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>

doc/user-guides/acrn-dm-parameters.rst

@@ -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.