doc: add virtio-console HLD document

transcode, review, and publish virtio-console developer-guides doc

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>

doc/developer-guides/index.rst

@@ -21,9 +21,10 @@ specific areas within the ACRN hypervisor system.
 
    memmgt-hld.rst
    virtio-hld.rst
+   virtio-console.rst
+   uart-virtualization.rst
    ACPI-virt-hld.rst
    APL_GVT-g-hld.rst
-   uart-virtualization.rst
    GVT-G-porting.rst
 
 Contributing to the project

doc/developer-guides/virtio-console.rst

@@ -0,0 +1,183 @@
+.. virtio-console:
+
+Virtio-Console High-Level design
+################################
+
+The Virtio-console is a simple device for data input and output.  The
+console's virtio device ID is ``3`` and can have from 1 to 16 ports.
+Each port has a pair of input and output virtqueues used to communicate
+information between the Front End (FE) and Back end (BE) drivers.
+Currently the size of each virtqueue is 64 (configurable in the source
+code).  The FE driver will place empty buffers for incoming data onto
+the receiving virtqueue, and enqueue outgoing characters onto the
+transmitting virtqueue.
+
+A Virtio-console device has a pair of control IO virtqueues as well. The
+control virtqueues are used to communicate information between the
+device and the driver, including: ports being opened and closed on
+either side of the connection, indication from the host about whether a
+particular port is a console port, adding new ports, port
+hot-plug/unplug, indication from the guest about whether a port or a
+device was successfully added, or a port opened or closed.
+
+The virtio-console architecture diagram in ACRN is shown below.
+
+.. figure:: images/virtio-console-arch.png
+   :align: center
+   :width: 700px
+   :name: virtio-console-arch
+
+   Virtio-console architecture diagram
+
+
+Virtio-console is implemented as a virtio legacy device in the ACRN device
+model (DM), and is registered as a PCI virtio device to the guest OS. No changes
+are required in the frontend Linux virtio-console except that the guest
+(UOS) kernel should be built with ``CONFIG_VIRTIO_CONSOLE=y``.
+
+Currently the feature bits supported by the BE device are:
+
+.. list-table:: Feature bits supported by BE drivers
+   :widths: 30 50
+   :header-rows: 0
+
+   * - VTCON_F_SIZE(bit 0)
+     - configuration columns and rows are valid.
+   * - VTCON_F_MULTIPORT(bit 1)
+     - device supports multiple ports, and control virtqueues will be used.
+   * - VTCON_F_EMERG_WRITE(bit 2)
+     - device supports emergency write.
+
+Virtio-console supports redirecting guest output to various backend
+devices. Currently the following backend devices are supported in ACRN
+device model: STDIO, TTY, PTY and regular file.
+
+The device model configuration command syntax for virtio-console is::
+
+   virtio-console,[@]stdio|tty|pty|file:portname[=portpath]\
+      [,[@]stdio|tty|pty|file:portname[=portpath]]
+
+-  Preceding with ``@`` marks the port as a console port, otherwise it is a
+   normal virtio serial port
+
+-  The ``portpath`` can be omitted when backend is stdio or pty
+
+-  The ``stdio/tty/pty`` is tty capable, which means :kbd:`TAB` and
+   :kbd:`BACKSPACE` are supported, as on a regular terminal
+
+-  When tty is used, please make sure the redirected tty is sleeping,
+   (e.g., by ``sleep 2d`` command), and will not read input from stdin before it
+   is used by virtio-console to redirect guest output.
+
+-  Claiming multiple virtio serial ports as consoles is supported,
+   however the guest Linux OS will only use one of them, through the
+   ``console=hvcN`` kernel parameter. For example, the following command
+   defines two backend ports, which are both console ports, but the frontend
+   driver will only use the second port named ``pty_port`` as its hvc
+   console (specified by ``console=hvc1`` in the kernel command
+   line)::
+
+      -s n,virtio-console,@tty:tty_port=/dev/pts/0,@pty:pty_port \
+      -B "root=/dev/vda2 rw rootwait maxcpus=$2 nohpet console=hvc1 console=ttyS0 ..."
+
+
+Console Backend Use Cases
+*************************
+
+The following sections elaborate on each backend.
+
+STDIO
+=====
+
+1. Add a pci slot to the device model (``acrn-dm``) command line::
+
+      -s n,virtio-console,@stdio:stdio_port
+
+#. Add the ``console`` parameter to the guest OS kernel command line::
+
+     console=hvc0
+
+PTY
+===
+
+1. Add a pci slot to the device model (``acrn-dm``) command line::
+
+     -s n,virtio-console,@pty:pty_port
+
+#. Add the ``console`` parameter to the guest os kernel command line::
+
+     console=hvc0
+
+   One line of information, such as shown below, will be printed in the terminal
+   after ``acrn-dm`` is launched (``/dev/pts/0`` may be different,
+   depending on your use case):
+
+   .. code-block: console
+
+      virt-console backend redirected to /dev/pts/0
+
+#. Use a terminal emulator, such as minicom or screen, to connect to the
+   tty node::
+
+     minicom -D /dev/pts/0
+
+   or ::
+
+     screen /dev/pts/0
+
+TTY
+===
+
+1. Identify your tty that will be used as the UOS console:
+
+   - If you're connected to your device over the network via ssh, use
+     the linux ``tty`` command, and it will report the node (may be
+     different in your use case)::
+
+        /dev/pts/0
+        sleep 2d
+
+   - If you do not have network access to your device, use screen
+     to create a new tty::
+
+        screen
+        tty
+
+     you will see (depending on your use case)::
+
+        /dev/pts/0
+
+     Prevent the tty from responding by sleeping::
+
+        sleep 2d
+
+     and detach the tty by pressing :kbd:`CTRL-A` :kbd:`d`.
+
+#. Add a pci slot to the device model (``acrn-dm``)  command line
+   (changing the ``dev/pts/X`` to match your use case)::
+
+      -s n,virtio-console,@tty:tty_port=/dev/pts/X
+
+#. Add the console parameter to the guest OS kernel command line::
+
+      console=hvc0
+
+#. Go back to the previous tty.  For example, if you're using
+   ``screen``, use::
+
+      screen -ls
+      screen -r <pid_of_your_tty>
+
+FILE
+====
+
+The File backend only supports console output to a file (no input).
+
+1. Add a pci slot to the device model (``acrn-dm``) command line,
+   adjusting the ``</path/to/file>`` to your use case::
+
+      -s n,virtio-console,@file:file_port=</path/to/file>
+
+#. Add the console parameter to the guest OS kernel command line::
+
+      console=hvc0