Skip to content

Commit defac8d

Browse files
dbkinderwenlingz
dbkinder
authored and
wenlingz
committed
doc: apply edits to SDC2 scenario doc
Update merged PR #3463 with format and wording improvements. (Not linked yet into the document navigation) Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
1 parent da744ac commit defac8d

File tree

2 files changed

+125
-117
lines changed

2 files changed

+125
-117
lines changed

‎doc/develop.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ Configuration Tutorials
2222
tutorials/using_partition_mode_on_nuc
2323
tutorials/using_partition_mode_on_up2
2424

25+
.. tutorials/using_sdc2_mode_on_nuc
26+
2527
User VM Tutorials
2628
*****************
2729

‎doc/tutorials/using_sdc2_mode_on_nuc.rst

Lines changed: 123 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -1,162 +1,168 @@
1+
:orphan:
2+
13
.. _using_sdc2_mode_on_nuc:
24

35
Launch Two User VMs on NUC using SDC2 Scenario
46
##############################################
57

6-
ACRN hypervisor supports new SDC2 (Software Defined Cockpit) scenario
7-
since the tag ``acrn-2019w29.5-140000p``. In SDC2 scenario,
8-
up to three User VMs (e.g. Clear Linux + Ubuntu) can be launched from
9-
the Service VM. This tutorial provides step by step instructions on how
10-
to enable the ACRN hypervisor SDC2 scenario on Intel NUC to activate
11-
two post-launched VMs running Linux based guest OSes. The same process
12-
can be applied to launch the third Linux VM as well.
8+
Starting with the ACRN v1.2 release, the ACRN hypervisor supports a new
9+
Software Defined Cockpit scenario SDC2, where up to three User VMs
10+
running potentially different OSes, can be launched from the Service VM.
11+
12+
This tutorial provides step-by-step instructions for enabling this SDC2
13+
scenario on an Intel NUC and activate two post-launched User VMs. One of
14+
these User VMs will be running Clear Linux, the other Ubuntu. The same
15+
process can be applied to launch a third Linux VM as well.
1316

1417
ACRN Service VM Setup
1518
*********************
1619

17-
Refer to the steps in :ref:`getting-started-apl-nuc` to set up ACRN on
18-
Intel NUC. The target device must be capable of launching a Clear Linux User VM
19-
as a starting point.
20+
Follow the steps in :ref:`getting-started-apl-nuc` to set up ACRN on an
21+
Intel NUC. The target device must be capable of launching a Clear Linux
22+
User VM as a starting point.
2023

2124
Re-build ACRN UEFI Executable
2225
*****************************
2326

24-
The ACRN prebuilt UEFI executable ``acrn.efi`` is compiled for SDC scenario
25-
by default, in which only one post-launched VM is supported.
26-
To activate more than one post-launched VM, you need to enable the SDC2
27-
scenario and rebuild the UEFI executable with the following steps:
27+
The ACRN prebuilt UEFI executable ``acrn.efi`` is compiled for the
28+
single post-launched VM ``SDC scenario`` by default. To activate additional
29+
post-launched VMs, you need to enable the ``SDC2 scenario`` and rebuild
30+
the UEFI executable using the following steps:
2831

2932
#. Refer to :ref:`getting-started-building` to set up the development environment
30-
for re-compiling the UEFI executable from ACRN source tree.
33+
for re-compiling the UEFI executable from the ACRN source tree.
3134

32-
#. Enter the ``hypervisor`` directory under the ACRN source tree to
33-
reconfigure the ACRN hypervisor for SDC2 scenario. The following example
34-
picks up the configurations for ``kbl-nuc-i7`` board as a template,
35-
you can specify other board type which is closed to your target system.
35+
#. Enter the ``hypervisor`` directory under the ACRN source tree and use
36+
menuconfig to reconfigure the ACRN hypervisor for SDC2 scenario. The
37+
following example starts with the configurations for the
38+
``kbl-nuc-i7`` board as a template. You can specify another board type
39+
which is closer to your target system.
3640

37-
.. code-block:: bash
41+
.. code-block:: bash
3842
39-
$ cd hypervisor/
40-
$ make defconfig BOARD=kbl-nuc-i7
41-
$ make menuconfig
43+
$ cd hypervisor/
44+
$ make defconfig BOARD=kbl-nuc-i7
45+
$ make menuconfig
4246
43-
.. figure:: images/sdc2-defconfig.png
44-
:align: center
45-
:width: 400px
46-
:name: Reconfigure the ACRN hypervisor
47+
.. figure:: images/sdc2-defconfig.png
48+
:align: center
49+
:width: 600px
50+
:name: Reconfigure the ACRN hypervisor
4751

4852
#. Select ``Software Defined Cockpit 2`` option for the **ACRN Scenario** configuration:
4953

50-
.. figure:: images/sdc2-selected.png
51-
:align: center
52-
:width: 400px
53-
:name: Select the SDC2 scenario option
54+
.. figure:: images/sdc2-selected.png
55+
:align: center
56+
:width: 600px
57+
:name: Select the SDC2 scenario option
5458

5559
#. Press :kbd:`D` to save the minimum configurations to a default file ``defconfig``,
5660
then press :kbd:`Q` to quit the menuconfig script.
5761

58-
.. figure:: images/sdc2-save-mini-config.png
59-
:align: center
60-
:width: 400px
61-
:name: Save the customized configurations
62+
.. figure:: images/sdc2-save-mini-config.png
63+
:align: center
64+
:width: 600px
65+
:name: Save the customized configurations
6266

6367
#. Create a new BOARD configuration (say ``mydevice``) with the SDC2
64-
scenario enabled. Replace the following ``kbl-nuc-i7`` soft linked target
65-
by the board type you specified in the previous step:
68+
scenario you just enabled. Replace the following ``kbl-nuc-i7`` soft
69+
linked target by the board type you specified in the previous step (if
70+
different):
6671

67-
.. code-block:: bash
72+
.. code-block:: bash
6873
69-
$ cp defconfig arch/x86/configs/mydevice.config
70-
$ ln -s kbl-nuc-i7 arch/x86/configs/mydevice
74+
$ cp defconfig arch/x86/configs/mydevice.config
75+
$ ln -s kbl-nuc-i7 arch/x86/configs/mydevice
7176
7277
#. Go to the root of ACRN source tree to build the ACRN UEFI executable
7378
with the customized configurations:
7479

75-
.. code-block:: bash
80+
.. code-block:: bash
7681
77-
$ cd ..
78-
$ make FIRMWARE=uefi BOARD=mydevice
82+
$ cd ..
83+
$ make FIRMWARE=uefi BOARD=mydevice
7984
8085
#. Copy the generated ``acrn.efi`` executable to the ESP partition.
81-
You may need to mount the ESP partition if it's not mounted.
86+
(You may need to mount the ESP partition if it's not mounted.)
8287

83-
.. code-block:: bash
88+
.. code-block:: bash
8489
85-
$ sudo mount /dev/sda1 /boot
86-
$ sudo cp build/hypervisor/acrn.efi /boot/EFI/acrn/acrn.efi
90+
$ sudo mount /dev/sda1 /boot
91+
$ sudo cp build/hypervisor/acrn.efi /boot/EFI/acrn/acrn.efi
8792
8893
#. Reboot the ACRN hypervisor and the Service VM.
8994

9095
Launch User VMs with predefined UUIDs
9196
*************************************
9297

93-
In SDC2 scenario, VMs launched by the ACRN device model ``acrn-dm``
94-
must match the following UUIDs. You will have to add the ``-U`` parameter
95-
to the ``launch_uos.sh`` script, in order to attach to specific VM through
96-
``acrn-dm``.
97-
98-
* d2795438-25d6-11e8-864e-cb7a18b34643
99-
* 495ae2e5-2603-4d64-af76-d4bc5a8ec0e5
100-
* 38158821-5208-4005-b72a-8a609e4190d0
101-
102-
For example, the following code snippet is used to launch the VM1:
103-
104-
.. code-block:: none
105-
:emphasize-lines: 9
106-
107-
acrn-dm -A -m $mem_size -c $2 -s 0:0,hostbridge -s 1:0,lpc -l com1,stdio \
108-
-s 2,pci-gvt -G "$3" \
109-
-s 5,virtio-console,@pty:pty_port \
110-
-s 6,virtio-hyper_dmabuf \
111-
-s 3,virtio-blk,clear-27550-kvm.img \
112-
-s 4,virtio-net,tap0 \
113-
$logger_setting \
114-
--mac_seed $mac_seed \
115-
-U d2795438-25d6-11e8-864e-cb7a18b34643 \
116-
-k /usr/lib/kernel/default-iot-lts2018 \
117-
-B "root=/dev/vda3 rw rootwait maxcpus=$2 nohpet console=tty0 console=hvc0 \
118-
console=ttyS0 no_timer_check ignore_loglevel log_buf_len=16M \
119-
consoleblank=0 tsc=reliable i915.avail_planes_per_pipe=$4 \
120-
i915.enable_hangcheck=0 i915.nuclear_pageflip=1 i915.enable_guc_loading=0 \
121-
i915.enable_guc_submission=0 i915.enable_guc=0" $vm_name
122-
123-
Likewise, the following code snippet specifies a separate UUID to launch the VM2.
124-
125-
.. code-block:: none
126-
:emphasize-lines: 2,6,10
127-
128-
acrn-dm -A -m $mem_size -c $2 -s 0:0,hostbridge -s 1:0,lpc -l com1,stdio \
129-
-s 2,pci-gvt -G "$3" \
130-
-s 5,virtio-console,@pty:pty_port \
131-
-s 6,virtio-hyper_dmabuf \
132-
-s 3,virtio-blk,ubuntu-16.04.img \
133-
-s 4,virtio-net,tap1 \
134-
-s 7,virtio-rnd \
135-
$logger_setting \
136-
--mac_seed $mac_seed \
137-
-U 495ae2e5-2603-4d64-af76-d4bc5a8ec0e5 \
138-
-k /usr/lib/kernel/default-iot-lts2018 \
139-
-B "root=/dev/vda rw rootwait maxcpus=$2 nohpet console=tty0 console=hvc0 \
140-
console=ttyS0 no_timer_check ignore_loglevel log_buf_len=16M \
141-
consoleblank=0 tsc=reliable i915.avail_planes_per_pipe=$4 \
142-
i915.enable_hangcheck=0 i915.nuclear_pageflip=1 i915.enable_guc_loading=0 \
143-
i915.enable_guc_submission=0 i915.enable_guc=0" $vm_name
144-
145-
.. note::
146-
In addition to a different predefined UUID, you also need to specify
147-
a different network tap device (e.g. ``tap1``) to connect the VM2 to
148-
the network.
149-
150-
.. note::
151-
i915 GPU supports three hardware pipes to drive the displays,
152-
however only certain products design with circuitry to connect to
153-
three external displays.
154-
On a system supports up to two external displays, since the primary
155-
display has been assigned to the Service VM at boot time, you may
156-
remove the ``-s 2,pci-gvt -G "$3"`` options in one of the previous
157-
scripts to completely disable the GVT-g feature from that particular VM.
158-
Refer the :ref:`APL_GVT-g-hld` for detailed information.
159-
160-
.. figure:: images/sdc2-launch-2-laag.png
161-
:align: center
162-
:name: Running 2 Linux UOSes
98+
In the SDC2 scenario, each User VMs launched by the ACRN device model ``acrn-dm``
99+
must use one of the following UUIDs:
100+
101+
* ``d2795438-25d6-11e8-864e-cb7a18b34643``
102+
* ``495ae2e5-2603-4d64-af76-d4bc5a8ec0e5``
103+
* ``38158821-5208-4005-b72a-8a609e4190d0``
104+
105+
As shown below, add the ``-U`` parameter to the ``launch_uos.sh`` script
106+
to attach the specific VM through an ``acrn-dm`` command. For example, the
107+
following code snippet is used to launch VM1:
108+
109+
.. code-block:: none
110+
:emphasize-lines: 9
111+
112+
acrn-dm -A -m $mem_size -c $2 -s 0:0,hostbridge -s 1:0,lpc -l com1,stdio \
113+
-s 2,pci-gvt -G "$3" \
114+
-s 5,virtio-console,@pty:pty_port \
115+
-s 6,virtio-hyper_dmabuf \
116+
-s 3,virtio-blk,clear-27550-kvm.img \
117+
-s 4,virtio-net,tap0 \
118+
$logger_setting \
119+
--mac_seed $mac_seed \
120+
-U d2795438-25d6-11e8-864e-cb7a18b34643 \
121+
-k /usr/lib/kernel/default-iot-lts2018 \
122+
-B "root=/dev/vda3 rw rootwait maxcpus=$2 nohpet console=tty0 console=hvc0 \
123+
console=ttyS0 no_timer_check ignore_loglevel log_buf_len=16M \
124+
consoleblank=0 tsc=reliable i915.avail_planes_per_pipe=$4 \
125+
i915.enable_hangcheck=0 i915.nuclear_pageflip=1 i915.enable_guc_loading=0 \
126+
i915.enable_guc_submission=0 i915.enable_guc=0" $vm_name
127+
128+
Likewise, the following code snippet specifies a different UUID and a
129+
different network tap device ``tap1`` to launch VM2 and connect VM2 to
130+
the network:
131+
132+
.. code-block:: none
133+
:emphasize-lines: 2,6,10
134+
135+
acrn-dm -A -m $mem_size -c $2 -s 0:0,hostbridge -s 1:0,lpc -l com1,stdio \
136+
-s 2,pci-gvt -G "$3" \
137+
-s 5,virtio-console,@pty:pty_port \
138+
-s 6,virtio-hyper_dmabuf \
139+
-s 3,virtio-blk,ubuntu-16.04.img \
140+
-s 4,virtio-net,tap1 \
141+
-s 7,virtio-rnd \
142+
$logger_setting \
143+
--mac_seed $mac_seed \
144+
-U 495ae2e5-2603-4d64-af76-d4bc5a8ec0e5 \
145+
-k /usr/lib/kernel/default-iot-lts2018 \
146+
-B "root=/dev/vda rw rootwait maxcpus=$2 nohpet console=tty0 console=hvc0 \
147+
console=ttyS0 no_timer_check ignore_loglevel log_buf_len=16M \
148+
consoleblank=0 tsc=reliable i915.avail_planes_per_pipe=$4 \
149+
i915.enable_hangcheck=0 i915.nuclear_pageflip=1 i915.enable_guc_loading=0 \
150+
i915.enable_guc_submission=0 i915.enable_guc=0" $vm_name
151+
152+
153+
.. note::
154+
The i915 GPU supports three hardware pipes to drive the displays,
155+
however only certain products are designed with circuitry needed to
156+
connect to three external displays. On a system supporting two external
157+
displays, because the primary display is assigned to the Service VM at
158+
boot time, you may remove the ``-s 2,pci-gvt -G "$3"`` options in one of
159+
the previous VM-launching example scripts to completely disable the
160+
GVT-g feature for that VM. Refer the :ref:`APL_GVT-g-hld` for
161+
detailed information.
162+
163+
Here's a screen shot of the resuting launch of the Clear Linux and Ubuntu
164+
User VMs, with a Clear Linux Service VM:
165+
166+
.. figure:: images/sdc2-launch-2-laag.png
167+
:align: center
168+
:name: Launching two User VMs, running Clear Linux and Ubuntu

0 commit comments

Comments
 (0)