From 79f40a569b0dd394871b31a288400ee5fe24228d Mon Sep 17 00:00:00 2001 From: Shuang Zheng Date: Thu, 3 Jan 2019 19:15:28 +0800 Subject: [PATCH] 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 | 32 +++++---- doc/developer-guides/hld/hld-devicemodel.rst | 51 +++++++------- doc/user-guides/acrn-dm-parameters.rst | 71 ++++++++++++++++++++ 3 files changed, 114 insertions(+), 40 deletions(-) diff --git a/devicemodel/core/main.c b/devicemodel/core/main.c index 70b949fd2..bcbd59bfc 100644 --- a/devicemodel/core/main.c +++ b/devicemodel/core/main.c @@ -131,27 +131,31 @@ static void usage(int code) { fprintf(stderr, - "Usage: %s [-hAEWY] [-c vcpus] [-l ]\n" - " %*s [-m mem] [-p vcpu:hostcpu] [-s ] [-U uuid] \n" - " %*s [--vsbl vsbl_file_name] [--part_info part_info_name]\n" - " %*s [--enable_trusty] [--debugexit] \n" + "Usage: %s [-hAWYv] [-B bootargs] [-c vcpus] [-E elf_image_path]\n" + " %*s [-G GVT_args] [-i ioc_mediator_parameters] [-k kernel_image_path]\n" + " %*s [-l lpc] [-m mem] [-p vcpu:hostcpu] [-r ramdisk_image_path]\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] \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: 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" - " -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" + " --mac_seed: set a platform unique string as a seed for generate mac address\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); } diff --git a/doc/developer-guides/hld/hld-devicemodel.rst b/doc/developer-guides/hld/hld-devicemodel.rst index 7ed058829..426eb2b14 100644 --- a/doc/developer-guides/hld/hld-devicemodel.rst +++ b/doc/developer-guides/hld/hld-devicemodel.rst @@ -51,46 +51,43 @@ options: .. code-block:: none - acrn-dm [-abehuwxACHPSTWY] [-c vcpus] [-g ] [-l ] - [-m mem] [-p vcpu:hostcpu] [-s ] [-U uuid] - [--vsbl vsbl_file_path] [--ovmf ovmf_file_path] - [--part_info part_info_name] - [--enable_trusty] [--intr_monitor param_setting] - - -a: local apic is in xAPIC mode (deprecated) + acrn-dm [-hAWYv] [-B bootargs] [-c vcpus] [-E elf_image_path] + [-G GVT_args] [-i ioc_mediator_parameters] [-k kernel_image_path] + [-l lpc] [-m mem] [-p vcpu:hostcpu] [-r ramdisk_image_path] + [-s pci] [-U uuid] [--vsbl vsbl_file_name] [--ovmf ovmf_file_path] + [--part_info part_info_name] [--enable_trusty] [--intr_monitor param_setting] + [--vtpm2 sock_path] [--virtio_poll interval] [--mac_seed seed_string] + [--vmcfg sub_options] [--dump vm_idx] [--ptdev_no_reset] [--debugexit] -A: create ACPI tables - -b: enable bvmcons + -B: bootargs for kernel -c: # cpus (default 1) - -C: include guest memory in core file - -e: exit on unhandled I/O access - -g: gdb port + -E: elf image path + -G: GVT args: low_gm_size, high_gm_size, fence_sz -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: 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 - -G: GVT args: low_gm_size, high_gm_size, fence_sz + -s: PCI slot config + -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: - threshold/s,probe-period(s),delay_time(ms),delay_duration(ms) + --debugexit: enable debug exit function + --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. diff --git a/doc/user-guides/acrn-dm-parameters.rst b/doc/user-guides/acrn-dm-parameters.rst index 2a4d82818..44721b07f 100644 --- a/doc/user-guides/acrn-dm-parameters.rst +++ b/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 ` + - The option dumps detailed configuration of a VM with built-in configurations. + + Example:: + + --dump 1 + + * - :kbd:`-E ` + - 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 ` + - 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 ` - 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 ` + - 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 ` - 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 ` + - 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 ` + - Enable virtio poll mode with poll interval xxx ns. + + usage:: + + --virtio_poll 1000000 + + enable virtio poll mode with poll interval 1ms. + + * - :kbd:`--vmcfg ` + - It's an experimental option for built-in VM configuration. The + sub-options could be 'list' or . + + - ``--vmcfg list`` shows indexes of all VMs with built-in configuration. + - ``--vmcfg `` launches UOS with selected config. + + Examples:: + + --vmcfg list + --vmcfg 1 + + * - :kbd:`--vtpm2 ` + - 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