github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-06-29 16:58:10 +00:00
Code Issues Projects Releases Wiki Activity

doc: Editorial changes to DM params doc

Browse Source 
Signed-off-by: Reyes, Amy <amy.reyes@intel.com>
This commit is contained in:
Reyes, Amy 2022-09-27 16:14:30 -07:00 committed by Amy Reyes
parent 4a7c81a449
commit 31331a6390
1 changed files with 187 additions and 169 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

356
doc/user-guides/acrn-dm-parameters.rst
View File

@ -3,20 +3,20 @@
Device Model Parameters and Launch Script Device Model Parameters and Launch Script
######################################### #########################################
Hypervisor Device Model (DM) is a QEMU-like application in the Service The Device Model (DM) ``acrn-dm`` is a QEMU-like application in the Service
VM responsible for creating a User VM and then performing devices VM responsible for creating a post-launched User VM and then performing device
emulation based on command line configurations, as introduced in emulation based on command-line configurations, as introduced in
the :ref:`hld-devicemodel`. ACRN Configurator generates launch scripts for the :ref:`hld-devicemodel`. The ACRN Configurator generates launch scripts for
Post-launched VMs that include a call to the ``acrn-dm`` command with post-launched VMs that include a call to the ``acrn-dm`` command with
parameter values that were set in the configurator. Generally, you should not parameter values that were set in the Configurator. Generally, you should not
edit these launch scripts and change the parameters manually. Any edits you edit these launch scripts and change the parameters manually. Any edits you
make would be overwritten if you run the configurator again and save the make would be overwritten if you run the Configurator again and save the
configuration and launch scripts. configuration and launch scripts.
The rest of this document provides details about the ``acrn-dm`` parameters as a The rest of this document provides details about the ``acrn-dm`` parameters as a
reference, and should help you understand what the generated launch scripts reference, and should help you understand what the generated launch scripts
are doing. We also include information useful to ACRN contributors about how are doing. We also include information useful to ACRN contributors about how
setting in the scenario file, created by the configurator, are transformed settings in the scenario file, created by the Configurator, are transformed
into the launch script. into the launch script.
.. _acrn-dm_parameters: .. _acrn-dm_parameters:
@ -24,17 +24,17 @@ into the launch script.
Device Model Parameters Device Model Parameters
*********************** ***********************
Here are descriptions for each of these ``acrn-dm`` command line parameters: Here are descriptions for each of these ``acrn-dm`` command-line parameters:
``-B``, ``--bootargs <bootargs>`` ``-B``, ``--bootargs <bootargs>``
Set the User VM kernel command-line arguments. The maximum length is 1023. Set the User VM kernel command-line arguments. The maximum length is 1023
The bootargs string will be passed to the kernel as its cmdline. characters. The bootargs string will be passed to the kernel as its cmdline.
Example:: Example::
-B "loglevel=7" -B "loglevel=7"
specifies the kernel log level at 7 to specify the kernel log level at 7.
---- ----
@ -44,18 +44,17 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
---- ----
``-E``, ``--elf_file <elf image path>`` ``-E``, ``--elf_file <elf_image_path>``
This option is to define a static elf binary which could be loaded by DM. Define a static ELF binary for the User VM.
DM will run elf as guest of ACRN.
---- ----
``--enable_trusty`` ``--enable_trusty``
Enable trusty for guest. For Android guest OS, ACRN provides a VM Enable trusty for guest. For an Android guest OS, ACRN provides a VM
environment with two worlds: normal world and trusty world. The Android environment with two worlds: normal world and trusty world. The Android
OS runs in the normal world. The trusty OS and security sensitive OS runs in the normal world. The trusty OS and security sensitive
applications runs in the trusty world. The trusty world can see the memory applications run in the trusty world. The trusty world can see the memory
of normal world but not vice versa. See :ref:`trusty_tee` for more of the normal world but not vice versa. See :ref:`trusty_tee` for more
information. information.
By default, the trusty world is disabled. Use this option to enable it. By default, the trusty world is disabled. Use this option to enable it.
@ -68,8 +67,8 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
---- ----
``--intr_monitor <intr_monitor_params>`` ``--intr_monitor <intr_monitor_params>``
Enable interrupt storm monitor for User VM. Use this option to prevent an Enable an interrupt storm monitor for the User VM. Use this option to prevent
interrupt storm from the User VM. an interrupt storm from the User VM.
usage: ``--intr_monitor threshold/s probe-period(s) delay_time(ms) delay_duration(ms)`` usage: ``--intr_monitor threshold/s probe-period(s) delay_time(ms) delay_duration(ms)``
@ -77,19 +76,19 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
--intr_monitor 10000,10,1,100 --intr_monitor 10000,10,1,100
- ``10000``: interrupt rate larger than 10000/s will be treated as - ``10000``: Interrupt rate larger than 10000/s will be treated as an
interrupt storm interrupt storm.
- ``10``: use the last 10s of interrupt data to detect an interrupt storm - ``10``: Use the last 10s of interrupt data to detect an interrupt storm.
- ``1``: when interrupts are identified as a storm, the next interrupt - ``1``: When interrupts are identified as a storm, the next interrupt
will be delayed 1ms before being injected to the guest will be delayed 1ms before being injected to the guest.
- ``100``: after 100ms, we will cancel the interrupt injection delay and - ``100``: After 100ms, cancel the interrupt injection delay and
restore to normal. restore to normal.
---- ----
``-k``, ``--kernel <kernel_image_path>`` ``-k``, ``--kernel <kernel_image_path>``
Set the kernel (full path) for the User VM kernel. The maximum path length Set the kernel (full path) for the User VM kernel. The maximum path length
is 1023 characters. The DM handles bzImage image format. is 1023 characters. The DM supports bzImage image format.
usage: ``-k /path/to/your/kernel_image`` usage: ``-k /path/to/your/kernel_image``
@ -100,25 +99,30 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
---- ----
``-m``, ``--memsize <memory_size>`` ``-m``, ``--memsize <memory_size>``
Setup total memory size for User VM. Set the total memory size for the User VM.
memory_size format is: "<size>{K/k, B/b, M/m, G/g}", and size is an memory_size format is: ``<size>{K/k, B/b, M/m, G/g}``, and size is an
integer. integer.
usage: ``-m 4g``: set User VM memory to 4 gigabytes. Example::
-m 4g
to set the User VM memory to 4 gigabytes.
---- ----
``-r``, ``--ramdisk <ramdisk_image_path>`` ``-r``, ``--ramdisk <ramdisk_image_path>``
Set the ramdisk (full path) for the User VM. The maximum length is 1023. Set the RAM disk (full path) for the User VM. The maximum path length is 1023
The supported ramdisk format depends on your User VM kernel configuration. characters. The supported RAM disk format depends on your User VM kernel
configuration.
usage: ``-r /path/to/your/ramdisk_image`` usage: ``-r /path/to/your/ramdisk_image``
---- ----
``-s``, ``--pci_slot <slot_config>`` ``-s``, ``--pci_slot <slot_config>``
Setup PCI device configuration. Set the PCI device configuration.
slot_config format is:: slot_config format is::
@ -127,10 +131,10 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
Where: Where:
- ``slot`` is 0..31 - ``slot`` is 0..31.
- ``func`` is 0..7 - ``func`` is 0..7.
- ``emul`` is a string describing the type of PCI device, e.g. - ``emul`` is a string describing the type of PCI device, e.g.,
virtio-net virtio-net.
- ``config`` is an optional device-dependent string, used for - ``config`` is an optional device-dependent string, used for
configuration. configuration.
@ -139,20 +143,20 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
-s 7,xhci,1-2,2-2 -s 7,xhci,1-2,2-2
This configuration means the virtual xHCI will appear in PCI slot 7 This configuration means the virtual xHCI will appear in PCI slot 7
in User VM. Any physical USB device attached on 1-2 (bus 1, port 2) or in the User VM. Any physical USB device attached on 1-2 (bus 1, port 2) or
2-2 (bus 2, port 2) will be detected by User VM and be used as expected. To 2-2 (bus 2, port 2) will be detected by the User VM and be used as expected.
determine which bus and port a USB device is attached, you could run To determine the bus and port of a USB device, run ``lsusb -t``
``lsusb -t`` in Service VM. in the Service VM.
:: ::
-s 9,virtio-blk,/root/test.img -s 9,virtio-blk,/root/test.img
This adds virtual block in PCI slot 9 and uses ``/root/test.img`` as the This example adds a virtual block in PCI slot 9 and uses ``/root/test.img``
disk image. as the disk image.
For more information about emulated device types, see :ref:'emul_config'. For more information about emulated device types, see :ref:`emul_config`.
---- ----
@ -173,10 +177,10 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
--ovmf /usr/share/acrn/bios/OVMF.fd --ovmf /usr/share/acrn/bios/OVMF.fd
uses ``/usr/share/acrn/bios/OVMF.fd`` as the OVMF image uses ``/usr/share/acrn/bios/OVMF.fd`` as the OVMF image.
ACRN also supports using OVMF split images; ``OVMF_CODE.fd`` that contains ACRN also supports using OVMF split images; ``OVMF_CODE.fd`` contains
the OVMF firmware executable and ``OVMF_VARS.fd`` that contains the NV the OVMF firmware executable and ``OVMF_VARS.fd`` contains the NV
data store. data store.
usage:: usage::
@ -186,8 +190,8 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
ACRN supports the option "w" for OVMF. To preserve all changes in OVMF's ACRN supports the option "w" for OVMF. To preserve all changes in OVMF's
NV data store section, use this option to enable writeback mode. NV data store section, use this option to enable writeback mode.
Writeback mode is only enabled for the ``OVMF_VARS.fd`` file in case of For OVMF split images, writeback mode is only enabled for the
OVMF split images, the firmware executable (``OVMF_CODE.fd``) remains ``OVMF_VARS.fd`` file, and the firmware executable (``OVMF_CODE.fd``) remains
read-only. read-only.
usage:: usage::
@ -198,11 +202,11 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
.. _cpu_affinity: .. _cpu_affinity:
``--cpu_affinity <list of lapic_ids>`` ``--cpu_affinity <list_of_lapic_ids>``
comma-separated list of vCPUs assigned to this VM. Each CPU has a Local Programmable Comma-separated list of vCPUs assigned to this VM. Each CPU has a Local
Interrupt Controller (LAPIC). The unique ID of the LAPIC (lapic_id) is used to identify vCPU. Programmable Interrupt Controller (LAPIC). The unique ID of the LAPIC
The ``lapic_id`` for a vCPU can be found in the service VM file ``/proc/cpuinfo`` (lapic_id) is used to identify the vCPU. The ``lapic_id`` for a vCPU can be
identified as ``apicid``. found in the Service VM file ``/proc/cpuinfo`` identified as ``apicid``.
Example:: Example::
@ -213,36 +217,36 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
---- ----
``--virtio_poll <poll_interval>`` ``--virtio_poll <poll_interval>``
Enable virtio poll mode with poll interval xxx ns. Enable virtio poll mode with poll interval in nanoseconds.
Example:: Example::
--virtio_poll 1000000 --virtio_poll 1000000
enable virtio poll mode with poll interval 1ms. to enable virtio poll mode with poll interval of 1ms.
---- ----
``--acpidev_pt <HID>[,<UID>]`` ``--acpidev_pt <HID>[,<UID>]``
This option is to enable ACPI device passthrough support. The ``HID`` is a Enable ACPI device passthrough support. The ``HID`` is a
mandatory parameter for this option which is the Hardware ID of the ACPI mandatory parameter and is the Hardware ID of the ACPI
device. device.
The ``UID`` is an option and used to specify a particular instance of the The ``UID`` is an option and used to specify an instance of the
HID device, the default is 00. HID device, the default is 00.
Example:: Example::
--acpidev_pt MSFT0101,00 --acpidev_pt MSFT0101,00
To pass through a TPM (which HID is MSFT0101 and UID is 00) ACPI device to to pass through a TPM (HID is MSFT0101 and UID is 00) ACPI device to
a User VM. a User VM.
---- ----
``--mmiodev_pt <MMIO_Region>`` ``--mmiodev_pt <MMIO_Region>``
This option is to enable MMIO device passthrough support. The Enable MMIO device passthrough support. The
``MMIO_Region`` is a mandatory parameter for this option which is the MMIO ``MMIO_Region`` is a mandatory parameter and is the MMIO
resource of the MMIO device. The ``MMIO_Region`` needs to be the base resource of the MMIO device. The ``MMIO_Region`` needs to be the base
address followed by the length of the region, both separated by a comma. address followed by the length of the region, both separated by a comma.
@ -250,27 +254,27 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
--mmiodev_pt 0xFED40000,0x00005000 --mmiodev_pt 0xFED40000,0x00005000
To pass through a MMIO device to a User VM. The MMIO device has a MMIO to pass through a MMIO device to a User VM. The MMIO device has a MMIO
region. The base address of this region is 0xFED40000 and the size of the region. The base address of this region is 0xFED40000 and the size of the
region is 0x00005000. region is 0x00005000.
---- ----
``--vtpm2 <sock_path>`` ``--vtpm2 <sock_path>``
This option is to enable virtual TPM support. The sock_path is a mandatory Enable virtual TPM support. The ``sock_path`` is a mandatory
parameter for this option which is the path of swtpm socket fd. parameter and is the path of the swtpm socket fd.
---- ----
``--virtio_msi`` ``--virtio_msi``
This option forces virtio to use single-vector MSI. By default, any Force virtio to use single-vector MSI. By default, a
virtio-based devices will use MSI-X as its interrupt method. If you want virtio-based device uses MSI-X as its interrupt method. If you want
to use single-vector MSI interrupt, you can do so using this option. to use single-vector MSI, you can do so using this option.
---- ----
``--lapic_pt`` ``--lapic_pt``
This option is to create a VM with the local APIC (LAPIC) passed-through. Create a VM with the local APIC (LAPIC) passed-through.
With this option, a VM is created with ``LAPIC_PASSTHROUGH`` and With this option, a VM is created with ``LAPIC_PASSTHROUGH`` and
``IO_COMPLETION_POLLING`` mode. This option is typically used for hard ``IO_COMPLETION_POLLING`` mode. This option is typically used for hard
real-time scenarios. real-time scenarios.
@ -280,7 +284,7 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
---- ----
``--rtvm`` ``--rtvm``
This option is used to create a VM with real-time attributes. With this Create a VM with real-time attributes. With this
option, a VM is created with ``GUEST_FLAG_RT`` and option, a VM is created with ``GUEST_FLAG_RT`` and
``GUEST_FLAG_IO_COMPLETION_POLLING`` mode. This kind of VM is generally ``GUEST_FLAG_IO_COMPLETION_POLLING`` mode. This kind of VM is generally
used for soft real-time scenarios (without ``--lapic_pt``) or hard used for soft real-time scenarios (without ``--lapic_pt``) or hard
@ -293,10 +297,10 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
---- ----
``--logger_setting <console,level=4;disk,level=4;kmsg,level=3>`` ``--logger_setting <console,level=4;disk,level=4;kmsg,level=3>``
This option sets the level of logging that is used for each log channel. Set the level of logging that is used for each log channel.
The general format of this option is ``<log channel>,level=<log level>``. The general format of this option is ``<log channel>,level=<log level>``.
Different log channels are separated by a semi-colon (``;``). The various Different log channels are separated by a semi-colon (``;``). The various
log channels available are: ``console``, ``disk`` and ``kmsg``. The log log channels available are: ``console``, ``disk``, and ``kmsg``. The log
level ranges from 1 (``error``) up to 5 (``debug``). level ranges from 1 (``error``) up to 5 (``debug``).
By default, the log severity level is set to 4 (``info``). By default, the log severity level is set to 4 (``info``).
@ -304,8 +308,8 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
---- ----
``--windows`` ``--windows``
This option is used to run Windows User VMs. It supports Oracle Run Windows User VMs. This option supports Oracle
``virtio-blk``, ``virtio-net`` and ``virtio-input`` devices for Windows ``virtio-blk``, ``virtio-net``, and ``virtio-input`` devices for Windows
guests with secure boot. guests with secure boot.
usage:: usage::
@ -319,7 +323,7 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
---- ----
``--ssram`` ``--ssram``
This option enables Software SRAM passthrough to the VM. Enable Software SRAM passthrough to the VM.
usage:: usage::
@ -328,50 +332,52 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
---- ----
``--iasl <iasl_compiler_path>`` ``--iasl <iasl_compiler_path>``
Specify the path to ``iasl`` compiler on the target machine. Specify the path to the ``iasl`` compiler on the target machine.
If ``--iasl <iasl_compiler_path>`` is specified as the ``acrn-dm`` parameter, If ``--iasl <iasl_compiler_path>`` is specified as the ``acrn-dm`` parameter,
acrn-dm uses <iasl_compiler_path> as the path to the ``iasl`` compiler; acrn-dm uses ``<iasl_compiler_path>`` as the path to the ``iasl`` compiler;
otherwise, ``which iasl`` is used to detect where the ``iasl`` compiler is located. otherwise, ``which iasl`` is used to detect where the ``iasl`` compiler is located.
usage:: usage::
--iasl /usr/local/bin/iasl --iasl /usr/local/bin/iasl
uses ``/usr/local/bin/iasl`` as the path to the ``iasl`` compiler uses ``/usr/local/bin/iasl`` as the path to the ``iasl`` compiler.
.. _emul_config: .. _emul_config:
Emulated PCI Device Types Emulated PCI Device Types
**************************** ****************************
In the acrn-dm ``-s`` or ``--pci_slot`` command line parameter, there is a ``<slot_config>`` argument In the acrn-dm ``-s`` or ``--pci_slot`` command-line parameter, there is a
that contains a string describing the type of emulated PCI device, along with optional device-dependent ``<slot_config>`` argument that contains a string describing the type of
arguments used for configuration. Here is a table describing these emulated device types and arguments: emulated PCI device, along with optional device-dependent arguments used for
configuration. Here is a table describing these emulated device types and
arguments:
.. list-table:: Emulated PCI Device Types .. list-table:: Emulated PCI Device Types
:header-rows: 1 :header-rows: 1
:widths: 20 80 :widths: 20 80
* - PCI Device Type string * - PCI Device Type String
- Description - Description
* - ``xhci`` * - ``xhci``
- USB controller used to support USB 3.0 devices, (also supports USB 2.0 - USB controller used to support USB 3.0 devices (also supports USB 2.0
and USB 1.0 devices). Parameter ``<bus number>-<port number>`` should be and USB 1.0 devices). Parameter ``<bus number>-<port number>`` should be
added. The physical USB devices attached on the specified bus and port added. The physical USB devices attached on the specified bus and port
will be detected by User VM and used as expected, e.g., ``xhci,1-2,2-2``. will be detected by the User VM and used as expected, e.g., ``xhci,1-2,2-2``.
* - ``lpc`` * - ``lpc``
- Low Pin Count (LPC) bus is used to connect low speed devices to the CPU, - Low Pin Count (LPC) bus is used to connect low speed devices to the CPU,
for example a serial port, keyboard, or mouse. for example, a serial port, keyboard, or mouse.
* - ``igd-lpc`` * - ``igd-lpc``
- Windows graphic driver requires this virtualized LPC device to operate - Windows graphics driver requires this virtualized LPC device to operate
the display function. the display function.
* - ``ivshmem`` * - ``ivshmem``
- Inter-VM shared memory (ivshmem) virtualized PCI device used specifically - Inter-VM shared memory (IVSHMEM) virtualized PCI device used specifically
for shared memory between VMs. Parameters should be added with the format for shared memory between VMs. Parameters should be added with the format
``ivshmem,<shm_name>,<shm_size>``. ``<shm-name>`` specifies a shared memory ``ivshmem,<shm_name>,<shm_size>``. ``<shm-name>`` specifies a shared memory
name, and must be listed in ``hv.FEATURES.IVSHMEM.IVSHMEM_REGION`` name, and must be listed in ``hv.FEATURES.IVSHMEM.IVSHMEM_REGION``
@ -382,7 +388,7 @@ arguments used for configuration. Here is a table describing these emulated dev
- Advanced Host Controller Interface provides advanced features to access - Advanced Host Controller Interface provides advanced features to access
Serial ATA (SATA) storage devices, such as a hard disk. Parameter Serial ATA (SATA) storage devices, such as a hard disk. Parameter
``<type:><filepath>*`` should be added: ``type`` could be ``<type:><filepath>*`` should be added: ``type`` could be
``hd`` (harddisk) or ``cd`` (CD-ROM). ``<filepath>`` is the path for the ``hd`` (hard disk) or ``cd`` (CD-ROM). ``<filepath>`` is the path for the
backend file and could be a partition name or a regular file, e.g., backend file and could be a partition name or a regular file, e.g.,
``ahci,hd:/dev/sda``. ``ahci,hd:/dev/sda``.
@ -390,52 +396,56 @@ arguments used for configuration. Here is a table describing these emulated dev
- This is an alias for ``ahci``. - This is an alias for ``ahci``.
* - ``ahci-cd`` * - ``ahci-cd``
- Advanced Host Controller Interface used to connect with AT Attachment - Advanced Host Controller Interface used to connect with an AT Attachment
Packet Interface device (for CD-ROM emulation). ``ahci-cd`` supports the same Packet Interface device (for CD-ROM emulation). ``ahci-cd`` supports the
parameters than ``ahci``. same parameters as ``ahci``.
* - ``hostbridge`` * - ``hostbridge``
- Virtualized PCI hostbridge, a hardware bridge between the CPU's - Virtualized PCI host bridge, a hardware bridge between the CPU's
high-speed system local bus and the Peripheral Component Interconnect high-speed system local bus and the Peripheral Component Interconnect
(PCI) bus. (PCI) bus.
* - ``virtio-blk`` * - ``virtio-blk``
- Virtio block type device, a string could be appended with the format - Virtio block type device. A string could be appended with the format
``virtio-blk,<filepath>[,options]`` ``virtio-blk,<filepath>[,options]``:
* ``<filepath>`` specifies the path of a file or disk partition. * ``<filepath>`` specifies the path of a file or disk partition. You can
You can also could use ``nodisk`` to create a virtio-blk device with a dummy backend. also use ``nodisk`` to create a virtio-blk device with a dummy backend.
``nodisk`` is used for hot-plugging a rootfs after the User VM has been launched. It is ``nodisk`` is used for hot-plugging a rootfs after the User VM has been
achieved by triggering a rescan of the ``virtio-blk`` device by the User VM. The empty file launched. It is achieved by triggering a rescan of the ``virtio-blk``
will be updated to valid file after rescan. device by the User VM. The empty file will be updated to a valid file
after rescan.
* ``[,options]`` includes: * ``[,options]`` includes:
* ``writethru``: write operation is reported completed only when the data * ``writethru``: write operation is reported completed only when the data
has been written to physical storage. has been written to physical storage.
* ``writeback``: write operation is reported completed when data is placed * ``writeback``: write operation is reported completed when data is placed
in the page cache. Needs to be flushed to the physical storage. in the page cache. Needs to be flushed to the physical storage.
* ``ro``: open file with readonly mode. * ``ro``: open file with read-only mode.
* ``sectorsize``: configured as either ``sectorsize=<sector size>/<physical sector size>`` * ``sectorsize``: configured as either ``sectorsize=<sector
or ``sectorsize=<sector size>``. The default values for sector size and physical sector size are 512. size>/<physical sector size>`` or ``sectorsize=<sector size>``. The
* ``range``: configured as ``range=<start lba in file>/<sub file size>`` meaning the virtio-blk will default values for sector size and physical sector size are 512.
only access part of the file, from the ``<start lba in file>`` to ``<start lba in file>`` + ``<sub file site>``. * ``range``: configured as ``range=<start lba in file>/<sub file
size>`` meaning the virtio-blk will only access part of the file,
from the ``<start lba in file>`` to ``<start lba in file>`` + ``<sub
file size>``.
* - ``virtio-input`` * - ``virtio-input``
- Virtio type device to emulate input device. ``evdev`` char device node - Virtio type device to emulate input device. ``evdev`` char device node
should be appended, e.g., ``-s should be appended, e.g., ``-s
n,virtio-input,/dev/input/eventX[,serial]``. ``serial`` is an optional n,virtio-input,/dev/input/eventX[,serial]``. ``serial`` is an optional
string used as the unique identification code of guest virtio input device. string used as the unique identification code of the guest virtio input device.
* - ``virtio-console`` * - ``virtio-console``
- Virtio console type device for data input and output. - Virtio console type device for data input and output.
* - ``virtio-heci`` * - ``virtio-heci``
- Virtio Host Embedded Controller Interface, parameters should be appended - Virtio Host Embedded Controller Interface. Parameters should be appended
with the format ``<bus>:<device>:<function>,d<0~8>``. You can find the BDF with the format ``<bus>:<device>:<function>,d<0~8>``. You can find the BDF
information from the Service VM. information from the Service VM.
* - ``virtio-i2c`` * - ``virtio-i2c``
- Virtio i2c type device,parameters with format: - Virtio I2C type device. Parameters format is:
``<bus>[:<client_addr>[@<node>]][,<bus>[:<client_addr>[@<node>]]`` ``<bus>[:<client_addr>[@<node>]][,<bus>[:<client_addr>[@<node>]]``
* ``<bus>`` specifies the bus number for the native I2C adapter, e.g., * ``<bus>`` specifies the bus number for the native I2C adapter, e.g.,
@ -448,13 +458,13 @@ arguments used for configuration. Here is a table describing these emulated dev
``hdac`` are supported for APL platform and are platform-specific. ``hdac`` are supported for APL platform and are platform-specific.
* - ``virtio-gpio`` * - ``virtio-gpio``
- Virtio GPIO type device, parameters format is: - Virtio GPIO type device. Parameters format is:
``virtio-gpio,<@controller_name{offset|name[=mapping_name]:offset|name[=mapping_name]:...}@controller_name{...}...]>`` ``virtio-gpio,<@controller_name{offset|name[=mapping_name]:offset|name[=mapping_name]:...}@controller_name{...}...]>``
* ``controller_name``: use the command ``ls /sys/bus/gpio/devices`` to * ``controller_name``: use the command ``ls /sys/bus/gpio/devices`` to
check the native GPIO controller information. Usually, the devices check the native GPIO controller information. Usually, the devices
represent the ``controller_name`` that you can use. You can also use represent the ``controller_name`` that you can use. You can also use
the command ``cat /sys/bus/gpio/device/XXX/dev`` to get the device id the command ``cat /sys/bus/gpio/device/XXX/dev`` to get the device ID
that can be used to match ``/dev/XXX``, and then use ``XXX`` as the that can be used to match ``/dev/XXX``, and then use ``XXX`` as the
``controller_name``. On Intel platforms, ``controller_name`` may be ``controller_name``. On Intel platforms, ``controller_name`` may be
``gpiochip0``, ``gpiochip1``, ``gpiochip2``, and ``gpiochip3``. ``gpiochip0``, ``gpiochip1``, ``gpiochip2``, and ``gpiochip3``.
@ -464,24 +474,29 @@ arguments used for configuration. Here is a table describing these emulated dev
a FE GPIO, you can set a new name here. a FE GPIO, you can set a new name here.
* - ``virtio-rnd`` * - ``virtio-rnd``
- Virtio random generator type device, the VBSU virtio backend is used by default. - Virtio random generator type device. The VBSU virtio backend is used by
default.
* - ``virtio-rpmb`` * - ``virtio-rpmb``
- Virtio Replay Protected Memory Block (RPMB) type device, with - Virtio Replay Protected Memory Block (RPMB) type device, with
``physical_rpmb`` to specify RPMB in physical mode, ``physical_rpmb`` to specify RPMB in physical mode;
otherwise RPMB is in simulated mode. otherwise, RPMB is in simulated mode.
* - ``virtio-net`` * - ``virtio-net``
- Virtio network type device, parameter should be appended with the format: - Virtio network type device. Parameters should be appended with the
format:
``virtio-net,<device_type>=<name>[,vhost][,mac=<XX:XX:XX:XX:XX:XX> | mac_seed=<seed_string>]``. ``virtio-net,<device_type>=<name>[,vhost][,mac=<XX:XX:XX:XX:XX:XX> | mac_seed=<seed_string>]``.
The only supported ``device_type`` parameter is
``tap``. The ``mac`` address is optional and ``name`` is the name of the TAP * ``device_type``: The only supported parameter is ``tap``.
(or MacVTap) device. ``vhost`` specifies vhost backend, otherwise the * ``name``: Name of the TAP (or MacVTap) device.
VBSU backend is used. ``mac_seed=<seed_string>`` sets a platform-unique * ``vhost``: Specifies the vhost backend; otherwise, the VBSU backend is
string as a seed to generate the MAC address. Each VM should have a used.
different ``seed_string``. The ``seed_string`` can be * ``mac=<XX:XX:XX:XX:XX:XX> | mac_seed=<seed_string>``: The MAC address
generated by the following method where ``$(vm_name)`` contains the name or seed is optional. ``mac_seed=<seed_string>`` sets a platform-unique
of the VM you are going to launch. string as a seed to generate the MAC address. Each VM should have a
different ``seed_string``. The ``seed_string`` can be generated by the
following method where ``$(vm_name)`` contains the name of the VM you
are going to launch.
.. code-block:: .. code-block::
@ -489,12 +504,12 @@ arguments used for configuration. Here is a table describing these emulated dev
seed_string=${mac:9:8}-${vm_name} seed_string=${mac:9:8}-${vm_name}
.. note:: .. note::
``mac`` and ``mac_seed`` are mutually exclusive, when both are set the ``mac`` and ``mac_seed`` are mutually exclusive. When both are set,
latter is ignored and the MAC address is set to the ``mac`` value. the latter is ignored and the MAC address is set to the ``mac`` value.
``mac_seed`` will only be used when ``mac`` is not set. ``mac_seed`` will only be used when ``mac`` is not set.
* - ``virtio-gpu`` * - ``virtio-gpu``
- Virtio GPU type device, parameters format is: - Virtio GPU type device. Parameters format is:
``virtio-gpu[,geometry=<width>x<height>+<x_off>+<y_off> | fullscreen]`` ``virtio-gpu[,geometry=<width>x<height>+<x_off>+<y_off> | fullscreen]``
* ``geometry`` specifies the mode of virtual display, windowed or fullscreen. * ``geometry`` specifies the mode of virtual display, windowed or fullscreen.
@ -512,7 +527,7 @@ arguments used for configuration. Here is a table describing these emulated dev
* - ``passthru`` * - ``passthru``
- Indicates a passthrough device. Use the parameter with the format - Indicates a passthrough device. Use the parameter with the format
``passthru,<bus>/<device>/<function>,<optional parameter>`` ``passthru,<bus>/<device>/<function>,<optional parameter>``.
Optional parameters include: Optional parameters include:
* ``keep_gsi``: keep vGSI for MSI capable passthrough device. * ``keep_gsi``: keep vGSI for MSI capable passthrough device.
@ -523,9 +538,9 @@ arguments used for configuration. Here is a table describing these emulated dev
parameter should be appended to enable a Windows UEFI ACPI bug fix. parameter should be appended to enable a Windows UEFI ACPI bug fix.
* ``gpu``: create the dedicated ``igd-lpc`` on ``00:1f.0`` for IGD * ``gpu``: create the dedicated ``igd-lpc`` on ``00:1f.0`` for IGD
passthrough. passthrough.
* ``vmsix_on_msi,<bar_id>``: enables vMSI-X emulation based on MSI * ``vmsix_on_msi,<bar_id>``: enable vMSI-X emulation based on MSI
capability. The specific virtual bar will be allocated. capability. The specific virtual bar will be allocated.
* ``enable_ptm``: enable PCIE precise time measurement mechanism for the * ``enable_ptm``: enable PCIe precise time measurement mechanism for the
passthrough device. passthrough device.
* - ``uart`` * - ``uart``
@ -533,97 +548,100 @@ arguments used for configuration. Here is a table describing these emulated dev
``uart,vuart_idx:<0~9>`` to specify hypervisor-emulated PCI vUART index. ``uart,vuart_idx:<0~9>`` to specify hypervisor-emulated PCI vUART index.
* - ``wdt-i6300esb`` * - ``wdt-i6300esb``
- Emulated i6300ESB PCI Watch Dog Timer (WDT) Intel processors use to - Emulated i6300ESB PCI Watch Dog Timer (WDT), which Intel processors use
monitor User VMs. to monitor User VMs.
Launch Script Launch Script
************* *************
A launch script is used to start a User VM from the Service VM command line. It A launch script is used to start a post-launched User VM from the Service VM
is generated by the ACRN configurator according to several settings for a User command line. The ACRN Configurator creates the launch script according to
VM. Normally, you should not manually edit these generated launch scripts or several User VM settings. Normally, you should not manually edit these generated
change ``acrn-dm`` command line parameters. If you do so, your changes could launch scripts or change ``acrn-dm`` command-line parameters. If you do so, your
be overwritten the next time you run the configurator. changes could be overwritten the next time you run the Configurator.
In this section we describe how setting in the scenario file, In this section, we describe how settings in the scenario file,
created by the configurator, are transformed into the launch script. created by the Configurator, are transformed into the launch script.
This information would be useful to ACRN contributors or developers This information would be useful to ACRN contributors or developers
interested in knowing how the launch scripts are created. interested in knowing how the launch scripts are created.
Most configurator settings for User VMs are used at launch time. Most Configurator settings for User VMs are used at launch time.
When you exit the configurator, these settings are saved in the When you exit the Configurator, these settings are saved in the
``scenario.xml`` file and then processed by ``scenario.xml`` file and then processed by
``misc/config_tools/launch_config/launch_cfg_gen.py`` ``misc/config_tools/launch_config/launch_cfg_gen.py``
to add shell commands to create the launch script, according to the template to add shell commands to create the launch script, according to the template
``misc/config_tools/launch_config/launch_script_template.sh``. ``misc/config_tools/launch_config/launch_script_template.sh``.
The template uses following helper functions to do system settings or to The template uses the following helper functions to do system settings or to
generate an ``acrn-dm`` command line parameter. For details about all generate an ``acrn-dm`` command-line parameter. For details about all
``acrn-dm`` parameters, refer to the previous section. ``acrn-dm`` parameters, refer to the previous section.
``probe_modules`` ``probe_modules``
Install necessary modules before launching a Post-launched VM. For Install necessary modules before launching a post-launched VM. For
example, ``pci_stub`` is used to provide a stub pci driver that does example, ``pci_stub`` is used to provide a stub PCI driver that does
nothing on attached pci devices. Passthrough PCIe devices will be unbound nothing on attached PCI devices. Passthrough PCIe devices will be unbound
from their original driver and bound to the stub, so that they can be safely from their original driver and bound to the stub, so that they can be safely
controlled by the User VM. controlled by the User VM.
``offline_cpus <cpu_apicid>...`` ``offline_cpus <cpu_apicid>...``
This is called if we are launching an RTVM or VM whose scheduler is This is called if we are launching an RTVM or VM whose scheduler is
"SCHED_NOOP". In both situations, CPU sharing between multiple VMs is ``SCHED_NOOP``. In both situations, CPU sharing between multiple VMs is
prevented. prevented.
This function will trigger taking a CPU offline (done by the Service VM This function will trigger taking a CPU offline (done by the Service VM
kernel), and then inform the hypervisor through Hypervisor Service Module kernel), and then inform the hypervisor through the Hypervisor Service
(HSM). The hypervisor will offline vCPU and freeze vCPU thread. Module (HSM). The hypervisor will offline the vCPU and freeze the vCPU
thread.
``unbind_device <bdf>`` ``unbind_device <bdf>``
Unbind a PCIe device with specified BDF (bus, device and function) number Unbind a PCIe device with specified BDF (bus, device, and function) number
from its original driver and re-bind it to the pci-stub driver. After that from its original driver and re-bind it to the pci-stub driver. Then
the Service VM kernel will not operate on that device any more and it can the Service VM kernel will not operate on that device anymore and it can
be passed through to User VM safely. be passed through to the User VM safely.
``create_tap <tap>`` ``create_tap <tap>``
Create or reuse the tap interface that is attached to ``acrn-br0`` bridge. Create or reuse the tap interface that is attached to the ``acrn-br0``
bridge.
``acrn-br0`` is registered to ``systemd-networkd.service`` after installing ``acrn-br0`` is registered to ``systemd-networkd.service`` after installing
the ACRN Debian package (``.deb``). You also need to enable and start the the ACRN Debian package (``.deb``). You also need to enable and start the
service to create the bridge from the Service VM using:: service to create the bridge from the Service VM using::
sudo systemctl enable --now systemd-networkd sudo systemctl enable --now systemd-networkd
The bridge is used to add ``virtio-net`` The bridge is used to add a ``virtio-net``
interface to a User VM. ``virtio-net`` interfaces for all User VMs are interface to a User VM. ``virtio-net`` interfaces for all User VMs are
virtually connected to a subnet behind the ACRN bridge. virtually connected to a subnet behind the ACRN bridge.
``mount_partition <partition>`` ``mount_partition <partition>``
Mount specified partition to a temporary directory created by ``mktemp -d``, Mount the specified partition to a temporary directory created by
``mktemp -d``,
and return the temporary directory for later unmount. and return the temporary directory for later unmount.
Typically this function is called to mount an image file in order to use Typically this function is called to mount an image file in order to use an
inner rootfs file as ``virtio-blk`` backend. For example, user could set inner rootfs file as a ``virtio-blk`` backend. For example, users could set
"<imgfile>:/boot/initrd.img*" in the ``virtio-blk`` input box in the ACRN ``<imgfile>:/boot/initrd.img*`` in the ``virtio-blk`` input box in the ACRN
Configurator. After the ``acrn-dm`` instance exits, ``unmount_partition`` Configurator. After the ``acrn-dm`` instance exits, ``unmount_partition``
will be called to unmount the image file. will be called to unmount the image file.
``unmount_partition <dir>`` ``unmount_partition <dir>``
Unmount partition from specified directory. Unmount the partition from the specified directory.
``add_cpus <cpu_apicid>...`` ``add_cpus <cpu_apicid>...``
Return an ``acrn-dm`` command line parameter fragment to set Return an ``acrn-dm`` command-line parameter fragment to set
``cpu_affinity``. Refer to `cpu_affinity`_ for details. ``cpu_affinity``. Refer to `cpu_affinity`_ for details.
``offline_cpus`` is called if the User VM is an RTVM or its scheduler is ``offline_cpus`` is called if the User VM is an RTVM or its scheduler is
``SCHED_NOOP``. ``SCHED_NOOP``.
``add_interrupt_storm_monitor <threshold_per_sec> <probe_period_in_sec> <inject_delay_in_ms> <delay_duration_in_ms>`` ``add_interrupt_storm_monitor <threshold_per_sec> <probe_period_in_sec> <inject_delay_in_ms> <delay_duration_in_ms>``
This is added if PCIe devices, other than an integrated GPU, are passed through to This is added if PCIe devices, other than an integrated GPU, are passed through to
the User VM to monitor if interrupt storm occurred on those devices. the User VM to monitor if an interrupt storm occurred on those devices.
This function and parameters are not visible in the ACRN Configurator and The function and parameters are not visible in the ACRN Configurator and
handled by config scripts. are handled by config scripts. The function returns ``acrn-dm``
It returns ``acrn-dm`` command line segment to set ``intr_monitor``. command-line segment to set ``intr_monitor``.
``add_logger_settings console=<n> kmsg=<n> disk=<n>`` ``add_logger_settings console=<n> kmsg=<n> disk=<n>``
set log level of each ``acrn-dm`` logging channel: console, kmsg, disk. Set the log level of each ``acrn-dm`` logging channel: console, kmsg, disk.
These settings are not exposed to user in the ACRN Configurator. These settings are not exposed to users in the ACRN Configurator.
``add_virtual_device <slot> <kind> <options>`` ``add_virtual_device <slot> <kind> <options>``
Add specified kind of virtual device to the specified PCIe device slot. Add the specified kind of virtual device to the specified PCIe device slot.
Some devices need options to configure further behaviors. ``<slot>`` numbers Some devices need options to configure further behaviors. ``<slot>`` numbers
for virtual devices and passthrough devices are automatically allocated for virtual devices and passthrough devices are automatically allocated
by ``launch_cfg_gen.py``. by ``launch_cfg_gen.py``.
@ -634,24 +652,24 @@ generate an ``acrn-dm`` command line parameter. For details about all
PCIe host bridge. ``<slot>`` must be 0. PCIe host bridge. ``<slot>`` must be 0.
- ``uart vuart_idx:<int>`` - ``uart vuart_idx:<int>``
Add a PCIe vuart with specified index. Add a PCIe vUART with specified index.
- ``xhci <bus>-<port>[:<bus>-<port>]...`` - ``xhci <bus>-<port>[:<bus>-<port>]...``
Config USB mediator. A list of USB ports each specified by Configure a USB mediator. A list of USB ports each specified by
``<bus>-<port>`` will be connected to the User VM. ``<bus>-<port>`` will be connected to the User VM.
- ``virtio-net tap=<tapname>[,vhost],mac_seed=<str>`` - ``virtio-net tap=<tapname>[,vhost],mac_seed=<str>``
The TAP should already be created by ``create_tap``. The TAP should already be created by ``create_tap``.
- ``virtio-blk <imgfile>[,writethru|writeback|ro]`` - ``virtio-blk <imgfile>[,writethru|writeback|ro]``
Add a virtio block device to User VM. The backend is a raw image Add a virtio block device to the User VM. The backend is a raw image
file. Options can be specified to control access right. file. Options can be specified to control access right.
For all types of virtual devices and options, refer to For all types of virtual devices and options, refer to
:ref:`emul_config`. :ref:`emul_config`.
``add_passthrough_device <slot> <bus>/<device>/<function> <options>`` ``add_passthrough_device <slot> <bus>/<device>/<function> <options>``
Passthrough PCIe device to User VM in specified ``<slot>``. Passthrough a PCIe device to the User VM in the specified ``<slot>``.
Some kinds of devices may need extra ``<options>`` to control internal Some kinds of devices may need extra ``<options>`` to control internal
behavior. Refer to the ``passthru`` section in :ref:`emul_config`. behavior. Refer to the ``passthru`` section in :ref:`emul_config`.