diff --git a/doc/release_notes/release_notes_3.0.1.rst b/doc/release_notes/release_notes_3.0.1.rst index 14e6f05d76..7eb98cd607 100644 --- a/doc/release_notes/release_notes_3.0.1.rst +++ b/doc/release_notes/release_notes_3.0.1.rst @@ -36,19 +36,19 @@ What's New in v3.0.1 ******************** Mitigation for Return Stack Buffer Underflow security vulnerability - For platforms that supports RRSBA (Restricted Return Stack Buffer + When running ACRN on Alder Lake platforms that support RRSBA (Restricted Return Stack Buffer Alternate), using retpoline may not be sufficient to guard against branch history injection or intra-mode branch target injection. RRSBA must - be disabled to prevent CPUs from using alternate predictors for RETs. + be disabled for Alder Lake platforms to prevent CPUs from using alternate predictors for RETs. (Addresses security issue tracked by CVE-2022-29901 and CVE-2022-28693.) ACRN shell commands added for real-time performance profiling ACRN shell commands were added to sample vmexit data per virtual CPU to facilitate real-time performance profiling: - * ``vmexit clear``: clears current vmexit buffer - * ``vmexit [vm_id]``: outputs vmexit info per vCPU * ``vmexit enable | disable``: enabled by default - + * ``vmexit clear``: clears current vmexit buffer + * ``vmexit [vm_id]``: outputs vmexit reason code and latency count information per vCPU + for a VM ID (or for all VM IDs if none is specified). See :ref:`release_notes_3.0` for additional release information. diff --git a/doc/user-guides/acrn-shell.rst b/doc/user-guides/acrn-shell.rst index 6c8f808f76..7b26e3dea3 100644 --- a/doc/user-guides/acrn-shell.rst +++ b/doc/user-guides/acrn-shell.rst @@ -53,6 +53,15 @@ The ACRN hypervisor shell supports the following commands: * - wrmsr [-p] - Write ``value`` (in hexadecimal) to the model-specific register (MSR) at index ``msr_index`` (in hexadecimal) for CPU ID ``pcpu_id``. + * - vmexit [enable | disable | clear | ] + - Controls collection and display of vmexit occurrences useful for + real-time performance profiling. + + * **enable** and **disable** determine if vmexit data is collected + (enabled by default in a debug-mode build). + * **clear** resets counters back to zero. + * **** displays vmexit data per vmexit reason for all vCPUs for that VM. + * If no argument is given, data for all VMs is displayed. Command Examples **************** @@ -249,3 +258,39 @@ In the following example, we can set the IA32_APIC_BASE value of pCPU 1 through the command:: wrmsr -p1 1b 0xfee00c00 + +vmexit +====== + +VMexit data collection is enabled by default in a debug-mode ACRN build. There +should be little impact on real-time system performance since a tuned RTVM +should have very few vmexits. + +You can disable vmexit data collection using the ACRN shell's ``vmexit disable`` +command. + +The ``vmexit`` command with no arguments (or with a argument) shows a +table of counters for each vmexit reason, for all VM's (or just the +specified VM's) vCPUs, showing the latency time counts. For example: + +.. figure:: images/vmexit-example.png + :align: center + +VMexit reason codes are defined in the (ACRN) kernel source code +:acrn_file:`hypervisor/include/arch/x86/asm/vmx.h` (search for "VM exit +reasons"). Here are a few examples: + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - VMexit reason code + - Explanation + * - 0x01 + - An external interrupt (IRQ) arrived + * - 0x0a + - The guest VM software attempted to execute the CPUID instruction. + * - 0x0c + - The guest VM attempted to execute HLT instruction. + * - 0x12 + - The execution of VMCALL by the guest VM caused an ordinary VM exit. diff --git a/doc/user-guides/images/vmexit-example.png b/doc/user-guides/images/vmexit-example.png new file mode 100644 index 0000000000..719bed1c20 Binary files /dev/null and b/doc/user-guides/images/vmexit-example.png differ