docs/specs/acpi_cpu_hotplug.rst

   1 QEMU<->ACPI BIOS CPU hotplug interface
   2 ======================================
   3
   4 QEMU supports CPU hotplug via ACPI. This document
   5 describes the interface between QEMU and the ACPI BIOS.
   6
   7 ACPI BIOS GPE.2 handler is dedicated for notifying OS about CPU hot-add
   8 and hot-remove events.
   9
  10
  11 Legacy ACPI CPU hotplug interface registers
  12 -------------------------------------------
  13
  14 CPU 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
  22 QEMU sets corresponding CPU bit on hot-add event and issues SCI
  23 with GPE.2 event set. CPU present map is read by ACPI BIOS GPE.2 handler
  24 to notify OS about CPU hot-add events. CPU hot-remove isn't supported.
  25
  26
  27 Modern ACPI CPU hotplug interface registers
  28 -------------------------------------------
  29
  30 Register block base address:
  31
  32 - ICH9-LPC IO port 0x0cd8
  33 - PIIX-PM  IO port 0xaf00
  34
  35 Register block size:
  36
  37 - ACPI_CPU_HOTPLUG_REG_LEN = 12
  38
  39 All accesses to registers described below, imply little-endian byte order.
  40
  41 Reserved registers behavior:
  42
  43 - write accesses are ignored
  44 - read accesses return all bits set to 0.
  45
  46 The 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
  51 On QEMU start, 'CPU selector' is initialized to a valid value, on reset it
  52 keeps the current value.
  53
  54 Read access behavior
  55 ^^^^^^^^^^^^^^^^^^^^
  56
  57 offset [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
  69 offset [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
  91 offset [0x5-0x7]
  92   reserved
  93
  94 offset [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
 107 Write access behavior
 108 ^^^^^^^^^^^^^^^^^^^^^
 109
 110 offset [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
 117 offset [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
 145 offset[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
 169 offset [0x6-0x7]
 170   reserved
 171
 172 offset [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
 186 Typical usecases
 187 ----------------
 188
 189 (x86) Detecting and enabling modern CPU hotplug interface
 190 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 191
 192 QEMU starts with legacy CPU hotplug interface enabled. Detecting and
 193 switching 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
 198 Use 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
 207 Get 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
 218 Enumerate 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".