Doc: Initial vuart configuration doc and images--4979

Signed-off-by: Deb Taylor <deb.taylor@intel.com>

doc/develop.rst

@@ -65,6 +65,7 @@ Enable ACRN Features
    tutorials/rtvm_workload_design_guideline
    tutorials/sgx_virtualization
    tutorials/virtio_i2c
+   tutorials/vuart_configuration
    tutorials/skl-nuc
    tutorials/using_cat_on_up2
    tutorials/using_sbl_on_up2

doc/tutorials/vuart_configuration.rst

@@ -0,0 +1,237 @@
+.. _vuart_config:
+
+vUART Configuration
+###################
+
+Introduction
+============
+
+The virtual universal asynchronous receiver-transmitter (vUART) supports two functions: one is the console, the other is communication. vUART only works on a single function.
+
+Currently, only two vUARTs configurations are added to the `/hypervisor/scenarios/<xxx>/vm_configuration.c` file, but you can change the value in it.
+
+.. code-block:: none
+
+                .vuart[0] = {
+                        .type = VUART_LEGACY_PIO,
+                        .addr.port_base = INVALID_COM_BASE,
+                },
+                .vuart[1] = {
+                        .type = VUART_LEGACY_PIO,
+                        .addr.port_base = INVALID_COM_BASE,
+                }
+
+**vuart[0]** is initiated as the **console** port.
+
+**vuart[1]** is initiated as a **communication** port.
+
+Console enable list
+===================
+
++-----------------+-----------------------+--------------------+----------------+----------------+
+| Scenarios       | vm0                   | vm1                | vm2            | vm3            |
++=================+=======================+====================+================+================+
+| SDC             | SOS (vuart enable)    | Post-launched      | Post-launched  |                |
++-----------------+-----------------------+--------------------+----------------+----------------+
+| SDC2            | SOS (vuart enable)    | Post-launched      |                | Post-launched  |
++-----------------+-----------------------+--------------------+----------------+----------------+
+| Hybrid          | Pre-launched (Zephyr) | SOS (vuart enable) | Post-launched  |                |
+|                 | (vuart enable)        |                    |                |                |
++-----------------+-----------------------+--------------------+----------------+----------------+
+| Industry        | SOS (vuart enable)    | Post-launched      | Post-launched  | Post-launched  |
+|                 |                       |                    | (vuart enable) |                |
++-----------------+-----------------------+--------------------+----------------+----------------+
+| Logic_partition | Pre-launched          | Pre-launched RTVM  | Post-launched  |                |
+|                 | (vuart enable)        | (vuart enable)     | RTVM           |                |
++-----------------+-----------------------+--------------------+----------------+----------------+
+
+How to configure a console port
+===============================
+
+To enable the console port for a VM, change only the port_base and irq. If the irq number has been used in your system (`cat /proc/interrupt`), choose another irq number. If you set the .irq =0, the vuart will work in polling mode.
+
+- COM1_BASE (0x3F8) + COM1_IRQ(4)
+- COM2_BASE (0x2F8) + COM2_IRQ(3)
+- COM3_BASE (0x3E8) + COM3_IRQ(6)
+- COM4_BASE (0x2E8) + COM4_IRQ(7)
+
+Example:
+
+.. code-block:: none
+
+   .vuart[0] = {
+                        .type = VUART_LEGACY_PIO,
+                        .addr.port_base = COM1_BASE,
+                        .irq = COM1_IRQ,
+                },
+
+How to configure a communication port
+=====================================
+
+To enable the communication port, configure vuart[1] in the two VMs that want to communicate.
+
+The port_base and irq should not repeat with the vuart[0] in the same VM.
+
+**t_vuart.vm_id** is the target VM's vm_id, start from 0. (0 means VM0)
+
+**t_vuart.vuart_id** is the target vuart index in the target VM. start from 1. (1 means vuart[1])
+
+Example:
+
+.. code-block:: none
+
+   /* VM0 */
+   ...
+   /* VM1 */
+   .vuart[1] = {
+                        .type = VUART_LEGACY_PIO,
+                        .addr.port_base = COM2_BASE,
+                        .irq = COM2_IRQ,
+                        .t_vuart.vm_id = 2U,
+                        .t_vuart.vuart_id = 1U,
+                },
+   ...
+   /* VM2 */
+   .vuart[1] = {
+                        .type = VUART_LEGACY_PIO,
+                        .addr.port_base = COM2_BASE,
+                        .irq = COM2_IRQ,
+                        .t_vuart.vm_id = 1U,
+                        .t_vuart.vuart_id = 1U,
+                },
+
+Communication vUART enable list
+===============================
+
++-----------------+-----------------------+--------------------+---------------------+----------------+
+| Scenarios       | vm0                   | vm1                | vm2                 | vm3            |
++=================+=======================+====================+=====================+================+
+| SDC             | SOS                   | Post-launched      | Post-launched       |                |
++-----------------+-----------------------+--------------------+---------------------+----------------+
+| SDC2            | SOS                   | Post-launched      | Post-launched       | Post-launched  |
++-----------------+-----------------------+--------------------+---------------------+----------------+
+| Hybrid          | Pre-launched (Zephyr) | SOS                | Post-launched       |                |
+|                 | (vuart enable COM2)   | (vuart enable COM2)|                     |                |
++-----------------+-----------------------+--------------------+---------------------+----------------+
+| Industry        | SOS                   | Post-launched      | Post-launched RTVM  | Post-launched  |
+|                 | (vuart enable COM2)   |                    | (vuart enable COM2) |                |
++-----------------+-----------------------+--------------------+---------------------+----------------+
+| Logic_partition | Pre-launched          | Pre-launched RTVM  |                     |                |
++-----------------+-----------------------+--------------------+---------------------+----------------+
+
+Launch script
+=============
+
+-  *-s 1:0,lpc -l com1,stdio*
+   This option is only needed for WaaG and vxWorks (and currently, OVMF). The common port is that they all depend on the ACPI table, but only acrn-dm can provide the ACPI table for UART.
+
+-  *-B " ....,console=ttyS0, ..."*
+   Add this to the kernel-based system.
+
+Test the communication port
+===========================
+
+After you have configured the communication port in hypervisor, you can access the corresponding port. For example, in Clear Linux:
+
+1. With `echo` and `cat`
+
+   On VM1: `# cat /dev/ttyS1`
+
+   On VM2: `# echo "test test" > /dev/ttyS1`
+
+   you can find the message from VM1 `/dev/ttyS1`.
+
+   If you are not sure which port is the communication port, you can run "dmesg | grep ttyS" under the Linux shell to check the base address. If it matches what you have set in the `vm_configuration.c` file, it is the correct port.
+
+
+#. With mimicom
+
+   Run `minicom -D /dev/ttyS1` on both VM1 and VM2 and enter `test` in VM1's minicom. The message should appear in VM2's minicom. Close the flow control in minicom.
+
+
+#. Limitations
+
+   -  The msg can not longer than 256 bytes.
+   -  This cannot be used to transfer files because flow control is not supported so data may lost.
+
+vUART design
+============
+
+**Console vUART**
+
+.. figure:: images/vuart-config-1.png
+   :align: center
+   :name: console-vuart
+
+**Communication vUART (between VM0 and VM1)**
+
+.. figure:: images/vuart-config-2.png
+   :align: center
+   :name: communication-vuart
+
+Com port configurations for Post-Launched VMs
+=============================================
+
+For a post-launched VM, the acrn-dm cmdline also provides a com port configuration:
+
+  `-s 1:0,lpc -l com1,stdio`
+
+This adds com1(0x3f8) and com2(0x2f8) modules in the Guest VM, including the ACPI info for these two ports.
+
+**Data Flow 1:**
+
+When the Post-launched VM is started only with the vUART enabled in the hypervisor configuration file, the data flow is shown as below:
+
+.. figure:: images/vuart-config-3.png
+   :align: center
+   :name: PLVM1-vuart
+
+**acrn-dm cmdline:** N/A
+
+.. code-block:: none
+
+   vm_configuration.c: .vuart[0] = {
+                                    .type = VUART_LEGACY_PIO,
+                                    .addr.port_base = COM1_BASE,
+                                    .irq = COM1_IRQ,
+                                   },
+
+**Data Flow 2:**
+
+When the Post-launched VM is started only with the acrn-dm cmdline of `-s 1:0,lpc -l com1,stdio`, the data flow is shown as below:
+
+.. figure:: images/vuart-config-4.png
+   :align: center
+   :name: PLVM2-vuart
+
+**acrn-dm cmdline:** `-s 1:0,lpc -l com1,stdio`
+
+.. code-block:: none
+
+   vm_configuration.c: .vuart[0] = {
+                                   .type = VUART_LEGACY_PIO,
+                                   .addr.port_base = INVALID_COM_BASE,
+                                   },
+
+**Date Flow 3:**
+
+When the Post-launched VM is started with both vUART enabled and the acrn-dm cmdline of `-s 1:0,lpc -l com1,stdio`, the data flow is show as below:
+
+.. figure:: images/vuart-config-5.png
+   :align: center
+   :name: PLVM3-vuart
+
+**acrn-dm cmdline:** `-s 1:0,lpc -l com1,stdio`
+
+.. code-block:: none
+
+   vm_configuration.c: .vuart[0] = {
+                                    .type = VUART_LEGACY_PIO,
+                                    .addr.port_base = COM1_BASE,
+                                    .irq = COM1_IRQ,
+                                   },
+
+.. note::
+   For operating systems such as vxWorks and Windows that depend on the ACPI table to probe the uart driver, only adding the vuart configuration in the hypervisor is not enough. Currently, we recommend that you use the configuration in Data Flow 3. This may be refined in the future.
+
+