From 6dec1667796e499481cd083067456d361db83d17 Mon Sep 17 00:00:00 2001 From: "David B. Kinder" Date: Wed, 12 Dec 2018 10:57:10 -0800 Subject: [PATCH] doc: improve acrn-dm param layout Use a table instead of a dictionary list to make the parameter description layout more readable. Signed-off-by: David B. Kinder --- doc/user-guides/acrn-dm-parameters.rst | 314 +++++++++++++------------ 1 file changed, 159 insertions(+), 155 deletions(-) diff --git a/doc/user-guides/acrn-dm-parameters.rst b/doc/user-guides/acrn-dm-parameters.rst index ec9361ea0..c599ad264 100644 --- a/doc/user-guides/acrn-dm-parameters.rst +++ b/doc/user-guides/acrn-dm-parameters.rst @@ -10,218 +10,222 @@ emulation based on command line configurations, as introduced in Here are descriptions for each of these ``acrn-dm`` command line parameters: -:kbd:`-A, --acpi` - Create ACPI tables. - With this option, DM will build an ACPI table into its VMs F-Segment - (0xf2400). This ACPI table includes full tables for RSDP, RSDT, XSDT, - MADT, FADT, HPET, MCFG, FACS, and DSDT. All these items are programmed - according to acrn-dm command line configuration and derived from their - default value. +.. list-table:: + :widths: 22 78 + :header-rows: 0 -:kbd:`-B, --bootargs ` - Set the UOS kernel command line arguments. - The maximum length is 1023. - The bootargs string will be passed to the kernel as its cmdline. + * - \-A, --acpi + - Create ACPI tables. + With this option, DM will build an ACPI table into its VMs F-Segment + (0xf2400). This ACPI table includes full tables for RSDP, RSDT, XSDT, + MADT, FADT, HPET, MCFG, FACS, and DSDT. All these items are programmed + according to acrn-dm command line configuration and derived from their + default value. - Example:: + * - \-B, --bootargs + - Set the UOS kernel command line arguments. + The maximum length is 1023. + The bootargs string will be passed to the kernel as its cmdline. - -B "loglevel=7" + Example:: - specifies the kernel log level at 7 + -B "loglevel=7" -:kbd:`-c, --ncpus ` - Set number of CPUs for UOS. This number is an integer and must not be - more than the total number of CPUs in the system, minus one (which is - used by the SOS). + specifies the kernel log level at 7 -:kbd:`--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 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. + * - \-c, --ncpus + - Set number of CPUs for UOS. This number is an integer and must not be + more than the total number of CPUs in the system, minus one (which is + used by the SOS). - By default, the trusty world is disabled. Use this option to enable it. + * - \--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 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. -:kbd:`-G, --gvtargs ` - ACRN implements GVT-g for graphics virtualization (aka AcrnGT). This - option allows you to set some of its parameters. + By default, the trusty world is disabled. Use this option to enable it. - GVT_args format: ``gvt_high_gm_sz gvt_low_gm_sz gvt_fence_sz`` + * - \-G, --gvtargs + - ACRN implements GVT-g for graphics virtualization (aka AcrnGT). This + option allows you to set some of its parameters. - Where: + GVT_args format: ``gvt_high_gm_sz gvt_low_gm_sz gvt_fence_sz`` - - ``gvt_high_gm_sz``: GVT-g aperture size, unit is MB - - ``gvt_low_gm_sz``: GVT-g hidden gfx memory size, unit is MB - - ``gvt_fence_sz``: the number of fence registers + Where: - Example:: + - ``gvt_high_gm_sz``: GVT-g aperture size, unit is MB + - ``gvt_low_gm_sz``: GVT-g hidden gfx memory size, unit is MB + - ``gvt_fence_sz``: the number of fence registers - -G "10 128 6" + Example:: - sets up 10Mb for GVT-g aperture, 128M for GVT-g hidden - memory, and 6 fence registers. + -G "10 128 6" -:kbd:`-h, --help` - Show a summary of commands. + sets up 10Mb for GVT-g aperture, 128M for GVT-g hidden + memory, and 6 fence registers. -:kbd:`-i, --ioc_node ` - IOC (IO Controller) is a bridge of an SoC to communicate with Vehicle Bus. - It routes Vehicle Bus signals, for example extracted from CAN messages, - from IOC to the SoC and back, as well as controlling the onboard - peripherals from SoC. (The ``-i`` and ``-l`` parameters are only - available on a platform with IOC.) + * - \-h, --help + - Show a summary of commands. - IOC DM opens ``/dev/ptmx`` device to create a peer PTY devices, IOC DM uses - these to communicate with UART DM since UART DM needs a TTY capable - device as its backend. + * - \-i, --ioc_node + - IOC (IO Controller) is a bridge of an SoC to communicate with Vehicle Bus. + It routes Vehicle Bus signals, for example extracted from CAN messages, + from IOC to the SoC and back, as well as controlling the onboard + peripherals from SoC. (The ``-i`` and ``-l`` parameters are only + available on a platform with IOC.) - The device model configuration command syntax for IOC mediator is:: + IOC DM opens ``/dev/ptmx`` device to create a peer PTY devices, IOC DM uses + these to communicate with UART DM since UART DM needs a TTY capable + device as its backend. - -i,[ioc_channel_path],[wakeup_reason] - -l,[lpc_port],[ioc_channel_path] + The device model configuration command syntax for IOC mediator is:: - - ``ioc_channel_path`` is an absolute path for communication between IOC - mediator and UART DM. - - ``lpc_port`` is com1 or com2. IOC mediator needs one unassigned lpc - port for data transfer between User OS and Service OS. - - ``wakeup_reason`` is IOC mediator boot up reason, where each bit represents - one wakeup reason. + -i,[ioc_channel_path],[wakeup_reason] + -l,[lpc_port],[ioc_channel_path] - Currently the wakeup reason bits supported by IOC firmware are: + - ``ioc_channel_path`` is an absolute path for communication between IOC + mediator and UART DM. + - ``lpc_port`` is com1 or com2. IOC mediator needs one unassigned lpc + port for data transfer between User OS and Service OS. + - ``wakeup_reason`` is IOC mediator boot up reason, where each bit represents + one wakeup reason. - - ``CBC_WK_RSN_BTN`` (bit 5): ignition button. - - ``CBC_WK_RSN_RTC`` (bit 9): RTC timer. - - ``CBC_WK_RSN_DOR`` (bit 11): Car door. - - ``CBC_WK_RSN_SOC`` (bit 23): SoC active/inactive. + Currently the wakeup reason bits supported by IOC firmware are: - As an example, the following commands are used to enable IOC feature, the - initial wakeup reason is ignition button, and cbc_attach uses ttyS1 for - TTY line discipline in UOS:: + - ``CBC_WK_RSN_BTN`` (bit 5): ignition button. + - ``CBC_WK_RSN_RTC`` (bit 9): RTC timer. + - ``CBC_WK_RSN_DOR`` (bit 11): Car door. + - ``CBC_WK_RSN_SOC`` (bit 23): SoC active/inactive. - -i /run/acrn/ioc_$vm_name,0x20 - -l com2,/run/acrn/ioc_$vm_name + As an example, the following commands are used to enable IOC feature, the + initial wakeup reason is ignition button, and cbc_attach uses ttyS1 for + TTY line discipline in UOS:: -:kbd:`-k, --kernel ` - Set the kernel (full path) for the UOS kernel. The maximum length is - 1023. The DM handles bzImage image format. + -i /run/acrn/ioc_$vm_name,0x20 + -l com2,/run/acrn/ioc_$vm_name - usage: ``-k /path/to/your/kernel_image`` + * - \-k, --kernel + - Set the kernel (full path) for the UOS kernel. The maximum path length is + 1023 characters. The DM handles bzImage image format. -:kbd:`-l, --lpc ` - (See **-i, --ioc_node**) + usage: ``-k /path/to/your/kernel_image`` -:kbd:`-m, --memsize ` - Setup total memory size for UOS. + * - \-l, --lpc + - (See **-i, --ioc_node**) - memory_size format is: "{K/k, B/b, M/m, G/g}", and size is an - integer. + * - \-m, --memsize + - Setup total memory size for UOS. - usage: ``-m 4g``: set UOS memory to 4 gigabytes. + memory_size format is: "{K/k, B/b, M/m, G/g}", and size is an + integer. -:kbd:`-p, --pincpu ` - Pin host CPU to appointed vCPU: + usage: ``-m 4g``: set UOS memory to 4 gigabytes. - - vcpu is the ID of the CPU seen by the UOS, and - - hostcpu is the physical CPU ID on the system. + * - \-p, --pincpu + - Pin host CPU to appointed vCPU: - Example: ``-p "1:2"`` means pin the 2nd physical cpu to 1st vcpu in UOS + - ``vcpu`` is the ID of the CPU seen by the UOS, and + - ``hostcpu`` is the physical CPU ID on the system. -:kbd:`--ptdev_no_reset` - Disable reset check for pci device. - When assigning a PCI device as a passthrough device, we will reset it - first to get it to a valid device state. So if the device doesn't have - the reset capability, the passthrough will fail. The PCI device reset - can be disabled using this option. + Example: ``-p "1:2"`` means pin the 2nd physical cpu to 1st vcpu in UOS -:kbd:`-r, --ramdisk ` - Set the ramdisk (full path) for the UOS. The maximum length is 1023. - The supported ramdisk format depends on your UOS kernel configuration. + * - \--ptdev_no_reset + - Disable reset check for pci device. + When assigning a PCI device as a passthrough device, we will reset it + first to get it to a valid device state. So if the device doesn't have + the reset capability, the passthrough will fail. The PCI device reset + can be disabled using this option. - usage: ``-r /path/to/your/ramdisk_image`` + * - \-r, --ramdisk + - Set the ramdisk (full path) for the UOS. The maximum length is 1023. + The supported ramdisk format depends on your UOS kernel configuration. -:kbd:`-s, --pci_slot ` - Setup PCI device configuration. + usage: ``-r /path/to/your/ramdisk_image`` - slot_config format is:: + * - \-s, --pci_slot + - Setup PCI device configuration. - ::,[,] - [:],[,] + slot_config format is:: - Where: + ::,[,] + [:],[,] - - ``slot`` is 0..31 - - ``func`` is 0..7 - - ``emul`` is a string describing the type of PCI device e.g. virtio-net - - ``config`` is an optional device-dependent string, used for - configuration. + Where: - Examples:: + - ``slot`` is 0..31 + - ``func`` is 0..7 + - ``emul`` is a string describing the type of PCI device e.g. virtio-net + - ``config`` is an optional device-dependent string, used for + configuration. - -s 7,xhci,1-2,2-2 + Examples:: - This configuration means the virtual xHCI will appear in PCI slot 7 - in UOS. Any physical USB device attached on 1-2 (bus 1, port 2) or - 2-2 (bus 2, port 2) will be detected by UOS and be used as expected. To - determine which bus and port a USB device is attached, you could run - `lsusb -t` in SOS. + -s 7,xhci,1-2,2-2 - :: + This configuration means the virtual xHCI will appear in PCI slot 7 + in UOS. Any physical USB device attached on 1-2 (bus 1, port 2) or + 2-2 (bus 2, port 2) will be detected by UOS and be used as expected. To + determine which bus and port a USB device is attached, you could run + `lsusb -t` in SOS. - -s 9,virtio-blk,/root/test.img + :: - This add virtual block in PCI slot 9 and use "/root/test.img" as the - disk image + -s 9,virtio-blk,/root/test.img -:kbd:`-U, --uuid ` - Set UUID for a VM. - Every VM is identified by a UUID. You can define that UUID with this - option. If you don't use this option, a default one - ("d2795438-25d6-11e8-864e-cb7a18b34643") will be used. + This add virtual block in PCI slot 9 and use "/root/test.img" as the + disk image - usage:: + * - \-U, --uuid + - Set UUID for a VM. + Every VM is identified by a UUID. You can define that UUID with this + option. If you don't use this option, a default one + ("d2795438-25d6-11e8-864e-cb7a18b34643") will be used. - -u "42795636-1d31-6512-7432-087d33b34756" + usage:: - set the newly created VM's UUID to "42795636-1d31-6512-7432-087d33b34756" + -u "42795636-1d31-6512-7432-087d33b34756" -:kbd:`-v, --version` - Show Device Model version + set the newly created VM's UUID to "42795636-1d31-6512-7432-087d33b34756" -:kbd:`--vsbl ` - Virtual Slim bootloader (vSBL) is the virtual bootloader supporting - booting of the UOS on the ACRN hypervisor platform. The vSBL design is - derived from Slim Bootloader, which follows a staged design approach - that provides hardware initialization and launching a payload that - provides the boot logic. + * - \-v, --version + - Show Device Model version - The vSBL image is installed on the Service OS root filesystem by the - service-os bundle, in ``/usr/share/acrn/bios/``. In the current design, - the vSBL supports booting Android guest OS or Linux guest OS using the - same vSBL image. For Android VM, the vSBL will load and verify trusty OS - first, and trusty OS will then load and verify Android OS according to - Android OS verification mechanism. + * - \--vsbl + - Virtual Slim bootloader (vSBL) is the virtual bootloader supporting + booting of the UOS on the ACRN hypervisor platform. The vSBL design is + derived from Slim Bootloader, which follows a staged design approach + that provides hardware initialization and launching a payload that + provides the boot logic. - usage:: + The vSBL image is installed on the Service OS root filesystem by the + service-os bundle, in ``/usr/share/acrn/bios/``. In the current design, + the vSBL supports booting Android guest OS or Linux guest OS using the + same vSBL image. For Android VM, the vSBL will load and verify trusty OS + first, and trusty OS will then load and verify Android OS according to + Android OS verification mechanism. - --vsbl /usr/share/acrn/bios/VSBL.bin + usage:: - uses ``/usr/share/acrn/bios/VSBL.bin`` as the vSBL image + --vsbl /usr/share/acrn/bios/VSBL.bin -: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 - method. If you want to use single-vector MSI interrupt, you can do so - using this option. + uses ``/usr/share/acrn/bios/VSBL.bin`` as the vSBL image -:kbd:`-Y, --mptgen` - Disable MPtable generation. - The MultiProcessor Specification (MPS) for the x86 architecture is an - open standard describing enhancements to both operating systems and - firmware that allows them to work with x86-compatible processors in a - multi-processor configuration. MPS covers Advanced Programmable - Interrupt Controller (APIC) architectures. + * - \-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 + method. If you want to use single-vector MSI interrupt, you can do so + using this option. - By default, DM will create the MPtable for you. Use this option to - disable it. + * - \-Y, --mptgen + - Disable MPtable generation. + The MultiProcessor Specification (MPS) for the x86 architecture is an + open standard describing enhancements to both operating systems and + firmware that allows them to work with x86-compatible processors in a + multi-processor configuration. MPS covers Advanced Programmable + Interrupt Controller (APIC) architectures. + + By default, DM will create the MPtable for you. Use this option to + disable it.