doc: update documents for 3.0.1 release

Clarify release notes and add vmexit information for acrn shell.

Signed-off-by: David B. Kinder <[email protected]>

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.

doc/user-guides/acrn-shell.rst

@@ -53,6 +53,15 @@ The ACRN hypervisor shell supports the following commands:
    * - 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``.
+   * - vmexit [enable | disable | clear | <vm_id>]
+     - 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.
+       * **<vm_id>** 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 <vm_id> 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.