doc: add the ACRN debug tutorial document

Add a new debugging tutorial and update the acrn_shell documentation
with additional details.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>

doc/user-guides/acrn-shell.rst

@@ -23,7 +23,7 @@ The ACRN hypervisor shell supports the following commands:
      - Dump host memory, starting at a given address, and for a given length
        (in bytes)
    * - sos_console
-     - Switch to the SOS's console. Use [Ctrl+Spacebar] to return to the ACRN
+     - Switch to the SOS's console. Use :kbd:`Ctrl+Spacebar` to return to the ACRN
        shell console
    * - int
      - List interrupt information per CPU
@@ -33,9 +33,9 @@ The ACRN hypervisor shell supports the following commands:
      - Show virtual IOAPIC (vIOAPIC) information for a specific VM
    * - dump_ioapic
      - Show native IOAPIC information
-   * - loglevel <console_loglevel> <mem_loglevel> <npk_logevel>
+   * - loglevel <console_loglevel> <mem_loglevel> <npk_loglevel>
      - * If no parameters are given, the command will return the level of
-         logging for respectively 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 less than three parameters are given, the
@@ -50,3 +50,178 @@ 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``
+
+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
+
+sos_console
+===========
+
+The ``sos_console`` command switches the ACRN's console to become the SOS'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