diff --git a/doc/api/devicemodel_api.rst b/doc/api/devicemodel_api.rst index 4ca7dd262..b09b74963 100644 --- a/doc/api/devicemodel_api.rst +++ b/doc/api/devicemodel_api.rst @@ -4,8 +4,8 @@ Device Model APIs ################# This section contains APIs for the Service VM Device Model services. Sources -for the Device Model are found in the devicemodel folder of the `ACRN -hypervisor GitHub repo`_ +for the Device Model are found in the ``devicemodel`` folder of the `ACRN +hypervisor GitHub repo`_. .. _ACRN hypervisor GitHub repo: https://github.com/projectacrn/acrn-hypervisor diff --git a/doc/api/hypercall_api.rst b/doc/api/hypercall_api.rst index 373108602..74b9a5232 100644 --- a/doc/api/hypercall_api.rst +++ b/doc/api/hypercall_api.rst @@ -4,7 +4,7 @@ Hypercall APIs ############## This section contains APIs for the hypercall services. Sources -for the Device Model are found in the `ACRN Hypervisor GitHub repo`_ +for the Device Model are found in the `ACRN Hypervisor GitHub repo`_. .. _ACRN Hypervisor GitHub repo: https://github.com/projectacrn/acrn-hypervisor/ diff --git a/doc/user-guides/acrn-shell.rst b/doc/user-guides/acrn-shell.rst index 5a80e226f..f210d24d6 100644 --- a/doc/user-guides/acrn-shell.rst +++ b/doc/user-guides/acrn-shell.rst @@ -12,47 +12,47 @@ The ACRN hypervisor shell supports the following commands: * - Command (and parameters) - Description * - help - - Display information about supported hypervisor shell commands + - Display information about supported hypervisor shell commands. * - version - - Display the HV version information + - Display the hypervisor version information. * - vm_list - - List all VMs, displaying the VM UUID, ID, name, and state ("Started"=running) + - List all VMs, displaying the VM UUID, ID, name, and state ("Started"=running). * - vcpu_list - - List all vCPUs in all VMs + - List all vCPUs in all VMs. * - vcpu_dumpreg - - Dump registers for a specific vCPU + - Dump registers for a specific vCPU. * - dump_host_mem - Dump the host memory region as specified by the start of the region ``hva`` (in hexadecimal) and its length ``length`` (in bytes, decimal number). * - dump_guest_mem - Dump a User VM (guest) memory region based on the VM ID (``vm_id``, in decimal), - the start of the memory region ``gva`` (in hexadecimal) and its length ``length`` (in bytes, decimal number). + the start of the memory region ``gva`` (in hexadecimal), and its length ``length`` (in bytes, decimal number). * - vm_console - Switch to the VM's console. Use :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`Space` to return to the ACRN - shell console + shell console. * - int - - List interrupt information per CPU + - List interrupt information per CPU. * - pt - - Show passthrough device information + - Show passthrough device information. * - vioapic - - Show virtual IOAPIC (vIOAPIC) information for a specific VM + - Show virtual IOAPIC (vIOAPIC) information for a specific VM. * - dump_ioapic - - Show native IOAPIC information + - Show native IOAPIC information. * - loglevel - * If no parameters are given, the command will return the level of - logging for the console, memory and npk + 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 fewer than three parameters are given, the - loglevels for the remaining areas will not be changed + loglevels for the remaining areas will not be changed. * - cpuid [subleaf] - - Display the CPUID leaf [subleaf], in hexadecimal + - Display the CPUID leaf [subleaf], in hexadecimal. * - rdmsr [-p] - - Read the Model-Specific Register (MSR) at index ``msr_index`` (in - hexadecimal) for CPU ID ``pcpu_id`` + - Read the model-specific register (MSR) at index ``msr_index`` (in + hexadecimal) for CPU ID ``pcpu_id``. * - wrmsr [-p] - - Write ``value`` (in hexadecimal) to the Model-Specific Register (MSR) at - index ``msr_index`` (in hexadecimal) for CPU ID ``pcpu_id`` + - Write ``value`` (in hexadecimal) to the model-specific register (MSR) at + index ``msr_index`` (in hexadecimal) for CPU ID ``pcpu_id``. Command Examples **************** @@ -62,7 +62,7 @@ The following sections provide further details and examples for some of these co vm_list ======= -``vm_list`` provides the name of each virtual machine and its corresponding ID and +The ``vm_list`` command provides the name of each virtual machine and its corresponding ID and state. .. figure:: images/shell_image8.png @@ -73,9 +73,9 @@ state. 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). +The ``vcpu_list`` command 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 @@ -85,10 +85,10 @@ STATE (init, paused, running, zombie or unknown). vcpu_dumpreg ============ -``vcpu_dumpreg vmid cpuid`` provides vCPU related information such as -registers values, etc. +The ``vcpu_dumpreg `` command provides vCPU-related +information such as register values. -In the following example, we dump vCPU0 RIP register value and get into +In the following example, we dump the vCPU0 RIP register value and get into the Service VM to search for the currently running function, using these commands:: @@ -110,8 +110,8 @@ function ``acpi_idle_do_entry``. dump_host_mem ============= -``dump_host_mem hva length`` provides the specified memory target data such as -the physical CPU (pCPU) number, etc. +The ``dump_host_mem `` command provides the specified memory +target data such as the physical CPU (pCPU) number. In this example, we know the pCPU active bitmap and physical CPU number physical memory address through @@ -119,7 +119,7 @@ physical memory address through ``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 +number. The pCPU active bitmap is 0x000000000000000f and pCPU number is 0x0000000000000004. .. figure:: images/shell_image12.png @@ -135,12 +135,12 @@ pCPU number is 0x0000000000000004. dump_guest_mem ============== -The ``dump_guest_mem`` command can dump guest memory according to the given -VM ID and guest virtual address (``gva``). +The ``dump_guest_mem `` command dumps guest memory +information according to the given VM ID and guest virtual address (``gva``). -In this example, we know the starting address of kernel text segment -in guest console or through the ``system.map`` (Note that the path for -``system.map`` depends on how we build the kernel) +In this example, we know the starting address of the kernel text segment +in the guest console or through the ``system.map``. (Note that the path for +``system.map`` depends on how we build the kernel.) .. figure:: images/shell_image19.png :align: center @@ -155,14 +155,15 @@ in guest console or through the ``system.map`` (Note that the path for vm_console =========== -The ``vm_console`` command switches the ACRN's console to become the VM's console. +The ``vm_console `` command switches the ACRN's console to become the +VM's console. Press :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`Space` to return to the ACRN shell console. vioapic ======= -``vioapic `` shows the virtual IOAPIC information for a specific -VM. In the following figure, we show the virtual IOPIC information for +The ``vioapic `` command shows the virtual IOAPIC information for a specific +VM. In the following figure, we show the virtual IOAPIC information for VM1: .. figure:: images/shell_image6.png @@ -173,7 +174,7 @@ VM1: dump_ioapic =========== -``dump_ioapic`` provides IOAPIC information and we can get IRQ number, +The ``dump_ioapic`` command provides IOAPIC information and we can get IRQ number, IRQ vector number, etc. .. figure:: images/shell_image14.png @@ -184,9 +185,9 @@ IRQ vector number, etc. pt == -``pt`` provides passthrough detailed information, such as the virtual -machine number, interrupt type, interrupt request, interrupt vector, -trigger mode, etc. +The ``pt`` command provides passthrough detailed information, such as the +virtual machine number, interrupt type, interrupt request, interrupt vector, +and trigger mode. .. figure:: images/shell_image13.png :align: center @@ -196,8 +197,8 @@ trigger mode, etc. int === -``int`` provides interrupt information on all CPUs and their corresponding -interrupt vector. +The ``int`` command provides interrupt information on all CPUs and their +corresponding interrupt vector. .. figure:: images/shell_image17.png :align: center @@ -207,7 +208,7 @@ interrupt vector. cpuid ===== -``cpuid [subleaf]`` provides the CPUID leaf [subleaf] in +The ``cpuid [subleaf]`` command provides the CPUID leaf [subleaf] in hexadecimal. .. figure:: images/shell_image15.png @@ -218,10 +219,10 @@ hexadecimal. rdmsr ===== -We can read model specific register (MSR) to get register +We can read a model-specific register (MSR) to get register values through ``rdmsr [-p] ``. -In the following example, we can get IA32_APIC_BASE value of pCPU 0 through +In the following example, we can get the IA32_APIC_BASE value of pCPU 0 through the command:: rdmsr -p0 1b @@ -241,10 +242,10 @@ and see that 1B (Hexadecimal) is the IA32_APIC_BASE MSR address. wrmsr ===== -We can write model specific register (MSR) to set register +We can write to a model-specific register (MSR) to set register values through ``wrmsr [-p] ``. -In the following example, we can set IA32_APIC_BASE value of pCPU 1 through +In the following example, we can set the IA32_APIC_BASE value of pCPU 1 through the command:: wrmsr -p1 1b 0xfee00c00 diff --git a/doc/user-guides/hv-parameters.rst b/doc/user-guides/hv-parameters.rst index d803f993f..ea50c7c7b 100644 --- a/doc/user-guides/hv-parameters.rst +++ b/doc/user-guides/hv-parameters.rst @@ -11,17 +11,17 @@ The ACRN hypervisor supports the following parameter: +-----------------+-----------------------------+----------------------------------------------------------------------------------------+ | Parameter | Value | Description | +=================+=============================+========================================================================================+ -| | disabled | This disables the serial port completely. | +| | disabled | This value disables the serial port completely. | | +-----------------------------+----------------------------------------------------------------------------------------+ -| ``uart=`` | bdf@ | This sets the serial port PCI BDF (in HEX), e.g. ``bdf@0xc1`` | +| ``uart=`` | bdf@ | This value sets the serial port PCI BDF (in HEX), for example, ``bdf@0xc1``. | | | | | | | | BDF: Bus, Device, and Function (in HEX) of the serial PCI device. The BDF is packed | | | | into a 16-bit WORD with format (B:8, D:5, F:3). For example, PCI device ``0:18.1`` | -| | | becomes ``0xc1`` | +| | | becomes ``0xc1``. | | +-----------------------------+----------------------------------------------------------------------------------------+ -| | port@ | This sets the serial port PIO address, e.g. ``uart=port@0x3F8`` | +| | port@ | This value sets the serial port PIO address, for example, ``uart=port@0x3F8``. | | +-----------------------------+----------------------------------------------------------------------------------------+ -| | mmio@ | This sets the serial port MMIO address, e.g. ``uart=mmio@0xfe040000`` | +| | mmio@ | This value sets the serial port MMIO address, for example, ``uart=mmio@0xfe040000``. | +-----------------+-----------------------------+----------------------------------------------------------------------------------------+ The Generic hypervisor parameters are specified in the GRUB multiboot/multiboot2 command.