| Message ID | d40643bf0730c2f227f2dfbc7985ba0b5f8878cf.1736942790.git.yann.dirson@vates.tech (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | [XEN] docs/sphinx: overview of serial consoles | expand |
On 15/01/2025 12:07 pm, Yann Dirson wrote: > --- > > Notes: > This is a very preliminar first draft for comments: > > - would this structuration be adequate? > > - Is my basic understanding correct, are those first enumerations > correct? (some of it come solely from console.txt, which has already > proven to be seriously outdated on many aspects) > > - is there some doc about the qemu/ioemu backend I missed? Is it able to > deal with PV consoles, or is it just for virtual UARTS? Consoles are probably one of the harder areas to get started. First, we need to distinguish between host consoles and guest consoles, because admin-guide/console could be either/both. Host consoles are mostly UARTs, but we have several flavours including usb2 and usb3 flavours. ARM has extensive early printk support, which RISC-V/PPC are borrowing too. Xen is also capable of using hypervisor-provided consoles too. For guest consoles, there's the plain CONSOLEIO hypercalls, and whether they do anything interesting depend on whether you're dom0 and/or the CONFIG_VERBOSE build setting. ARM has the ability to mutiplex output from different guests onto the host console. There's also the xenconsoled, things emulated by Qemu or other emulators, and even the in-Xen UART emulator currently on list. Then, for specific guests, they've got different console options available. e.g. Linux has a dedicated earlyconsole option for Xen (uses CONSOLEIO) as well as an hvc driver. And ideally we want all this information documented nicely, between "how do I set up debugging for my guest" and how do I write a driver for xenconsoled. ~Andrew
On 1/15/25 14:27, Andrew Cooper wrote: > On 15/01/2025 12:07 pm, Yann Dirson wrote: >> --- >> >> Notes: >> This is a very preliminar first draft for comments: >> >> - would this structuration be adequate? >> >> - Is my basic understanding correct, are those first enumerations >> correct? (some of it come solely from console.txt, which has already >> proven to be seriously outdated on many aspects) >> >> - is there some doc about the qemu/ioemu backend I missed? Is it able to >> deal with PV consoles, or is it just for virtual UARTS? > > Consoles are probably one of the harder areas to get started. > > First, we need to distinguish between host consoles and guest consoles, > because admin-guide/console could be either/both. OK, so this would rather be admin-guide/guest-console or even admin-guide/guest-serial-console. > > Host consoles are mostly UARTs, but we have several flavours including > usb2 and usb3 flavours. ARM has extensive early printk support, which > RISC-V/PPC are borrowing too. Xen is also capable of using > hypervisor-provided consoles too. Let's leave this for a later admin-guide/host-console :) > For guest consoles, there's the plain CONSOLEIO hypercalls, and whether > they do anything interesting depend on whether you're dom0 and/or the > CONFIG_VERBOSE build setting. I would see that part in something like guest-guide/serial-console. > ARM has the ability to mutiplex output > from different guests onto the host console. There's also the > xenconsoled, things emulated by Qemu or other emulators, and even the > in-Xen UART emulator currently on list. > > Then, for specific guests, they've got different console options > available. e.g. Linux has a dedicated earlyconsole option for Xen (uses > CONSOLEIO) as well as an hvc driver. Those definitely seem in the scope for the doc I was thinking about > And ideally we want all this information documented nicely, between "how > do I set up debugging for my guest" Debugging is an obvious superset, would hint to a "Guest debugging" section. Maybe it would be enough to add admin-guide/guest-debugging as intermediate level, but not be necessary to create an additional level of subdir for the contents? > and how do I write a driver for xenconsoled. That one does not really fit in either of admin-guide, guest-guide, and hypervisor-guide. Something like toolstack-implementation-guide? Yann Dirson | Vates Platform Developer XCP-ng & Xen Orchestra - Vates solutions web: https://vates.tech
diff --git a/docs/admin-guide/console.rst b/docs/admin-guide/console.rst new file mode 100644 index 0000000000..7f82a368f9 --- /dev/null +++ b/docs/admin-guide/console.rst @@ -0,0 +1,37 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Xen console +=========== + +Overview +-------- + +Xen provides several alternatives to provide the functionality of a +real machine's serial console, which are seen by the guest as one of: + +* PV consoles (``/dev/hvc$N`` in a Linux guest) +* Virtual SBSA UART (on ARM only?, ``/dev/ttyAMA0`` in a Linux guest) + +In dom0, different backends can be used to communicate with those +guest devices: + +* xenconsoled: a ``xenconsoled`` daemon in dom0 takes are of the + communication with the guest driver, and provides a pty interface. + The ``xenconsole`` tool can be used to connect to this pty. + Limitation: can only be used for the first PV or virtual UART + console. +* qemu? ioemu?: FIXME: describe + +Configuration +------------- + +TBW + +Gory details +------------ + +While not strictly useful for administration of a Xen machine, some +xenstore entries internal to the toolstack are visible, intermingled +with usual dom0/guest communication. + +TBW diff --git a/docs/admin-guide/index.rst b/docs/admin-guide/index.rst index 54e6f65de3..8a1ea1741e 100644 --- a/docs/admin-guide/index.rst +++ b/docs/admin-guide/index.rst @@ -6,3 +6,4 @@ Admin Guide .. toctree:: introduction microcode-loading + console
--- Notes: This is a very preliminar first draft for comments: - would this structuration be adequate? - Is my basic understanding correct, are those first enumerations correct? (some of it come solely from console.txt, which has already proven to be seriously outdated on many aspects) - is there some doc about the qemu/ioemu backend I missed? Is it able to deal with PV consoles, or is it just for virtual UARTS? docs/admin-guide/console.rst | 37 ++++++++++++++++++++++++++++++++++++ docs/admin-guide/index.rst | 1 + 2 files changed, 38 insertions(+) create mode 100644 docs/admin-guide/console.rst