diff --git a/doc/developer-guides/images/virtio-console-arch.png b/doc/developer-guides/images/virtio-console-arch.png new file mode 100644 index 000000000..f3aa3e12c Binary files /dev/null and b/doc/developer-guides/images/virtio-console-arch.png differ diff --git a/doc/developer-guides/index.rst b/doc/developer-guides/index.rst index 6169e5561..4046025c4 100644 --- a/doc/developer-guides/index.rst +++ b/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 diff --git a/doc/developer-guides/virtio-console.rst b/doc/developer-guides/virtio-console.rst new file mode 100644 index 000000000..14f6a9e2a --- /dev/null +++ b/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 + +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 ```` to your use case:: + + -s n,virtio-console,@file:file_port= + +#. Add the console parameter to the guest OS kernel command line:: + + console=hvc0