1.. _acrnshell:
2
3ACRN Shell Commands
4###################
5
6The ACRN shell is a text-based terminal for the hypervisor, accessible via the target system's serial port.
7It is only available when the hypervisor build type is debug, the serial console port is configured, and a
8terminal emulator on your development computer is connected, typically via a serial-to-USB cable.
9
10The ACRN shell provides useful debugging commands for displaying internal system states, environment settings,
11and hypervisor statistics as well as reading and writing CPU model-specific registers (MSR).
12
13A short command history is maintained that lets you use the :kbd:`UP` and :kbd:`DOWN` keys to browse the command
14history and :kbd:`HOME`, :kbd:`END`, :kbd:`LEFT`, and :kbd:`RIGHT` keys to select an edit point within the command.
15
16Here's the list of commands supported by the ACRN shell, followed by example uses of these commands:
17
18.. list-table::
19   :header-rows: 1
20   :widths: 40 60
21
22   * - Command (and parameters)
23     - Description
24   * - help
25     - Display information about supported hypervisor shell commands.
26   * - version
27     - Display the hypervisor version information.
28   * - vm_list
29     - List all VMs, displaying the VM UUID, ID, name, and state ("Started"=running).
30   * - vcpu_list
31     - List all vCPUs in all VMs.
32   * - vcpu_dumpreg <vm_id> <vcpu_id>
33     - Dump registers for a specific vCPU.
34   * - dump_host_mem <hva> <length>
35     - Dump the host memory region as specified by the start of the region ``hva`` (in hexadecimal)
36       and its length ``length`` (in bytes, decimal number).
37   * - dump_guest_mem <vm_id> <gva> <length>
38     - Dump a User VM (guest) memory region based on the VM ID (``vm_id``, in decimal),
39       the start of the memory region ``gva`` (in hexadecimal), and its length ``length`` (in bytes, decimal number).
40   * - vm_console <vm_id>
41     - Switch to the VM's console. Use :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`Space` to return to the ACRN
42       shell console.
43   * - int
44     - List interrupt information per CPU.
45   * - pt
46     - Show passthrough device information.
47   * - vioapic <vm_id>
48     - Show virtual IOAPIC (vIOAPIC) information for a specific VM.
49   * - dump_ioapic
50     - Show native IOAPIC information.
51   * - loglevel <console_loglevel> <mem_loglevel> <npk_loglevel>
52     - * If no parameters are given, the command will return the level of
53         logging for the console, memory, and npk.
54       * Give (up to) three parameters between ``0`` (none) and ``6`` (verbose)
55         to set the loglevel for the console, memory, and npk (in
56         that order). If fewer than three parameters are given, the
57         loglevels for the remaining areas will not be changed.
58   * - cpuid <leaf> [subleaf]
59     - Display the CPUID leaf [subleaf], in hexadecimal.
60   * - rdmsr [-p<pcpu_id>] <msr_index>
61     - Read the model-specific register (MSR) at index ``msr_index`` (in
62       hexadecimal) for CPU ID ``pcpu_id``.
63   * - wrmsr [-p<pcpu_id>] <msr_index> <value>
64     - Write ``value`` (in hexadecimal) to the model-specific register (MSR) at
65       index ``msr_index`` (in hexadecimal) for CPU ID ``pcpu_id``.
66
67Command Examples
68****************
69
70The following sections provide further details and examples for some of these commands.
71
72vm_list
73=======
74
75The ``vm_list`` command provides the name of each virtual machine and its corresponding ID and
76state.
77
78.. figure:: images/shell_image8.png
79   :align: center
80
81   vm_list information
82
83vcpu_list
84=========
85
86The ``vcpu_list`` command provides information about virtual CPUs (vCPU), including
87the VM ID, pCPU ID, vCPU ID, vCPU role (primary or secondary), and vCPU
88state (init, paused, running, zombie, or unknown).
89
90.. figure:: images/shell_image7.png
91   :align: center
92
93   vcpu_list information
94
95vcpu_dumpreg
96============
97
98The ``vcpu_dumpreg <vm_id> <vcpu_id>`` command provides vCPU-related
99information such as register values.
100
101In the following example, we dump the vCPU0 RIP register value and get into
102the Service VM to search for the running function, using these
103commands::
104
105   cat /proc/kallsyms | grep RIP_value
106
107As you can see, vCPU0 is running in
108function ``acpi_idle_do_entry``.
109
110.. figure:: images/shell_image10.png
111   :align: center
112
113   vcpu_dumpreg information
114
115.. figure:: images/shell_image9.png
116   :align: center
117
118   system map information
119
120dump_host_mem
121=============
122
123The ``dump_host_mem <hva> <length>`` command provides the specified memory
124target data such as the physical CPU (pCPU) number.
125
126In this example, we know the pCPU active bitmap and physical CPU number
127physical memory address through
128``build/hypervisor/acrn.map``. (Note that the path for
129``acrn.map`` depends on how we build the hypervisor.)
130
131Then we can dump the memory address of the pCPU active bitmap and CPU
132number. The pCPU active bitmap is 0x000000000000000f and
133pCPU number is 0x0000000000000004.
134
135.. figure:: images/shell_image12.png
136   :align: center
137
138   dumpmem information
139
140.. figure:: images/shell_image11.png
141   :align: center
142
143   acrn map information
144
145dump_guest_mem
146==============
147
148The ``dump_guest_mem <vm_id> <gva> <length>`` command dumps guest memory
149information according to the given VM ID and guest virtual address (``gva``).
150
151In this example, we know the starting address of the kernel text segment
152in the guest console or through the ``system.map``. (Note that the path for
153``system.map`` depends on how we build the kernel.)
154
155.. figure:: images/shell_image19.png
156   :align: center
157
158   guest virtual address
159
160.. figure:: images/shell_image20.png
161   :align: center
162
163   guest memory information
164
165vm_console
166===========
167
168The ``vm_console <vm_id>`` command switches the ACRN's console to become the
169VM's console.
170Send a BREAK character to enter escaping mode and a character e to return to
171the ACRN shell console. For details on how the hypervisor console works,
172refer to :ref:`hv-console`.
173
174vioapic
175=======
176
177The ``vioapic <vm_id>`` command shows the virtual IOAPIC information for a specific
178VM. In the following figure, we show the virtual IOAPIC information for
179VM1:
180
181.. figure:: images/shell_image6.png
182   :align: center
183
184   vioapic information
185
186dump_ioapic
187===========
188
189The ``dump_ioapic`` command provides IOAPIC information and we can get IRQ number,
190IRQ vector number, etc.
191
192.. figure:: images/shell_image14.png
193   :align: center
194
195   dump_ioapic information
196
197pt
198==
199
200The ``pt`` command provides passthrough detailed information, such as the
201virtual machine number, interrupt type, interrupt request, interrupt vector,
202and trigger mode.
203
204.. figure:: images/shell_image13.png
205   :align: center
206
207   pt information
208
209int
210===
211
212The ``int`` command provides interrupt information on all CPUs and their
213corresponding interrupt vector.
214
215.. figure:: images/shell_image17.png
216   :align: center
217
218   int information
219
220cpuid
221=====
222
223The ``cpuid <leaf> [subleaf]`` command provides the CPUID leaf [subleaf] in
224hexadecimal.
225
226.. figure:: images/shell_image15.png
227   :align: center
228
229   cpuid information
230
231rdmsr
232=====
233
234We can read a model-specific register (MSR) to get register
235values through ``rdmsr [-p<pcpu_id>] <msr_index>``.
236
237In the following example, we can get the IA32_APIC_BASE value of pCPU 0 through
238the command::
239
240   rdmsr -p0 1b
241
242and see that 1B (Hexadecimal) is the IA32_APIC_BASE MSR address.
243
244.. figure:: images/shell_image16.png
245   :align: center
246
247   IA32_APIC_BASE register information
248
249.. figure:: images/shell_image18.png
250   :align: center
251
252   rdmsr information
253
254wrmsr
255=====
256
257We can write to a model-specific register (MSR) to set register
258values through ``wrmsr [-p<pcpu_id>] <msr_index> <value>``.
259
260In the following example, we can set the IA32_APIC_BASE value of pCPU 1 through
261the command::
262
263   wrmsr -p1 1b 0xfee00c00
264