[XEN PATCH] docs/sphinx: overview of serial consoles

["Yann Dirson" <yann.dirson@xxxxxxxxxx>]

---

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

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
-- 
2.39.5



Yann Dirson | Vates Platform Developer

XCP-ng & Xen Orchestra - Vates solutions

web: https://vates.tech