1QEMU<->ACPI BIOS CPU hotplug interface
2======================================
3
4QEMU supports CPU hotplug via ACPI. This document
5describes the interface between QEMU and the ACPI BIOS.
6
7ACPI BIOS GPE.2 handler is dedicated for notifying OS about CPU hot-add
8and hot-remove events.
9
10
11Legacy ACPI CPU hotplug interface registers
12-------------------------------------------
13
14CPU present bitmap for:
15
16- ICH9-LPC (IO port 0x0cd8-0xcf7, 1-byte access)
17- PIIX-PM  (IO port 0xaf00-0xaf1f, 1-byte access)
18- One bit per CPU. Bit position reflects corresponding CPU APIC ID. Read-only.
19- The first DWORD in bitmap is used in write mode to switch from legacy
20  to modern CPU hotplug interface, write 0 into it to do switch.
21
22QEMU sets corresponding CPU bit on hot-add event and issues SCI
23with GPE.2 event set. CPU present map is read by ACPI BIOS GPE.2 handler
24to notify OS about CPU hot-add events. CPU hot-remove isn't supported.
25
26
27Modern ACPI CPU hotplug interface registers
28-------------------------------------------
29
30Register block base address:
31
32- ICH9-LPC IO port 0x0cd8
33- PIIX-PM  IO port 0xaf00
34
35Register block size:
36
37- ACPI_CPU_HOTPLUG_REG_LEN = 12
38
39All accesses to registers described below, imply little-endian byte order.
40
41Reserved registers behavior:
42
43- write accesses are ignored
44- read accesses return all bits set to 0.
45
46The last stored value in 'CPU selector' must refer to a possible CPU, otherwise
47
48- reads from any register return 0
49- writes to any other register are ignored until valid value is stored into it
50
51On QEMU start, 'CPU selector' is initialized to a valid value, on reset it
52keeps the current value.
53
54Read access behavior
55^^^^^^^^^^^^^^^^^^^^
56
57offset [0x0-0x3]
58  Command data 2: (DWORD access)
59
60  If value last stored in 'Command field' is:
61
62  0:
63    reads as 0x0
64  3:
65    upper 32 bits of architecture specific CPU ID value
66  other values:
67    reserved
68
69offset [0x4]
70  CPU device status fields: (1 byte access)
71
72  bits:
73
74  0:
75    Device is enabled and may be used by guest
76  1:
77    Device insert event, used to distinguish device for which
78    no device check event to OSPM was issued.
79    It's valid only when bit 0 is set.
80  2:
81    Device remove event, used to distinguish device for which
82    no device eject request to OSPM was issued. Firmware must
83    ignore this bit.
84  3:
85    reserved and should be ignored by OSPM
86  4:
87    if set to 1, OSPM requests firmware to perform device eject.
88  5-7:
89    reserved and should be ignored by OSPM
90
91offset [0x5-0x7]
92  reserved
93
94offset [0x8]
95  Command data: (DWORD access)
96
97  If value last stored in 'Command field' is one of:
98
99  0:
100    contains 'CPU selector' value of a CPU with pending event[s]
101  3:
102    lower 32 bits of architecture specific CPU ID value
103    (in x86 case: APIC ID)
104  otherwise:
105    contains 0
106
107Write access behavior
108^^^^^^^^^^^^^^^^^^^^^
109
110offset [0x0-0x3]
111  CPU selector: (DWORD access)
112
113  Selects active CPU device. All following accesses to other
114  registers will read/store data from/to selected CPU.
115  Valid values: [0 .. max_cpus)
116
117offset [0x4]
118  CPU device control fields: (1 byte access)
119
120  bits:
121
122  0:
123    reserved, OSPM must clear it before writing to register.
124  1:
125    if set to 1 clears device insert event, set by OSPM
126    after it has emitted device check event for the
127    selected CPU device
128  2:
129    if set to 1 clears device remove event, set by OSPM
130    after it has emitted device eject request for the
131    selected CPU device.
132  3:
133    if set to 1 initiates device eject, set by OSPM when it
134    triggers CPU device removal and calls _EJ0 method or by firmware
135    when bit #4 is set. In case bit #4 were set, it's cleared as
136    part of device eject.
137  4:
138    if set to 1, OSPM hands over device eject to firmware.
139    Firmware shall issue device eject request as described above
140    (bit #3) and OSPM should not touch device eject bit (#3) in case
141    it's asked firmware to perform CPU device eject.
142  5-7:
143    reserved, OSPM must clear them before writing to register
144
145offset[0x5]
146  Command field: (1 byte access)
147
148  value:
149
150  0:
151    selects a CPU device with inserting/removing events and
152    following reads from 'Command data' register return
153    selected CPU ('CPU selector' value).
154    If no CPU with events found, the current 'CPU selector' doesn't
155    change and corresponding insert/remove event flags are not modified.
156
157  1:
158    following writes to 'Command data' register set OST event
159    register in QEMU
160  2:
161    following writes to 'Command data' register set OST status
162    register in QEMU
163  3:
164    following reads from 'Command data' and 'Command data 2' return
165    architecture specific CPU ID value for currently selected CPU.
166  other values:
167    reserved
168
169offset [0x6-0x7]
170  reserved
171
172offset [0x8]
173  Command data: (DWORD access)
174
175  If last stored 'Command field' value is:
176
177  1:
178    stores value into OST event register
179  2:
180    stores value into OST status register, triggers
181    ACPI_DEVICE_OST QMP event from QEMU to external applications
182    with current values of OST event and status registers.
183  other values:
184    reserved
185
186Typical usecases
187----------------
188
189(x86) Detecting and enabling modern CPU hotplug interface
190^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
191
192QEMU starts with legacy CPU hotplug interface enabled. Detecting and
193switching to modern interface is based on the 2 legacy CPU hotplug features:
194
195#. Writes into CPU bitmap are ignored.
196#. CPU bitmap always has bit #0 set, corresponding to boot CPU.
197
198Use following steps to detect and enable modern CPU hotplug interface:
199
200#. Store 0x0 to the 'CPU selector' register, attempting to switch to modern mode
201#. Store 0x0 to the 'CPU selector' register, to ensure valid selector value
202#. Store 0x0 to the 'Command field' register
203#. Read the 'Command data 2' register.
204   If read value is 0x0, the modern interface is enabled.
205   Otherwise legacy or no CPU hotplug interface available
206
207Get a cpu with pending event
208^^^^^^^^^^^^^^^^^^^^^^^^^^^^
209
210#. Store 0x0 to the 'CPU selector' register.
211#. Store 0x0 to the 'Command field' register.
212#. Read the 'CPU device status fields' register.
213#. If both bit #1 and bit #2 are clear in the value read, there is no CPU
214   with a pending event and selected CPU remains unchanged.
215#. Otherwise, read the 'Command data' register. The value read is the
216   selector of the CPU with the pending event (which is already selected).
217
218Enumerate CPUs present/non present CPUs
219^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
220
221#. Set the present CPU count to 0.
222#. Set the iterator to 0.
223#. Store 0x0 to the 'CPU selector' register, to ensure that it's in
224   a valid state and that access to other registers won't be ignored.
225#. Store 0x0 to the 'Command field' register to make 'Command data'
226   register return 'CPU selector' value of selected CPU
227#. Read the 'CPU device status fields' register.
228#. If bit #0 is set, increment the present CPU count.
229#. Increment the iterator.
230#. Store the iterator to the 'CPU selector' register.
231#. Read the 'Command data' register.
232#. If the value read is not zero, goto 05.
233#. Otherwise store 0x0 to the 'CPU selector' register, to put it
234   into a valid state and exit.
235   The iterator at this point equals "max_cpus".
236