github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-09-06 11:20:32 +00:00
Code Issues Projects Releases Wiki Activity

doc: Reorganize documentation site content

Browse Source 
Take the existing ACRN technical documentation and reorganize its
presentation to be persona and use-case based, in preparation for adding
new scenario/use-case based architecture introduction and getting
started documents.

Introduce a more graphical home page and theme color tweaks.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder
2019-07-31 16:08:40 -07:00
committed by David Kinder
parent e188e1f245
commit 11d4f4159f
300 changed files with 297 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,327 +0,0 @@
.. _acrn-dm_parameters:
Device Model Parameters
#######################
Hypervisor Device Model (DM) is a QEMU-like application in the Service
OS (SOS) responsible for creating a UOS VM and then performing devices
emulation based on command line configurations, as introduced in
:ref:`hld-devicemodel`.
Here are descriptions for each of these ``acrn-dm`` command line parameters:
.. list-table::
:widths: 22 78
:header-rows: 0
* - :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.
* - :kbd:`-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.
Example::
-B "loglevel=7"
specifies the kernel log level at 7
* - :kbd:`-c, --ncpus <cpus>`
- 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:`--debugexit`
- Enable guest to write io port 0xf4 to exit guest. It's mainly used by
guest unit test.
* - :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:
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.
* - :kbd:`-G, --gvtargs <GVT_args>`
- 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.
* - :kbd:`-h, --help`
- Show a summary of commands.
* - :kbd:`-i, --ioc_node <ioc_mediator_parameters>`
- 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.)
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
* - :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.
usage: ``-k /path/to/your/kernel_image``
* - :kbd:`-l, --lpc <lpc_device_configuration>`
- (See :kbd:`-i, --ioc_node`)
* - :kbd:`-m, --memsize <memory_size>`
- Setup total memory size for UOS.
memory_size format is: "<size>{K/k, B/b, M/m, G/g}", and size is an
integer.
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:
- ``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
* - :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
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>`
- 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``
* - :kbd:`-s, --pci_slot <slot_config>`
- Setup PCI device configuration.
slot_config format is::
<bus>:<slot>:<func>,<emul>[,<config>]
<slot>[:<func>],<emul>[,<config>]
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
* - :kbd:`-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.
usage::
-u "42795636-1d31-6512-7432-087d33b34756"
set the newly created VM's UUID to ``42795636-1d31-6512-7432-087d33b34756``
* - :kbd:`-v, --version`
- Show Device Model version
* - :kbd:`--vsbl <vsbl_file_path>`
- 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.
.. note::
vSBL is currently only supported on Apollo Lake processors.
usage::
--vsbl /usr/share/acrn/bios/VSBL.bin
uses ``/usr/share/acrn/bios/VSBL.bin`` as the vSBL image
* - :kbd:`--ovmf [w,]<ovmf_file_path>`
- Open Virtual Machine Firmware (OVMF) is an EDK II based project to enable
UEFI support for Virtual Machines.
ACRN does not support off-the-shelf OVMF builds targeted for QEMU and
KVM. Compatible OVMF images are included in the source tree, under
``devicemodel/bios/``.
usage::
--ovmf /usr/share/acrn/bios/OVMF.fd
uses ``/usr/share/acrn/bios/OVMF.fd`` as the OVMF image
ACRN supports option "w" of OVMF. To preserve any change of OVMF NV data
store section, using this option to enable NV data store section writeback.
usage::
--ovmf w,/usr/share/acrn/bios/OVMF.fd
* - :kbd:`--virtio_poll <poll_interval>`
- Enable virtio poll mode with poll interval xxx ns.
Example::
--virtio_poll 1000000
enable virtio poll mode with poll interval 1ms.
* - :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
method. If you want to use single-vector MSI interrupt, you can do so
using this option.
* - :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.
By default, DM will create the MPtable for you. Use this option to
disable it.
* - :kbd:`--lapic_pt`
- This option is to create a VM with the local APIC (LAPIC) passed-through.
With this option, a VM is created with ``LAPIC_PASSTHROUGH`` and
``IO_COMPLETION_POLLING`` mode. This option is typically used for hard
realtime scenarios.
By default, this option is not enabled.
* - :kbd:`--rtvm`
- This option is used to create a VM with realtime attributes.
With this option, a VM is created with ``GUEST_FLAG_RT`` and
``GUEST_FLAG_IO_COMPLETION_POLLING`` mode. This kind of VM is
generally used for soft realtime scenarios (without ``--lapic_pt``) or
hard realtime scenarios (with ``--lapic_pt``). With ``GUEST_FLAG_RT``,
the Service OS (SOS) cannot interfere with this kind of VM when it is
running. It can only be powered off from inside the VM itself.
By default, this option is not enabled.

227
doc/user-guides/acrn-shell.rst
View File

@@ -1,227 +0,0 @@
.. _acrnshell:
ACRN Shell Commands
###################
The ACRN hypervisor shell supports the following commands:
.. list-table::
:header-rows: 1
:widths: 40 60
* - Command (and parameters)
- Description
* - help
- Display information about supported hypervisor shell commands
* - version
- Display the HV version information
* - vm_list
- List all VMs, displaying the VM UUID, ID, name, and state ("Started"=running)
* - vcpu_list
- List all vCPUs in all VMs
* - vcpu_dumpreg <vm_id> <vcpu_id>
- Dump registers for a specific vCPU
* - dumpmem <hva> <length>
- Dump host memory, starting at a given address, and for a given length
(in bytes)
* - vm_console <vm_id>
- Switch to the VM's console. Use :kbd:`Ctrl+Spacebar` to return to the ACRN
shell console
* - int
- List interrupt information per CPU
* - pt
- Show pass-through device information
* - vioapic <vm_id>
- Show virtual IOAPIC (vIOAPIC) information for a specific VM
* - dump_ioapic
- Show native IOAPIC information
* - loglevel <console_loglevel> <mem_loglevel> <npk_loglevel>
- * If no parameters are given, the command will return the level of
logging for the console, memory and npk
* Give (up to) three parameters between ``0`` (none) and ``6`` (verbose)
to set the loglevel for the console, memory, and npk (in
that order). If less than three parameters are given, the
loglevels for the remaining areas will not be changed
* - cpuid <leaf> [subleaf]
- Display the CPUID leaf [subleaf], in hexadecimal
* - rdmsr [-p<pcpu_id>] <msr_index>
- Read the Model-Specific Register (MSR) at index ``msr_index`` (in
hexadecimal) for CPU ID ``pcpu_id``
* - wrmsr [-p<pcpu_id>] <msr_index> <value>
- Write ``value`` (in hexadecimal) to the Model-Specific Register (MSR) at
index ``msr_index`` (in hexadecimal) for CPU ID ``pcpu_id``
Command examples
****************
The following sections provide further details and examples for some of these commands.
vm_list
=======
``vm_list`` provides the name of each virtual machine and its corresponding ID and
state.
.. figure:: images/shell_image8.png
:align: center
vm_list information
vcpu_list
=========
``vcpu_list`` provides information about virtual CPUs (vCPU), including
the VM ID, PCPU ID, VCPU ID, VCPU ROLE (primary or secondary), and VCPU
STATE (init, paused, running, zombie or unknown).
.. figure:: images/shell_image7.png
:align: center
vcpu_list information
vcpu_dumpreg
============
``vcpu_dumpreg vmid cpuid`` provides vCPU related information such as
registers values, etc.
In the following example, we dump vCPU0 RIP register value and get into
the SOS to search for the currently running function, using these
commands::
cat /proc/kallsyms | grep RIP_value
As you can see, vCPU0 is running in
function ``acpi_idle_do_entry``.
.. figure:: images/shell_image10.png
:align: center
vcpu_dumpreg information
.. figure:: images/shell_image9.png
:align: center
system map information
dumpmem
=======
``dumpmem mem_address`` provides the specified memory target data such as
the physical CPU (pCPU) number, etc.
In this example, we know the pCPU active bitmap and physical CPU number
physical memory address through
``build/hypervisor/acrn.map``. (Note that the path for
``acrn.map`` depends on how we build the hypervisor.)
Then we can dump the memory address of the pCPU active bitmap and CPU
number, we will know that pCPU active bitmap is 0x000000000000000f and
pCPU number is 0x0000000000000004.
.. figure:: images/shell_image12.png
:align: center
dumpmem information
.. figure:: images/shell_image11.png
:align: center
acrn map information
vm_console
===========
The ``vm_console`` command switches the ACRN's console to become the VM's console.
Use a :kbd:`Ctrl-Spacebar` to return to the ACRN shell console.
vioapic
=======
``vioapic <vm_id>`` shows the virtual IOAPIC information for a specific
VM. In the following figure, we show the virtual IOPIC information for
VM1:
.. figure:: images/shell_image6.png
:align: center
vioapic information
dump_ioapic
===========
``dump_ioapic`` provides IOAPIC information and we can get IRQ number,
IRQ vector number, etc.
.. figure:: images/shell_image14.png
:align: center
dump_ioapic information
pt
==
``pt`` provides pass-through detailed information, such as the virtual
machine number, interrupt type, interrupt request, interrupt vector,
trigger mode, etc.
.. figure:: images/shell_image13.png
:align: center
pt information
int
===
``int`` provides interrupt information on all CPUs and their corresponding
interrupt vector.
.. figure:: images/shell_image17.png
:align: center
int information
cpuid
=====
``cpuid <leaf> [subleaf]`` provides the CPUID leaf [subleaf] in
hexadecimal.
.. figure:: images/shell_image15.png
:align: center
cpuid information
rdmsr
=====
We can read model specific register (MSR) to get register
values through ``rdmsr [-p<pcpu_id>] <msr_index>``.
In the following example, we can get IA32_APIC_BASE value of pCPU 0 through
the command::
rdmsr -p0 1b
and see that 1B (Hexadecimal) is the IA32_APIC_BASE MSR address.
.. figure:: images/shell_image16.png
:align: center
IA32_APIC_BASE register information
.. figure:: images/shell_image18.png
:align: center
rdmsr information
wrmsr
=====
We can write model specific register (MSR) to set register
values through ``wrmsr [-p<pcpu_id>] <msr_index> <value>``.
In the following example, we can set IA32_APIC_BASE value of pCPU 1 through
the command::
wrmsr -p1 1b 0xfee00c00

BIN
doc/user-guides/images/i915-image1.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 10 KiB

BIN
doc/user-guides/images/i915-image2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 37 KiB

BIN
doc/user-guides/images/i915-image3.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 7.3 KiB

BIN
doc/user-guides/images/i915-image4.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 13 KiB

BIN
doc/user-guides/images/i915-image5.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 13 KiB

BIN
doc/user-guides/images/shell_image10.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 43 KiB

BIN
doc/user-guides/images/shell_image11.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 7.5 KiB

BIN
doc/user-guides/images/shell_image12.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 5.1 KiB

BIN
doc/user-guides/images/shell_image13.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 29 KiB

BIN
doc/user-guides/images/shell_image14.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 28 KiB

BIN
doc/user-guides/images/shell_image15.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 16 KiB

BIN
doc/user-guides/images/shell_image16.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 35 KiB

BIN
doc/user-guides/images/shell_image17.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 9.0 KiB

BIN
doc/user-guides/images/shell_image18.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 1.1 KiB

BIN
doc/user-guides/images/shell_image6.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 147 KiB

BIN
doc/user-guides/images/shell_image7.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 6.5 KiB

BIN
doc/user-guides/images/shell_image8.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 4.7 KiB

BIN
doc/user-guides/images/shell_image9.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 22 KiB

13
doc/user-guides/index.rst
View File

@@ -1,13 +0,0 @@
.. _userguides:
User Guides
###########
.. toctree::
:maxdepth: 2
:glob:
acrn-shell.rst
kernel-parameters.rst
acrn-dm-parameters.rst
tools.rst

660
doc/user-guides/kernel-parameters.rst
View File

@@ -1,660 +0,0 @@
.. _kernel-parameters:
ACRN Kernel Parameters
######################
Generic kernel parameters
*************************
A number of kernel parameters control the behavior of ACRN-based systems. Some
are applicable to the Service OS (SOS) kernel, others to the User OS (UOS)
kernel, and some are applicable to both.
This section focuses on generic parameters from the Linux kernel which are
relevant for configuring or debugging ACRN-based systems.
.. list-table::
:header-rows: 1
:widths: 10,10,50,30
* - Parameter
- Used in SOS or UOS
- Description
- Usage example
* - module_blacklist
- SOS
- A comma-separated list of modules that should not be loaded.
Useful to debug or work
around issues related to specific modules.
- ::
module_blacklist=dwc3_pci
* - no_timer_check
- SOS,UOS
- Disables the code which tests for broken timer IRQ sources.
- ::
no_timer_check
* - console
- SOS,UOS
- Output console device and options.
``tty<n>``
Use the virtual console device <n>.
``ttyS<n>[,options]``
Use the specified serial port and options. Default options are
``9600n8`` meaning 9600 baud, no parity, 8 bits. Options are of the form *bbbbpnf*,
where:
| *bbbb* is baud rate, for example 9600;
| *p* is parity, one of ``n``, ``o``, or ``e`` (for none, odd, or even),
| *n* is number of bits (typically 8),
| *f* is flow control (``r`` for RTS, or left blank)
``hvc<n>``
Use the hypervisor console device <n>. (This is for both Xen and
PowerPC hypervisors.)
- ::
console=tty0
console=ttyS0
console=hvc0
* - loglevel
- SOS
- All Kernel messages with a loglevel less than the console loglevel will
be printed to the console. The loglevel can also be changed with
``klogd`` or other programs. The loglevels are defined as follows:
.. list-table::
:header-rows: 1
* - loglevel value
- Definition
* - 0 (KERN_EMERG)
- system is unusable
* - 1 (KERN_ALERT)
- action must be taken immediately
* - 2 (KERN_CRIT)
- critical conditions
* - 3 (KERN_ERR)
- error conditions
* - 4 (KERN_WARNING)
- warning conditions
* - 5 (KERN_NOTICE)
- normal but significant condition
* - 6 (KERN_INFO)
- informational
* - 7 (KERN_DEBUG)
- debug-level messages
- ::
loglevel=7
* - ignore_loglevel
- UOS
- Ignoring loglevel setting will print **all**
kernel messages to the console. Useful for debugging.
We also add it as printk module parameter, so users
could change it dynamically, usually by changing
``/sys/module/printk/parameters/ignore_loglevel``.
- ::
ignore_loglevel
* - log_buf_len
- UOS
- Sets the size of the printk ring buffer,
in bytes. n must be a power of two and greater
than the minimal size. The minimal size is defined
by LOG_BUF_SHIFT kernel config parameter. There is
also CONFIG_LOG_CPU_MAX_BUF_SHIFT config parameter
that allows to increase the default size depending on
the number of CPUs. See init/Kconfig for more details."
- ::
log_buf_len=16M
* - consoleblank
- SOS,UOS
- The console blank (screen saver) timeout in
seconds. Defaults to 600 (10 minutes). A value of 0
disables the blank timer.
- ::
consoleblank=0
* - rootwait
- SOS,UOS
- Wait (indefinitely) for root device to show up.
Useful for devices that are detected asynchronously
(e.g. USB and MMC devices).
- ::
rootwait
* - root
- SOS,UOS
- Define the root filesystem
``/dev/<disk_name><decimal>``
represents the device number of the partition - device
number of disk plus the partition number
``/dev/<disk_name>p<decimal>``
same as above, this form is used when disk name of
the partitioned disk ends with a digit. To separate
disk name and partition slot, a 'p' is inserted.
``PARTUUID=00112233-4455-6677-8899-AABBCCDDEEFF``
representing the unique id of a partition if the
partition table provides it. The UUID may be either
an EFI/GPT UUID, or refer to an MSDOS
partition using the format SSSSSSSS-PP, where SSSSSSSS is a
zero-filled hexadecimal representation of the 32-bit
"NT disk signature", and PP is a zero-filled hexadecimal
representation of the 1-based partition number.
- ::
root=/dev/mmcblk0p1
root=/dev/vda2
root=PARTUUID=00112233-4455-6677-8899-AABBCCDDEEFF
* - rw
- SOS,UOS
- Mount root device read-write on boot
- ::
rw
* - tsc
- UOS
- Disable clocksource stability checks for TSC.
Format: <string>, where the only supported value is:
``reliable``:
Mark TSC clocksource as reliable, and disables clocksource
verification at runtime, and the stability checks done at bootup.
Used to enable high-resolution timer mode on older hardware, and in
virtualized environments.
- ::
tsc=reliable
* - cma
- SOS
- Sets the size of the kernel global memory area for
contiguous memory allocations, and optionally the
placement constraint by the physical address range of
memory allocations. A value of 0 disables CMA
altogether. For more information, see
``include/linux/dma-contiguous``.
- ::
cma=64M@0
* - hvlog
- SOS
- Reserve memory for the ACRN hypervisor log. The reserved space should not
overlap any other blocks (e.g. hypervisor's reserved space).
- ::
hvlog=2M@0x6de00000
* - memmap
- SOS
- Mark specific memory as reserved.
``memmap=nn[KMG]$ss[KMG]``
Region of memory to be reserved is from ``ss`` to ``ss+nn``,
using ``K``, ``M``, and ``G`` representing Kilobytes, Megabytes, and
Gigabytes, respectively.
- ::
memmap=0x400000$0x6da00000
* - ramoops.mem_address
ramoops.mem_size
ramoops.console_size
- SOS
- Ramoops is an oops/panic logger that writes its logs to RAM
before the system crashes. Ramoops uses a predefined memory area
to store the dump. See `Linux Kernel Ramoops oops/panic logger
<https://www.kernel.org/doc/html/v4.19/admin-guide/ramoops.html#ramoops-oops-panic-logger>`_
for details.
- ::
ramoops.mem_address=0x6da00000
ramoops.mem_size=0x400000
ramoops.console_size=0x200000
* - reboot_panic
- SOS
- Reboot in case of panic
The comma-delimited parameters are:
reboot_mode:
``w`` (warm), ``s`` (soft), ``c`` (cold), or ``g`` (gpio)
reboot_type:
``b`` (bios), ``a`` (acpi), ``k`` (kbd), ``t`` (triple), ``e`` (efi),
or ``p`` (pci)
reboot_cpu:
``s###`` (smp, and processor number to be used for rebooting)
reboot_force:
``f`` (force), or not specified.
- ::
reboot_panic=p,w
* - maxcpus
- UOS
- Maximum number of processors that an SMP kernel
will bring up during bootup.
``maxcpus=n`` where n >= 0 limits
the kernel to bring up ``n`` processors during system bootup.
Giving n=0 is a special case, equivalent to ``nosmp``,which
also disables the I/O APIC.
After bootup, you can bring up additional plugged CPUs by executing
``echo 1 > /sys/devices/system/cpu/cpuX/online``
- ::
maxcpus=1
* - nohpet
- UOS
- Don't use the HPET timer
- ::
nohpet
* - intel_iommu
- UOS
- Intel IOMMU driver (DMAR) option
``on``:
Enable intel iommu driver.
``off``:
Disable intel iommu driver.
``igfx_off``:
By default, gfx is mapped as normal device. If a gfx
device has a dedicated DMAR unit, the DMAR unit is
bypassed by not enabling DMAR with this option. In
this case, gfx device will use physical address for DMA.
- ::
intel_iommu=off
Intel GVT-g (AcrnGT) Parameters
*******************************
This table gives an overview of all the Intel GVT-g parameters that are
available to tweak the behavior of the graphics sharing (Intel GVT-g, aka
AcrnGT) capabilities in ACRN. The `GVT-g-kernel-options`_
section below has more details on a few select parameters.
.. list-table::
:header-rows: 1
:widths: 10,10,50,30
* - Parameter
- Used in SOS or UOS
- Description
- Usage example
* - i915.enable_gvt
- SOS
- Enable Intel GVT-g graphics virtualization support in the host
- ::
i915.enable_gvt=1
* - i915.enable_pvmmio
- SOS, UOS
- Control Para-Virtualized MMIO (PVMMIO). It batches sequential MMIO writes
into a shared buffer between the SOS and UOS
- ::
i915.enable_pvmmio=0x1F
* - i915.gvt_workload_priority
- SOS
- Define the priority level of UOS graphics workloads
- ::
i915.gvt_workload_priority=1
* - i915.enable_initial_modeset
- SOS
- On MRB, value must be ``1``. On NUC or UP2 boards, value must be
``0``. See :ref:`i915-enable-initial-modeset`.
- ::
i915.enable_initial_modeset=1
i915.enable_initial_modeset=0
* - i915.nuclear_pageflip
- SOS,UOS
- Force enable atomic functionality on platforms that don't have full support yet.
- ::
i915.nuclear_pageflip=1
* - i915.avail_planes_per_pipe
- SOS
- See :ref:`i915-avail-planes-owners`.
- ::
i915.avail_planes_per_pipe=0x01010F
* - i915.domain_plane_owners
- SOS
- See :ref:`i915-avail-planes-owners`.
- ::
i915.domain_plane_owners=0x011111110000
* - i915.domain_scaler_owner
- SOS
- See `i915.domain_scaler_owner`_
- ::
i915.domain_scaler_owner=0x021100
* - i915.enable_guc
- SOS
- Enable GuC load for HuC load.
- ::
i915.enable_guc=0x02
* - i915.avail_planes_per_pipe
- UOS
- See :ref:`i915-avail-planes-owners`.
- ::
i915.avail_planes_per_pipe=0x070F00
* - i915.enable_guc
- UOS
- Disable GuC
- ::
i915.enable_guc=0
* - i915.enable_hangcheck
- UOS
- Disable check GPU activity for detecting hangs.
- ::
i915.enable_hangcheck=0
* - i915.enable_fbc
- UOS
- Enable frame buffer compression for power savings
- ::
i915.enable_fbc=1
.. _GVT-g-kernel-options:
GVT-g (AcrnGT) Kernel Options details
=====================================
This section provides additional information and details on the kernel command
line options that are related to AcrnGT.
i915.enable_gvt
---------------
This option enables support for Intel GVT-g graphics virtualization
support in the host. By default, it's not enabled, so we need to add
``i915.enable_gvt=1`` in the SOS kernel command line. This is a Service
OS only parameter, and cannot be enabled in the User OS.
i915.enable_pvmmio
------------------
We introduce the feature named **Para-Virtualized MMIO** (PVMMIO)
to improve graphics performance of the GVT-g guest.
This feature batches sequential MMIO writes into a
shared buffer between the Service OS and User OS, and then submits a
para-virtualized command to notify to GVT-g in Service OS. This
effectively reduces the trap numbers of MMIO operations and improves
overall graphics performance.
The ``i915.enable_pvmmio`` option controls
the optimization levels of the PVMMIO feature: each bit represents a
sub-feature of the optimization. By default, all
sub-features of PVMMIO are enabled. They can also be selectively
enabled or disabled..
The PVMMIO optimization levels are:
* PVMMIO_ELSP_SUBMIT = 0x1 - Batch submission of the guest graphics
workloads
* PVMMIO_PLANE_UPDATE = 0x2 - Batch plane register update operations
* PVMMIO_PLANE_WM_UPDATE = 0x4 - Batch watermark registers update operations
* PVMMIO_MASTER_IRQ = 0x8 - Batch IRQ related registers
* PVMMIO_PPGTT_UPDATE = 0x10 - Use PVMMIO method to update the PPGTT table
of guest.
.. note:: This parameter works in both the Service OS and User OS, but
changes to one will affect the other. For example, if either SOS or UOS
disables the PVMMIO_PPGTT_UPDATE feature, this optimization will be
disabled for both.
i915.gvt_workload_priority
--------------------------
AcrnGT supports **Prioritized Rendering** as described in the
:ref:`GVT-g-prioritized-rendering` high-level design. This
configuration option controls the priority level of GVT-g guests.
Priority levels range from -1023 to 1023.
The default priority is zero, the same priority as the Service OS. If
the level is less than zero, the guest's priority will be lower than the
Service OS, so graphics preemption will work and the prioritized
rendering feature will be enabled. If the level is greater than zero,
UOS graphics workloads will preempt most of the SOS graphics workloads,
except for display updating related workloads that use a default highest
priority (1023).
Currently, all UOSes share the same priority.
This is a Service OS only parameters, and does
not work in the User OS.
.. _i915-enable-initial-modeset:
i915.enable_initial_modeset
---------------------------
At time, kernel graphics must be initialized with a valid display
configuration with full display pipeline programming in place before the
user space is initialized and without a fbdev & fb console.
When ``i915.enable_initial_modeset=1``, the FBDEV of i915 will not be
initialized, so users would not be able to see the fb console on screen.
If there is no graphics UI running by default, users will see black
screens displayed.
When ``i915.enable_initial_modeset=0`` in SOS, the plane restriction
(also known as plane-based domain ownership) feature will be disabled.
(See the next section and :ref:`plane_restriction` in the ACRN GVT-g
High Level Design for more information about this feature.)
In the current configuration, we will set
``i915.enable_initial_modeset=1`` in SOS and
``i915.enable_initial_modeset=0`` in UOS.
This parameter is not used on UEFI platforms.
.. _i915-avail-planes-owners:
i915.avail_planes_per_pipe and i915.domain_plane_owners
-------------------------------------------------------
Both Service OS and User OS are provided a set of HW planes where they
can display their contents. Since each domain provides its content,
there is no need for any extra composition to be done through SOS.
``i915.avail_planes_per_pipe`` and ``i915.domain_plane_owners`` work
together to provide the plane restriction (or plan-based domain
ownership) feature.
* i915.domain_plane_owners
On Intel's display hardware, each pipeline contains several planes, which are
blended
together by their Z-order and rendered to the display monitors. In
AcrnGT, we can control each planes' ownership so that the domains can
display contents on the planes they own.
The ``i915.domain_plane_owners`` parameter controls the ownership of all
the planes in the system, as shown in :numref:`i915-planes-pipes`. Each
4-bit nibble identifies the domain id owner for that plane and a group
of 4 nibbles represents a pipe. This is a Service OS only configuration
and cannot be modified at runtime. Domain ID 0x0 is for the Service OS,
the User OS use domain IDs from 0x1 to 0xF.
.. figure:: images/i915-image1.png
:width: 900px
:align: center
:name: i915-planes-pipes
i915.domain_plane_owners
For example, if we set ``i915.domain_plane_owners=0x010001101110``, the
plane ownership will be as shown in :numref:`i915-planes-example1` - SOS
(green) owns plane 1A, 1B, 4B, 1C, and 2C, and UOS #1 owns plane 2A, 3A,
4A, 2B, 3B and 3C.
.. figure:: images/i915-image2.png
:width: 900px
:align: center
:name: i915-planes-example1
i915.domain_plane_owners example
Some other examples:
* i915.domain_plane_owners=0x022211110000 - SOS (0x0) owns planes on pipe A;
UOS #1 (0x1) owns all planes on pipe B; and UOS #2 (0x2) owns all
planes on pipe C (since, in the representation in
:numref:`i915-planes-pipes` above, there are only 3 planes attached to
pipe C).
* i915.domain_plane_owners=0x000001110000 - SOS owns all planes on pipe A
and pipe C; UOS #1 owns plane 1, 2 and 3 on pipe B. Plane 4 on pipe B
is owned by the SOS so that if it wants to display notice message, it
can display on top of the UOS.
* i915.avail_planes_per_pipe
Option ``i915.avail_planes_per_pipe`` is a bitmask (shown in
:numref:`i915-avail-planes`) that tells the i915
driver which planes are available and can be exposed to the compositor.
This is a parameter that must to be set in each domain. If
``i915.avail_planes_per_pipe=0``, the plane restriction feature is disabled.
.. figure:: images/i915-image3.png
:width: 600px
:align: center
:name: i915-avail-planes
i915.avail_planes_per_pipe
For example, if we set ``i915.avail_planes_per_pipe=0x030901`` in SOS
and ``i915.avail_planes_per_pipe=0x04060E`` in UOS, the planes will be as
shown in :numref:`i915-avail-planes-example1` and
:numref:`i915-avail-planes-example1`:
.. figure:: images/i915-image4.png
:width: 500px
:align: center
:name: i915-avail-planes-example1
SOS i915.avail_planes_per_pipe
.. figure:: images/i915-image5.png
:width: 500px
:align: center
:name: i915-avail-planes-example2
UOS i915.avail_planes_per_pipe
``i915.avail_planes_per_pipe`` controls the view of planes from i915 drivers
inside of every domain, and ``i915.domain_plane_owners`` is the global
arbiter controlling which domain can present its content onto the
real hardware. Generally, they are aligned. For example, we can set
``i915.domain_plane_owners= 0x011111110000``,
``i915.avail_planes_per_pipe=0x00000F`` in SOS, and
``i915.avail_planes_per_pipe=0x070F00`` in domain 1, so every domain will
only flip on the planes they owns.
However, we don't force alignment: ``avail_planes_per_pipe`` might
not be aligned with the
setting of ``domain_plane_owners``. Consider this example:
``i915.domain_plane_owners=0x011111110000``,
``i915.avail_planes_per_pipe=0x01010F`` in SOS and
``i915.avail_planes_per_pipe=0x070F00`` in domain 1.
With this configuration, SOS will be able to render on plane 1B and
plane 1C, however, the content of plane 1B and plane 1C will not be
flipped onto the real hardware.
i915.domain_scaler_owner
========================
On each Intel GPU display pipeline, there are several plane scalers
to zoom in/out the planes. For example, if a 720p video is played
full-screen on a 1080p display monitor, the kernel driver will use a
scaler to zoom in the video plane to a 1080p image and present it onto a
display pipeline. (Refer to "Intel Open Source Graphics PRM Vol 7:
display" for the details.)
On Broxton platforms, Pipe A and Pipe B each
have two plane scalers, and Pipe C has one plane scaler. To support the
plane scaling in AcrnGT guest OS, we introduced the parameter
``i915.domain_scaler_owner``, to assign a specific scaler to the target
guest OS.
As with the parameter ``i915.domain_plane_owners``, each nibble of
``i915.domain_scaler_owner`` represents the domain id that owns the scaler;
every nibble (4 bits) represents a scaler and every group of 2 nibbles
represents a pipe. This is a Service OS only configuration and cannot be
modified at runtime. Domain ID 0x0 is for the Service OS, the User OS
use domain IDs from 0x1 to 0xF.
For example, if we set ``i915.domain_scaler_owner=0x021100``, the SOS
owns scaler 1A, 2A; UOS #1 owns scaler 1B, 2B; and UOS #2 owns scaler
1C.
i915.enable_hangcheck
=====================
This parameter enable detection of a GPU hang. When enabled, the i915
will start a timer to check if the workload is completed in a specific
time. If not, i915 will treat it as a GPU hang and trigger a GPU reset.
In AcrnGT, the workload in SOS and UOS can be set to different
priorities. If SOS is assigned a higher priority than the UOS, the UOS's
workload might not be able to run on the HW on time. This may lead to
the guest i915 triggering a hangcheck and lead to a guest GPU reset.
This reset is unnecessary so we use ``i915.enable_hangcheck=0`` to
disable this timeout check and prevent guest from triggering unnecessary
GPU resets.

10
doc/user-guides/tools.rst
View File

@@ -1,10 +0,0 @@
.. _tools:
Tools
#####
.. toctree::
:glob:
:maxdepth: 1
../misc/**