github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-07-04 11:07:51 +00:00
Code Issues Projects Releases Wiki Activity

doc: improve acrn-dm param layout

Browse Source 
Use a table instead of a dictionary list to make the parameter
description layout more readable.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder 2018-12-12 10:57:10 -08:00 committed by David Kinder
parent 21a5b30865
commit 6dec166779
1 changed files with 159 additions and 155 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

314
doc/user-guides/acrn-dm-parameters.rst
View File

@ -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: Here are descriptions for each of these ``acrn-dm`` command line parameters:
:kbd:`-A, --acpi` .. list-table::
Create ACPI tables. :widths: 22 78
With this option, DM will build an ACPI table into its VMs F-Segment :header-rows: 0
(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.
:kbd:`-B, --bootargs <bootargs>` * - \-A, --acpi
Set the UOS kernel command line arguments. - Create ACPI tables.
The maximum length is 1023. With this option, DM will build an ACPI table into its VMs F-Segment
The bootargs string will be passed to the kernel as its cmdline. (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 <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 <cpus>` specifies the kernel log level at 7
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).
:kbd:`--enable_trusty` * - \-c, --ncpus <cpus>
Enable trusty for guest. - Set number of CPUs for UOS. This number is an integer and must not be
For Android guest OS, ACRN provides a VM environment with two worlds: more than the total number of CPUs in the system, minus one (which is
normal world and trusty world. The Android OS runs in the the normal used by the SOS).
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. * - \--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 <GVT_args>` By default, the trusty world is disabled. Use this option to enable it.
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`` * - \-G, --gvtargs <GVT_args>
- 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 Where:
- ``gvt_low_gm_sz``: GVT-g hidden gfx memory size, unit is MB
- ``gvt_fence_sz``: the number of fence registers
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 -G "10 128 6"
memory, and 6 fence registers.
:kbd:`-h, --help` sets up 10Mb for GVT-g aperture, 128M for GVT-g hidden
Show a summary of commands. memory, and 6 fence registers.
:kbd:`-i, --ioc_node <ioc_mediator_parameters>` * - \-h, --help
IOC (IO Controller) is a bridge of an SoC to communicate with Vehicle Bus. - Show a summary of commands.
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.)
IOC DM opens ``/dev/ptmx`` device to create a peer PTY devices, IOC DM uses * - \-i, --ioc_node <ioc_mediator_parameters>
these to communicate with UART DM since UART DM needs a TTY capable - IOC (IO Controller) is a bridge of an SoC to communicate with Vehicle Bus.
device as its backend. 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] The device model configuration command syntax for IOC mediator is::
-l,[lpc_port],[ioc_channel_path]
- ``ioc_channel_path`` is an absolute path for communication between IOC -i,[ioc_channel_path],[wakeup_reason]
mediator and UART DM. -l,[lpc_port],[ioc_channel_path]
- ``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: - ``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. Currently the wakeup reason bits supported by IOC firmware are:
- ``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 - ``CBC_WK_RSN_BTN`` (bit 5): ignition button.
initial wakeup reason is ignition button, and cbc_attach uses ttyS1 for - ``CBC_WK_RSN_RTC`` (bit 9): RTC timer.
TTY line discipline in UOS:: - ``CBC_WK_RSN_DOR`` (bit 11): Car door.
- ``CBC_WK_RSN_SOC`` (bit 23): SoC active/inactive.
-i /run/acrn/ioc_$vm_name,0x20 As an example, the following commands are used to enable IOC feature, the
-l com2,/run/acrn/ioc_$vm_name initial wakeup reason is ignition button, and cbc_attach uses ttyS1 for
TTY line discipline in UOS::
:kbd:`-k, --kernel <kernel_image_path>` -i /run/acrn/ioc_$vm_name,0x20
Set the kernel (full path) for the UOS kernel. The maximum length is -l com2,/run/acrn/ioc_$vm_name
1023. The DM handles bzImage image format.
usage: ``-k /path/to/your/kernel_image`` * - \-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.
:kbd:`-l, --lpc <lpc_device_configuration>` usage: ``-k /path/to/your/kernel_image``
(See **-i, --ioc_node**)
:kbd:`-m, --memsize <memory_size>` * - \-l, --lpc <lpc_device_configuration>
Setup total memory size for UOS. - (See **-i, --ioc_node**)
memory_size format is: "<size>{K/k, B/b, M/m, G/g}", and size is an * - \-m, --memsize <memory_size>
integer. - Setup total memory size for UOS.
usage: ``-m 4g``: set UOS memory to 4 gigabytes. memory_size format is: "<size>{K/k, B/b, M/m, G/g}", and size is an
integer.
:kbd:`-p, --pincpu <vcpu:hostcpu>` usage: ``-m 4g``: set UOS memory to 4 gigabytes.
Pin host CPU to appointed vCPU:
- vcpu is the ID of the CPU seen by the UOS, and * - \-p, --pincpu <vcpu:hostcpu>
- hostcpu is the physical CPU ID on the system. - 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` Example: ``-p "1:2"`` means pin the 2nd physical cpu to 1st vcpu in UOS
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.
:kbd:`-r, --ramdisk <ramdisk_image_path>` * - \--ptdev_no_reset
Set the ramdisk (full path) for the UOS. The maximum length is 1023. - Disable reset check for pci device.
The supported ramdisk format depends on your UOS kernel configuration. 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 <ramdisk_image_path>
- 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 <slot_config>` usage: ``-r /path/to/your/ramdisk_image``
Setup PCI device configuration.
slot_config format is:: * - \-s, --pci_slot <slot_config>
- Setup PCI device configuration.
<bus>:<slot>:<func>,<emul>[,<config>] slot_config format is::
<slot>[:<func>],<emul>[,<config>]
Where: <bus>:<slot>:<func>,<emul>[,<config>]
<slot>[:<func>],<emul>[,<config>]
- ``slot`` is 0..31 Where:
- ``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:: - ``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 -s 7,xhci,1-2,2-2
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.
:: 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 -s 9,virtio-blk,/root/test.img
disk image
:kbd:`-U, --uuid <uuid>` This add virtual block in PCI slot 9 and use "/root/test.img" as the
Set UUID for a VM. disk image
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, --uuid <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` set the newly created VM's UUID to "42795636-1d31-6512-7432-087d33b34756"
Show Device Model version
:kbd:`--vsbl <vsbl_file_path>` * - \-v, --version
Virtual Slim bootloader (vSBL) is the virtual bootloader supporting - Show Device Model version
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 * - \--vsbl <vsbl_file_path>
service-os bundle, in ``/usr/share/acrn/bios/``. In the current design, - Virtual Slim bootloader (vSBL) is the virtual bootloader supporting
the vSBL supports booting Android guest OS or Linux guest OS using the booting of the UOS on the ACRN hypervisor platform. The vSBL design is
same vSBL image. For Android VM, the vSBL will load and verify trusty OS derived from Slim Bootloader, which follows a staged design approach
first, and trusty OS will then load and verify Android OS according to that provides hardware initialization and launching a payload that
Android OS verification mechanism. 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` uses ``/usr/share/acrn/bios/VSBL.bin`` as the vSBL image
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.
:kbd:`-Y, --mptgen` * - \-W, --virtio_msix
Disable MPtable generation. - This option forces virtio to use single-vector MSI.
The MultiProcessor Specification (MPS) for the x86 architecture is an By default, any virtio-based devices will use MSI-X as its interrupt
open standard describing enhancements to both operating systems and method. If you want to use single-vector MSI interrupt, you can do so
firmware that allows them to work with x86-compatible processors in a using this option.
multi-processor configuration. MPS covers Advanced Programmable
Interrupt Controller (APIC) architectures.
By default, DM will create the MPtable for you. Use this option to * - \-Y, --mptgen
disable it. - 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.