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