1.. _vuart_config:
2
3Enable vUART Configurations
4###########################
5
6About vUART
7============
8
9A virtual universal asynchronous receiver/transmitter (vUART) can be a console
10port or a communication port.
11
12A vUART can exchange data between the hypervisor and a VM
13or between two VMs. Typical use cases of a vUART include:
14
15* Access the console of a VM from the hypervisor or another VM. A VM console,
16  when enabled by the OS in that VM, typically provides logs and a shell to
17  log in and execute commands. (vUART console)
18
19* Exchange user-specific, low-speed data between two VMs. (vUART communication)
20
21To the VMs, the vUARTs are presented in a 8250-compatible manner.
22
23To exchange high-speed (for example, megabytes or gigabytes per second) data
24between two VMs, you can use the inter-VM shared memory feature
25(IVSHMEM) instead.
26
27Dependencies and Constraints
28=============================
29
30Consider the following dependencies and constraints:
31
32* The OSes of the VMs need an 8250-compatible serial driver.
33
34* To access the hypervisor shell, you must have a physical UART.
35
36* Although a vUART is available to all kinds of VMs, you should not
37  enable a vUART to access the console of or exchange data with a real-time VM.
38  Exchanging data via a vUART imposes a performance
39  penalty that could delay the response of asynchronous events in real-time VMs.
40
41* A VM can have one console vUART and multiple communication vUARTs.
42
43* A single vUART connection cannot support both console and communication.
44
45Configuration Overview
46======================
47
48The :ref:`acrn_configurator_tool` lets you configure vUART connections. The
49following documentation is a general overview of the configuration process.
50
51To configure access to the console of a VM from the hypervisor, go to the **VM
52Basic Parameters > Console virtual UART type**, and select a COM port.
53
54.. image:: images/configurator-vuartconn02.png
55   :align: center
56   :class: drop-shadow
57
58To configure communication between two VMs, go to the **Hypervisor Global
59Settings > Basic Parameters > InterVM Virtual UART Connection**. Click **+**
60to add the first vUART connection.
61
62.. image:: images/configurator-vuartconn03.png
63   :align: center
64   :class: drop-shadow
65
66For the connection:
67
68#. Select the two VMs to connect.
69
70#. Select the vUART type, either Legacy or PCI.
71
72#. If you select Legacy, the tool displays a virtual I/O address field for each
73   VM. If you select PCI, the tool displays a virtual Board:Device.Function
74   (BDF) address field for each VM. In both cases, you can enter an address or
75   leave it blank. If the field is blank, the tool provides an address when the
76   configuration is saved.
77
78To add another connection, click **+** on the right side of an existing
79connection. Or click **-** to delete a connection.
80
81   .. note::
82
83      The release v3.0+ ACRN Configurator assigns COM2 (I/O address ``0x2F8``) to
84      the S5 feature. A conflict will occur if you assign ``0x2F8`` to another
85      connection. In our example, we'll use COM3 (I/O address ``0x3E8``).
86
87.. image:: images/configurator-vuartconn01.png
88   :align: center
89   :class: drop-shadow
90
91
92Example Configuration
93=====================
94
95The following steps show how to configure and verify a vUART
96connection between two VMs. The example extends the information provided in the
97:ref:`gsg`.
98
99#. In the ACRN Configurator, create a shared scenario with a Service VM and one
100   post-launched User VM.
101
102#. Go to **Hypervisor Global Settings > Basic Parameters > InterVM Virtual UART
103   Connection**.
104
105   a. Click **+** to add a vUART connection.
106
107   #. Select the Service VM (ACRN_Service_VM) and the post-launched User VM
108      (POST_STD_VM1).
109
110   #. For the vUART type, this example uses ``Legacy``.
111
112   #. For the virtual I/O address, this example uses ``0x3E8``.
113
114   .. image:: images/configurator-vuartconn01.png
115      :align: center
116      :class: drop-shadow
117
118#. Save the scenario and launch script.
119
120#. Build ACRN, copy all the necessary files from the development computer to the
121   target system, and launch the Service VM and post-launched User VM.
122
123#. To verify the connection:
124
125   a. In the Service VM, check the communication port via the ``dmesg | grep
126      tty`` command. In this example, we know the port is ``ttyS1`` because the
127      I/O address matches the address in the ACRN Configurator.
128
129      .. code-block:: console
130         :emphasize-lines: 7
131
132         root@10239146120sos-dom0:~# dmesg |grep tty
133         [    0.000000] Command line: root=/dev/nvme0n1p2 idle=halt rw rootwait console=ttyS0 console=tty0 earlyprintk=serial,ttyS0,115200 cons_timer_check consoleblank=0 no_timer_check quiet loglevel=3 i915.nuclear_pageflip=1 nokaslr i915.force_probe=* i915.enable_guc=0x7 maxcpus=16 hugepagesz=1G hugepages=26 hugepagesz=2M hugepages=388  root=PARTUUID=25302f3f-5c45-4ba4-a811-3de2b64ae6f6
134         [    0.038630] Kernel command line: root=/dev/nvme0n1p2 idle=halt rw rootwait console=ttyS0 console=tty0 earlyprintk=serial,ttyS0,115200 cons_timer_check consoleblank=0 no_timer_check quiet loglevel=3 i915.nuclear_pageflip=1 nokaslr i915.force_probe=* i915.enable_guc=0x7 maxcpus=16 hugepagesz=1G hugepages=26 hugepagesz=2M hugepages=388  root=PARTUUID=25302f3f-5c45-4ba4-a811-3de2b64ae6f6
135         [    0.105303] printk: console [tty0] enabled
136         [    0.105319] printk: console [ttyS0] enabled
137         [    1.391979] 00:03: ttyS0 at I/O 0x3f8 (irq = 4, base_baud = 115200) is a 16550A
138         [    1.649819] serial8250: ttyS1 at I/O 0x3e8 (irq = 5, base_baud = 115200) is a 16550A
139         [    3.394543] systemd[1]: Created slice system-serial\x2dgetty.slice.
140
141   #. Test vUART communication:
142
143      In the Service VM, run the following command to write ``acrn`` to the
144      communication port:
145
146      .. code-block:: console
147
148         root@10239146120sos-dom0:~/kino# echo "acrn" > /dev/ttyS1
149
150      In the User VM, read the communication port to confirm that ``acrn`` was
151      received:
152
153      .. code-block:: console
154
155         $ root@intel-corei7-64:~# cat /dev/ttyS1
156         acrn
157
158Learn More
159==========
160
161ACRN supports multiple inter-VM communication methods. For a comparison, see
162:ref:`inter-vm_communication`.
163
164For details on ACRN vUART high-level design, see:
165
166* :ref:`hv-console-shell-uart`
167* :ref:`vuart_virtualization`
168* :ref:`uart_virtualization`
169