1 QEMU<->ACPI BIOS CPU hotplug interface
2 --------------------------------------
4 QEMU supports CPU hotplug via ACPI. This document
5 describes the interface between QEMU and the ACPI BIOS.
7 ACPI BIOS GPE.2 handler is dedicated for notifying OS about CPU hot-add
10 ============================================
11 Legacy ACPI CPU hotplug interface registers:
12 --------------------------------------------
13 CPU present bitmap for:
14 ICH9-LPC (IO port 0x0cd8-0xcf7, 1-byte access)
15 PIIX-PM (IO port 0xaf00-0xaf1f, 1-byte access)
16 One bit per CPU. Bit position reflects corresponding CPU APIC ID. Read-only.
17 The first DWORD in bitmap is used in write mode to switch from legacy
18 to modern CPU hotplug interface, write 0 into it to do switch.
19 ---------------------------------------------------------------
20 QEMU sets corresponding CPU bit on hot-add event and issues SCI
21 with GPE.2 event set. CPU present map is read by ACPI BIOS GPE.2 handler
22 to notify OS about CPU hot-add events. CPU hot-remove isn't supported.
24 =====================================
25 Modern ACPI CPU hotplug interface registers:
26 -------------------------------------
27 Register block base address:
28 ICH9-LPC IO port 0x0cd8
29 PIIX-PM IO port 0xaf00
31 ACPI_CPU_HOTPLUG_REG_LEN = 12
33 All accesses to registers described below, imply little-endian byte order.
35 Reserved resisters behavior:
36 - write accesses are ignored
37 - read accesses return all bits set to 0.
39 The last stored value in 'CPU selector' must refer to a possible CPU, otherwise
40 - reads from any register return 0
41 - writes to any other register are ignored until valid value is stored into it
42 On QEMU start, 'CPU selector' is initialized to a valid value, on reset it
43 keeps the current value.
47 [0x0-0x3] Command data 2: (DWORD access)
48 if value last stored in 'Command field':
50 3: upper 32 bits of architecture specific CPU ID value
51 other values: reserved
52 [0x4] CPU device status fields: (1 byte access)
54 0: Device is enabled and may be used by guest
55 1: Device insert event, used to distinguish device for which
56 no device check event to OSPM was issued.
57 It's valid only when bit 0 is set.
58 2: Device remove event, used to distinguish device for which
59 no device eject request to OSPM was issued.
60 3-7: reserved and should be ignored by OSPM
62 [0x8] Command data: (DWORD access)
63 contains 0 unless value last stored in 'Command field' is one of:
64 0: contains 'CPU selector' value of a CPU with pending event[s]
65 3: lower 32 bits of architecture specific CPU ID value
66 (in x86 case: APIC ID)
70 [0x0-0x3] CPU selector: (DWORD access)
71 selects active CPU device. All following accesses to other
72 registers will read/store data from/to selected CPU.
73 Valid values: [0 .. max_cpus)
74 [0x4] CPU device control fields: (1 byte access)
76 0: reserved, OSPM must clear it before writing to register.
77 1: if set to 1 clears device insert event, set by OSPM
78 after it has emitted device check event for the
80 2: if set to 1 clears device remove event, set by OSPM
81 after it has emitted device eject request for the
83 3: if set to 1 initiates device eject, set by OSPM when it
84 triggers CPU device removal and calls _EJ0 method
85 4-7: reserved, OSPM must clear them before writing to register
86 [0x5] Command field: (1 byte access)
88 0: selects a CPU device with inserting/removing events and
89 following reads from 'Command data' register return
90 selected CPU ('CPU selector' value).
91 If no CPU with events found, the current 'CPU selector' doesn't
92 change and corresponding insert/remove event flags are not modified.
93 1: following writes to 'Command data' register set OST event
95 2: following writes to 'Command data' register set OST status
97 other values: reserved
99 [0x8] Command data: (DWORD access)
100 if last stored 'Command field' value:
101 1: stores value into OST event register
102 2: stores value into OST status register, triggers
103 ACPI_DEVICE_OST QMP event from QEMU to external applications
104 with current values of OST event and status registers.
105 other values: reserved
108 - (x86) Detecting and enabling modern CPU hotplug interface.
109 QEMU starts with legacy CPU hotplug interface enabled. Detecting and
110 switching to modern interface is based on the 2 legacy CPU hotplug features:
111 1. Writes into CPU bitmap are ignored.
112 2. CPU bitmap always has bit#0 set, corresponding to boot CPU.
114 Use following steps to detect and enable modern CPU hotplug interface:
115 1. Store 0x0 to the 'CPU selector' register,
116 attempting to switch to modern mode
117 2. Store 0x0 to the 'CPU selector' register,
118 to ensure valid selector value
119 3. Store 0x0 to the 'Command field' register,
120 4. Read the 'Command data 2' register.
121 If read value is 0x0, the modern interface is enabled.
122 Otherwise legacy or no CPU hotplug interface available
124 - Get a cpu with pending event
125 1. Store 0x0 to the 'CPU selector' register.
126 2. Store 0x0 to the 'Command field' register.
127 3. Read the 'CPU device status fields' register.
128 4. If both bit#1 and bit#2 are clear in the value read, there is no CPU
129 with a pending event and selected CPU remains unchanged.
130 5. Otherwise, read the 'Command data' register. The value read is the
131 selector of the CPU with the pending event (which is already
134 - Enumerate CPUs present/non present CPUs
135 01. Set the present CPU count to 0.
136 02. Set the iterator to 0.
137 03. Store 0x0 to the 'CPU selector' register, to ensure that it's in
138 a valid state and that access to other registers won't be ignored.
139 04. Store 0x0 to the 'Command field' register to make 'Command data'
140 register return 'CPU selector' value of selected CPU
141 05. Read the 'CPU device status fields' register.
142 06. If bit#0 is set, increment the present CPU count.
143 07. Increment the iterator.
144 08. Store the iterator to the 'CPU selector' register.
145 09. Read the 'Command data' register.
146 10. If the value read is not zero, goto 05.
147 11. Otherwise store 0x0 to the 'CPU selector' register, to put it
148 into a valid state and exit.
149 The iterator at this point equals "max_cpus".