From 7bcd7054e54b391529062fe23982b8d928e508c1 Mon Sep 17 00:00:00 2001 From: "David B. Kinder" Date: Mon, 10 Dec 2018 16:05:07 -0800 Subject: [PATCH] doc: additional DM parameter documentation Update the device model HLD with additional parameter documentation Tracked-On: #2021 Signed-off-by: David B. Kinder --- doc/developer-guides/hld/hld-devicemodel.rst | 225 ++++++++++++++++++- 1 file changed, 224 insertions(+), 1 deletion(-) diff --git a/doc/developer-guides/hld/hld-devicemodel.rst b/doc/developer-guides/hld/hld-devicemodel.rst index 783c5a9ac..82c88d6fb 100644 --- a/doc/developer-guides/hld/hld-devicemodel.rst +++ b/doc/developer-guides/hld/hld-devicemodel.rst @@ -46,7 +46,7 @@ ISA, and PCI emulation. Configuration ************* -The acrn-dm should run according to below command line configuration +The acrn-dm runs using these command line configuration options: .. code-block:: none @@ -90,6 +90,229 @@ options: --intr_monitor: enable interrupt storm monitor, params: threshold/s,probe-period(s),delay_time(ms),delay_duration(ms) +acrn-dm parameters +================== + +Here are further descriptions for each of these parameters: + +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. + +h, help + Show a summary of commands + +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. + +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. + +v, version + Show DM version + +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. + + By default, the trusty world is disabled. Use this option to enable it. + +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. + +k, kernel + Set the kernel (full path) for the UOS kernel. The maximum length is + 1023. The DM handles bzImage image format. + + usage: -k /path/to/your/kernel_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. + + usage: -r /path/to/your/ramdisk_image + +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. + + Example: -B "loglevel=7": it specifies the kernel log level at 7 + +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). + +p, pincpu + Pin host CPU to appointed vCPU: + + - vcpu is the ID of the CPU seen by the UOS, and + - hostcpu is the physical CPU ID on the system. + + Example: -p "1:2" means pin the 2nd physical cpu to 1st vcpu in UOS + +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. + + Examples:: + + -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 + +m, memsize + Setup total memory size for UOS + + memory_size format is: "{K/k, B/b, M/m, G/g}", and size is an + integer. + + usage: -m 4g: set uos memory to 4 gigabytes. + +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. + + usage:: + + -u "42795636-1d31-6512-7432-087d33b34756" + + set the newly created VM's UUID to "42795636-1d31-6512-7432-087d33b34756" + +i, ioc_node + (See **l, lpc** description) + +l, lpc + 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. (These parameters are only available on a + platform with IOC.) + + 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. + + The device model configuration command syntax for IOC mediator is:: + + -i,[ioc_channel_path],[wakeup_reason] + -l,[lpc_port],[ioc_channel_path] + + - "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. + + Currently the wakeup reason bits supported by IOC firmware are: + + - 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. + + 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:: + + -i /run/acrn/ioc_$vm_name,0x20 + -l com2,/run/acrn/ioc_$vm_name + +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. + + 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. + + usage:: + + --vsbl /usr/share/acrn/bios/VSBL.bin + + uses ``/usr/share/acrn/bios/VSBL.bin`` as the vSBL image + +G, gvtargs + ACRN implements GVT-g for graphics virtualization (aka AcrnGT). This + option allows you to set some of its parameters. + + GVT_args format: "gvt_high_gm_sz gvt_low_gm_sz gvt_fence_sz" + + Where: + + - 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 + + Example:: + + -G "10 128 6" + + sets up 10Mb for GVT-g aperture, 128M for GVT-g hidden + memory, and 6 fence registers. + + Here's an example showing how to run a VM with: - Build ACPI table