docs/specs/acpi_cpu_hotplug.txt

   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 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.
  23
  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
  30 Register block size:
  31     ACPI_CPU_HOTPLUG_REG_LEN = 12
  32
  33 All accesses to registers described below, imply little-endian byte order.
  34
  35 Reserved resisters behavior:
  36    - write accesses are ignored
  37    - read accesses return all bits set to 0.
  38
  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.
  44
  45 read access:
  46     offset:
  47     [0x0-0x3] Command data 2: (DWORD access)
  48               if value last stored in 'Command field':
  49                 0: reads as 0x0
  50                 3: upper 32 bits of architecture specific CPU ID value
  51                 other values: reserved
  52     [0x4] CPU device status fields: (1 byte access)
  53         bits:
  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. Firmware must
  60               ignore this bit.
  61            3: reserved and should be ignored by OSPM
  62            4: if set to 1, OSPM requests firmware to perform device eject.
  63            5-7: reserved and should be ignored by OSPM
  64     [0x5-0x7] reserved
  65     [0x8] Command data: (DWORD access)
  66           contains 0 unless value last stored in 'Command field' is one of:
  67               0: contains 'CPU selector' value of a CPU with pending event[s]
  68               3: lower 32 bits of architecture specific CPU ID value
  69                  (in x86 case: APIC ID)
  70
  71 write access:
  72     offset:
  73     [0x0-0x3] CPU selector: (DWORD access)
  74               selects active CPU device. All following accesses to other
  75               registers will read/store data from/to selected CPU.
  76               Valid values: [0 .. max_cpus)
  77     [0x4] CPU device control fields: (1 byte access)
  78         bits:
  79             0: reserved, OSPM must clear it before writing to register.
  80             1: if set to 1 clears device insert event, set by OSPM
  81                after it has emitted device check event for the
  82                selected CPU device
  83             2: if set to 1 clears device remove event, set by OSPM
  84                after it has emitted device eject request for the
  85                selected CPU device.
  86             3: if set to 1 initiates device eject, set by OSPM when it
  87                triggers CPU device removal and calls _EJ0 method or by firmware
  88                when bit #4 is set. In case bit #4 were set, it's cleared as
  89                part of device eject.
  90             4: if set to 1, OSPM hands over device eject to firmware.
  91                Firmware shall issue device eject request as described above
  92                (bit #3) and OSPM should not touch device eject bit (#3) in case
  93                it's asked firmware to perform CPU device eject.
  94             5-7: reserved, OSPM must clear them before writing to register
  95     [0x5] Command field: (1 byte access)
  96           value:
  97             0: selects a CPU device with inserting/removing events and
  98                following reads from 'Command data' register return
  99                selected CPU ('CPU selector' value).
 100                If no CPU with events found, the current 'CPU selector' doesn't
 101                change and corresponding insert/remove event flags are not modified.
 102             1: following writes to 'Command data' register set OST event
 103                register in QEMU
 104             2: following writes to 'Command data' register set OST status
 105                register in QEMU
 106             3: following reads from 'Command data' and 'Command data 2' return
 107                architecture specific CPU ID value for currently selected CPU.
 108             other values: reserved
 109     [0x6-0x7] reserved
 110     [0x8] Command data: (DWORD access)
 111           if last stored 'Command field' value:
 112               1: stores value into OST event register
 113               2: stores value into OST status register, triggers
 114                  ACPI_DEVICE_OST QMP event from QEMU to external applications
 115                  with current values of OST event and status registers.
 116               other values: reserved
 117
 118 Typical usecases:
 119     - (x86) Detecting and enabling modern CPU hotplug interface.
 120       QEMU starts with legacy CPU hotplug interface enabled. Detecting and
 121       switching to modern interface is based on the 2 legacy CPU hotplug features:
 122         1. Writes into CPU bitmap are ignored.
 123         2. CPU bitmap always has bit#0 set, corresponding to boot CPU.
 124
 125       Use following steps to detect and enable modern CPU hotplug interface:
 126         1. Store 0x0 to the 'CPU selector' register,
 127            attempting to switch to modern mode
 128         2. Store 0x0 to the 'CPU selector' register,
 129            to ensure valid selector value
 130         3. Store 0x0 to the 'Command field' register,
 131         4. Read the 'Command data 2' register.
 132            If read value is 0x0, the modern interface is enabled.
 133            Otherwise legacy or no CPU hotplug interface available
 134
 135     - Get a cpu with pending event
 136       1. Store 0x0 to the 'CPU selector' register.
 137       2. Store 0x0 to the 'Command field' register.
 138       3. Read the 'CPU device status fields' register.
 139       4. If both bit#1 and bit#2 are clear in the value read, there is no CPU
 140          with a pending event and selected CPU remains unchanged.
 141       5. Otherwise, read the 'Command data' register. The value read is the
 142          selector of the CPU with the pending event (which is already
 143          selected).
 144
 145     - Enumerate CPUs present/non present CPUs
 146       01. Set the present CPU count to 0.
 147       02. Set the iterator to 0.
 148       03. Store 0x0 to the 'CPU selector' register, to ensure that it's in
 149           a valid state and that access to other registers won't be ignored.
 150       04. Store 0x0 to the 'Command field' register to make 'Command data'
 151           register return 'CPU selector' value of selected CPU
 152       05. Read the 'CPU device status fields' register.
 153       06. If bit#0 is set, increment the present CPU count.
 154       07. Increment the iterator.
 155       08. Store the iterator to the 'CPU selector' register.
 156       09. Read the 'Command data' register.
 157       10. If the value read is not zero, goto 05.
 158       11. Otherwise store 0x0 to the 'CPU selector' register, to put it
 159           into a valid state and exit.
 160           The iterator at this point equals "max_cpus".