mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-06-24 22:42:53 +00:00
doc: Add launch script document
Add launch script document so that customers could understand how an User VM is launched by ACRN Device Model. As launch script is a user friendly tool to set Device Model parameters, append the contents to Device Model Parameters chapter. Tracked-On: #7801 Signed-off-by: Qiang Zhang <qiang4.zhang@linux.intel.com>
This commit is contained in:
Qiang Zhang
David Kinder
parent
8c0070a531
commit
81dc3b192e
@ -1,12 +1,28 @@
|
||||
.. _acrn-dm_parameters:
|
||||
.. _acrn-dm_parameters-and-launch-script:
|
||||
|
||||
Device Model Parameters
|
||||
#######################
|
||||
Device Model Parameters and Launch Script
|
||||
#########################################
|
||||
|
||||
Hypervisor Device Model (DM) is a QEMU-like application in the Service
|
||||
VM responsible for creating a User VM and then performing devices
|
||||
emulation based on command line configurations, as introduced in
|
||||
:ref:`hld-devicemodel`.
|
||||
the :ref:`hld-devicemodel`. ACRN Configurator generates launch scripts for
|
||||
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
|
||||
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
|
||||
configuration and launch scripts.
|
||||
|
||||
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
|
||||
are doing. We also include information useful to ACRN contributors about how
|
||||
setting in the scenario file, created by the configurator, are transformed
|
||||
into the launch script.
|
||||
|
||||
.. _acrn-dm_parameters:
|
||||
|
||||
Device Model Parameters
|
||||
***********************
|
||||
|
||||
Here are descriptions for each of these ``acrn-dm`` command line parameters:
|
||||
|
||||
@ -37,7 +53,7 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
|
||||
``--enable_trusty``
|
||||
Enable trusty for guest. For Android guest OS, ACRN provides a VM
|
||||
environment with two worlds: normal world and trusty world. The Android
|
||||
OS runs in the 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
|
||||
of normal world but not vice versa. See :ref:`trusty_tee` for more
|
||||
information.
|
||||
@ -180,6 +196,8 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
|
||||
|
||||
----
|
||||
|
||||
.. _cpu_affinity:
|
||||
|
||||
``--cpu_affinity <list of lapic_ids>``
|
||||
comma-separated list of vCPUs assigned to this VM. Each CPU has a Local Programmable
|
||||
Interrupt Controller (LAPIC). The unique ID of the LAPIC (lapic_id) is used to identify vCPU.
|
||||
@ -516,3 +534,129 @@ arguments used for configuration. Here is a table describing these emulated dev
|
||||
* - ``wdt-i6300esb``
|
||||
- Emulated i6300ESB PCI Watch Dog Timer (WDT) Intel processors use to
|
||||
monitor User VMs.
|
||||
|
||||
Launch Script
|
||||
*************
|
||||
|
||||
A launch script is used to start a User VM from the Service VM command line. It
|
||||
is generated by the ACRN configurator according to several settings for a User
|
||||
VM. Normally, you should not manually edit these generated launch scripts or
|
||||
change ``acrn-dm`` command line parameters. If you do so, your changes could
|
||||
be overwritten the next time you run the configurator.
|
||||
|
||||
In this section we describe how setting in the scenario file,
|
||||
created by the configurator, are transformed into the launch script.
|
||||
This information would be useful to ACRN contributors or developers
|
||||
interested in knowing how the launch scripts are created.
|
||||
|
||||
Most configurator settings for User VMs are used at launch time.
|
||||
When you exit the configurator, these settings are saved in the
|
||||
``scenario.xml`` file and then processed by
|
||||
``misc/config_tools/launch_config/launch_cfg_gen.py``
|
||||
to add shell commands to create the launch script, according to the template
|
||||
``misc/config_tools/launch_config/launch_script_template.sh``.
|
||||
The template uses following helper functions to do system settings or to
|
||||
generate an ``acrn-dm`` command line parameter. For details about all
|
||||
``acrn-dm`` parameters, refer to the previous section.
|
||||
|
||||
``probe_modules``
|
||||
Install necessary modules before launching a Post-launched VM. For
|
||||
example, ``pci_stub`` is used to provide a stub pci driver that does
|
||||
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
|
||||
controlled by the User VM.
|
||||
|
||||
``offline_cpus <cpu_apicid>...``
|
||||
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
|
||||
prevented.
|
||||
This function will trigger taking a CPU offline (done by the Service VM
|
||||
kernel), and then inform the hypervisor through Hypervisor Service Module
|
||||
(HSM). The hypervisor will offline vCPU and freeze vCPU thread.
|
||||
|
||||
``unbind_device <bdf>``
|
||||
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
|
||||
the Service VM kernel will not operate on that device any more and it can
|
||||
be passed through to User VM safely.
|
||||
|
||||
``create_tap <tap>``
|
||||
Create or reuse the tap interface that is attached to ``acrn-br0`` bridge.
|
||||
``acrn-br0`` is registered to ``systemd-networkd.service`` after installing
|
||||
the ACRN Debian package (``.deb``). You also need to enable and start the
|
||||
service to create the bridge from the Service VM using::
|
||||
|
||||
sudo systemctl enable --now systemd-networkd
|
||||
|
||||
The bridge is used to add ``virtio-net``
|
||||
interface to a User VM. ``virtio-net`` interfaces for all User VMs are
|
||||
virtually connected to a subnet behind the ACRN bridge.
|
||||
|
||||
``mount_partition <partition>``
|
||||
Mount specified partition to a temporary directory created by ``mktemp -d``,
|
||||
and return the temporary directory for later unmount.
|
||||
Typically this function is called to mount an image file in order to use
|
||||
inner rootfs file as ``virtio-blk`` backend. For example, user could set
|
||||
"<imgfile>:/boot/initrd.img*" in the ``virtio-blk`` input box in the ACRN
|
||||
Configurator. After the ``acrn-dm`` instance exits, ``unmount_partition``
|
||||
will be called to unmount the image file.
|
||||
|
||||
``unmount_partition <dir>``
|
||||
Unmount partition from specified directory.
|
||||
|
||||
``add_cpus <cpu_apicid>...``
|
||||
Return an ``acrn-dm`` command line parameter fragment to set
|
||||
``cpu_affinity``. Refer to `cpu_affinity`_ for details.
|
||||
``offline_cpus`` is called if the User VM is an RTVM or its scheduler is
|
||||
``SCHED_NOOP``.
|
||||
|
||||
``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
|
||||
the User VM to monitor if interrupt storm occurred on those devices.
|
||||
This function and parameters are not visible in the ACRN Configurator and
|
||||
handled by config scripts.
|
||||
It returns ``acrn-dm`` command line segment to set ``intr_monitor``.
|
||||
|
||||
``add_logger_settings console=<n> kmsg=<n> disk=<n>``
|
||||
set log level of each ``acrn-dm`` logging channel: console, kmsg, disk.
|
||||
These settings are not exposed to user in the ACRN Configurator.
|
||||
|
||||
``add_virtual_device <slot> <kind> <options>``
|
||||
Add specified kind of virtual device to the specified PCIe device slot.
|
||||
Some devices need options to configure further behaviors. ``<slot>`` numbers
|
||||
for virtual devices and passthrough devices are automatically allocated
|
||||
by ``launch_cfg_gen.py``.
|
||||
|
||||
Typical use cases:
|
||||
|
||||
- ``hostbridge``
|
||||
PCIe host bridge. ``<slot>`` must be 0.
|
||||
|
||||
- ``uart vuart_idx:<int>``
|
||||
Add a PCIe vuart with specified index.
|
||||
|
||||
- ``xhci <bus>-<port>[:<bus>-<port>]...``
|
||||
Config USB mediator. A list of USB ports each specified by
|
||||
``<bus>-<port>`` will be connected to the User VM.
|
||||
|
||||
- ``virtio-net tap=<tapname>[,vhost],mac_seed=<str>``
|
||||
The TAP should already be created by ``create_tap``.
|
||||
|
||||
- ``virtio-blk <imgfile>[,writethru|writeback|ro]``
|
||||
Add a virtio block device to User VM. The backend is a raw image
|
||||
file. Options can be specified to control access right.
|
||||
|
||||
For all types of virtual devices and options, refer to
|
||||
:ref:`emul_config`.
|
||||
|
||||
``add_passthrough_device <slot> <bus>/<device>/<function> <options>``
|
||||
Passthrough PCIe device to User VM in specified ``<slot>``.
|
||||
Some kinds of devices may need extra ``<options>`` to control internal
|
||||
behavior. Refer to the ``passthru`` section in :ref:`emul_config`.
|
||||
|
||||
These functions in the template are copied to the target launch script. Then
|
||||
``launch_cfg_gen.py`` generates the following dynamic part. It first defines
|
||||
necessary variables such as ``vm_type`` and ``scheduler``, and uses the
|
||||
functions described above to construct the ``dm_params`` parameters per the
|
||||
user settings in ``scenario.xml``.
|
||||
Finally, ``acrn-dm`` is executed to launch a User VM with these parameters.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user