Update and complete acrn-dm parameters description

Update and complete `acrn-dm` parameters description in the user guide and HLD

Tracked-On: #2036
Signed-off-by: Shuang Zheng shuang.zheng@intel.com

devicemodel/core/main.c

@@ -131,27 +131,31 @@ static void
 usage(int code)
 {
 	fprintf(stderr,
-		"Usage: %s [-hAEWY] [-c vcpus] [-l <lpc>]\n"
+		"Usage: %s [-hAWYv] [-B bootargs] [-c vcpus] [-E elf_image_path]\n"
-		"       %*s [-m mem] [-p vcpu:hostcpu] [-s <pci>] [-U uuid] \n"
+		"       %*s [-G GVT_args] [-i ioc_mediator_parameters] [-k kernel_image_path]\n"
-		"       %*s [--vsbl vsbl_file_name] [--part_info part_info_name]\n"
+		"       %*s [-l lpc] [-m mem] [-p vcpu:hostcpu] [-r ramdisk_image_path]\n"
-		"       %*s [--enable_trusty] [--debugexit] <vm>\n"
+		"       %*s [-s pci] [-U uuid] [--vsbl vsbl_file_name] [--ovmf ovmf_file_path]\n"
+		"       %*s [--part_info part_info_name] [--enable_trusty] [--intr_monitor param_setting]\n"
+		"       %*s [--vtpm2 sock_path] [--virtio_poll interval] [--mac_seed seed_string]\n"
+		"       %*s [--vmcfg sub_options] [--dump vm_idx] [--ptdev_no_reset] [--debugexit] <vm>\n"
 		"       -A: create ACPI tables\n"
+		"       -B: bootargs for kernel\n"
 		"       -c: # cpus (default 1)\n"
 		"       -E: elf image path\n"
+		"       -G: GVT args: low_gm_size, high_gm_size, fence_sz\n"
 		"       -h: help\n"
+		"       -i: ioc boot parameters\n"
+		"       -k: kernel image path\n"
 		"       -l: LPC device configuration\n"
 		"       -m: memory size in MB\n"
 		"       -p: pin 'vcpu' to 'hostcpu'\n"
+		"       -r: ramdisk image path\n"
 		"       -s: <slot,driver,configinfo> PCI slot config\n"
 		"       -U: uuid\n"
+		"       -v: version\n"
 		"       -W: force virtio to use single-vector MSI\n"
 		"       -Y: disable MPtable generation\n"
-		"       -k: kernel image path\n"
+		"       --mac_seed: set a platform unique string as a seed for generate mac address\n"
-		"       -r: ramdisk image path\n"
-		"       -B: bootargs for kernel\n"
-		"       -G: GVT args: low_gm_size, high_gm_size, fence_sz\n"
-		"       -v: version\n"
-		"       -i: ioc boot parameters\n"
 #ifdef CONFIG_VM_CFG
 		"       --vmcfg: build-in VM configurations\n"
 		"       --dump: show build-in VM configurations\n"
@@ -163,10 +167,12 @@ usage(int code)
 		"       --ptdev_no_reset: disable reset check for ptdev\n"
 		"       --debugexit: enable debug exit function\n"
 		"       --intr_monitor: enable interrupt storm monitor\n"
-		"       --vtpm2: Virtual TPM2 args: sock_path=$PATH_OF_SWTPM_SOCKET\n"
+		"            its params: threshold/s,probe-period(s),delay_time(ms),delay_duration(ms)\n"
-		"            its params: threshold/s,probe-period(s),delay_time(ms),delay_duration(ms)\n",
+		"       --virtio_poll: enable virtio poll mode with poll interval with ns\n"
+		"       --vtpm2: Virtual TPM2 args: sock_path=$PATH_OF_SWTPM_SOCKET\n",
 		progname, (int)strnlen(progname, PATH_MAX), "", (int)strnlen(progname, PATH_MAX), "",
-		(int)strnlen(progname, PATH_MAX), "");
+		(int)strnlen(progname, PATH_MAX), "", (int)strnlen(progname, PATH_MAX), "",
+		(int)strnlen(progname, PATH_MAX), "", (int)strnlen(progname, PATH_MAX), "");
 
 	exit(code);
 }

doc/developer-guides/hld/hld-devicemodel.rst

@@ -51,46 +51,43 @@ options:
 
 .. code-block:: none
 
-   acrn-dm [-abehuwxACHPSTWY] [-c vcpus] [-g <gdb port>] [-l <lpc>]
+  acrn-dm [-hAWYv] [-B bootargs] [-c vcpus] [-E elf_image_path]
-               [-m mem] [-p vcpu:hostcpu] [-s <pci>] [-U uuid]
+               [-G GVT_args] [-i ioc_mediator_parameters] [-k kernel_image_path]
-               [--vsbl vsbl_file_path] [--ovmf ovmf_file_path]
+               [-l lpc] [-m mem] [-p vcpu:hostcpu] [-r ramdisk_image_path]
-               [--part_info part_info_name]
+               [-s pci] [-U uuid] [--vsbl vsbl_file_name] [--ovmf ovmf_file_path]
-               [--enable_trusty] [--intr_monitor param_setting] <vm>
+               [--part_info part_info_name] [--enable_trusty] [--intr_monitor param_setting]
-
+               [--vtpm2 sock_path] [--virtio_poll interval] [--mac_seed seed_string]
-       -a: local apic is in xAPIC mode (deprecated)
+               [--vmcfg sub_options] [--dump vm_idx] [--ptdev_no_reset] [--debugexit] <vm>
        -A: create ACPI tables
-       -b: enable bvmcons
+       -B: bootargs for kernel
        -c: # cpus (default 1)
-       -C: include guest memory in core file
+       -E: elf image path
-       -e: exit on unhandled I/O access
+       -G: GVT args: low_gm_size, high_gm_size, fence_sz
-       -g: gdb port
        -h: help
-       -H: vmexit from the guest on hlt
+       -i: ioc boot parameters
+       -k: kernel image path
        -l: LPC device configuration
        -m: memory size in MB
        -p: pin 'vcpu' to 'hostcpu'
-       -P: vmexit from the guest on pause
-       -s: <slot,driver,configinfo> PCI slot config
-       -S: guest memory cannot be swapped
-       -u: RTC keeps UTC time
-       -U: uuid
-       -w: ignore unimplemented MSRs
-       -W: force virtio to use single-vector MSI
-       -x: local apic is in x2APIC mode
-       -Y: disable MPtable generation
-       -k: kernel image path
        -r: ramdisk image path
-       -B: bootargs for kernel
+       -s: <slot,driver,configinfo> PCI slot config
-       -G: GVT args: low_gm_size, high_gm_size, fence_sz
+       -U: uuid
        -v: version
-       -i: ioc boot parameters
+       -W: force virtio to use single-vector MSI
+       -Y: disable MPtable generation
+       --mac_seed: set a platform unique string as a seed for generate mac address
+       --vmcfg: build-in VM configurations
+       --dump: show build-in VM configurations
        --vsbl: vsbl file path
        --ovmf: ovmf file path
        --part_info: guest partition info file path
        --enable_trusty: enable trusty for guest
        --ptdev_no_reset: disable reset check for ptdev
-       --intr_monitor: enable interrupt storm monitor, params:
+       --debugexit: enable debug exit function
-       		threshold/s,probe-period(s),delay_time(ms),delay_duration(ms)
+       --intr_monitor: enable interrupt storm monitor
+            its params: threshold/s,probe-period(s),delay_time(ms),delay_duration(ms),
+       --virtio_poll: enable virtio poll mode with poll interval with ns
+       --vtpm2: Virtual TPM2 args: sock_path=$PATH_OF_SWTPM_SOCKET
 
 See :ref:`acrn-dm_parameters` for more detailed descriptions of these
 configuration options.

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

@@ -38,6 +38,21 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
        more than the total number of CPUs in the system, minus one (which is
        used by the SOS).
 
+   * - :kbd:`--debugexit`
+     - Enable guest to write io port 0xf4 to exit guest. It's mainly used by 
+       guest unit test.
+
+   * - :kbd:`--dump <vm_idx>`
+     - The option dumps detailed configuration of a VM with built-in configurations.
+
+       Example::
+
+         --dump 1
+
+   * - :kbd:`-E <elf image path>`
+     - This option is to define a static elf binary which could be loaded by
+       DM. DM will run elf as guest of ACRN.
+
    * - :kbd:`--enable_trusty`
      - Enable trusty for guest.
        For Android guest OS, ACRN provides a VM environment with two worlds:
@@ -107,6 +122,24 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
           -i /run/acrn/ioc_$vm_name,0x20
           -l com2,/run/acrn/ioc_$vm_name
 
+   * - :kbd:`--intr_monitor <intr_monitor_params>`
+     - Enable interrupt storm monitor for UOS. Use this option to prevent an interrupt
+       storm from the UOS.
+
+       usage: ``--intr_monitor threshold/s probe-period(s) delay_time(ms) delay_duration(ms)``
+       
+       Example:: 
+
+         --intr_monitor 10000,10,1,100
+
+       - ``10000``: interrupt rate larger than 10000/s will be treated as 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 will
+         be delayed 1ms before being injected to the guest
+       - ``100``: after 100ms, we will cancel the interrupt injection delay and restore
+         to normal.
+
    * - :kbd:`-k, --kernel <kernel_image_path>`
      - Set the kernel (full path) for the UOS kernel. The maximum path length is
        1023 characters. The DM handles bzImage image format.
@@ -124,6 +157,16 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
 
        usage: ``-m 4g``: set UOS memory to 4 gigabytes.
 
+   * - :kbd:`--mac_seed <seed_string>`
+     - Set a platform unique 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.
+
+       ``mac=$(cat /sys/class/net/e*/address)``
+
+       ``seed_string=${mac:9:8}-${vm_name}``
+
    * - :kbd:`-p, --pincpu <vcpu:hostcpu>`
      - Pin host CPU to appointed vCPU:
 
@@ -132,6 +175,9 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
 
        Example: ``-p  "1:2"`` means pin the 2nd physical cpu to 1st vcpu in UOS
 
+   * - :kbd:`--part_info <part_info_name>`
+     - Set guest partition info path.
+
    * - :kbd:`--ptdev_no_reset`
      - Disable reset check for pci device.
        When assigning a PCI device as a passthrough device, we will reset it
@@ -226,6 +272,31 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
 
        uses ``OVMF.fd`` as the OVMF image
 
+   * - :kbd:`--virtio_poll <poll_interval>`
+     - Enable virtio poll mode with poll interval xxx ns.
+
+       usage::
+
+          --virtio_poll 1000000
+
+       enable virtio poll mode with poll interval 1ms.
+
+   * - :kbd:`--vmcfg <sub-options>`
+     - It's an experimental option for built-in VM configuration. The
+       sub-options could be 'list' or <vm_idx>.
+
+       - ``--vmcfg list`` shows indexes of all VMs with built-in configuration.
+       - ``--vmcfg <vm_idx>`` launches UOS with selected config.
+
+       Examples::
+
+         --vmcfg list
+         --vmcfg 1
+
+   * - :kbd:`--vtpm2 <sock_path>`
+     - This option is to enable virtual TPM support. The sock_path is a mandatory
+       parameter for this option which is the path of swtpm socket fd.
+
    * - :kbd:`-W, --virtio_msix`
      - This option forces virtio to use single-vector MSI.
        By default, any virtio-based devices will use MSI-X as its interrupt