docs/specs/acpi_cpu_hotplug.rst

QEMU<->ACPI BIOS CPU hotplug interface
======================================

QEMU supports CPU hotplug via ACPI. This document
describes the interface between QEMU and the ACPI BIOS.

ACPI BIOS GPE.2 handler is dedicated for notifying OS about CPU hot-add
and hot-remove events.


Legacy ACPI CPU hotplug interface registers
-------------------------------------------

CPU present bitmap for:

- ICH9-LPC (IO port 0x0cd8-0xcf7, 1-byte access)
- PIIX-PM  (IO port 0xaf00-0xaf1f, 1-byte access)
- One bit per CPU. Bit position reflects corresponding CPU APIC ID. Read-only.
- The first DWORD in bitmap is used in write mode to switch from legacy
  to modern CPU hotplug interface, write 0 into it to do switch.

QEMU sets corresponding CPU bit on hot-add event and issues SCI
with GPE.2 event set. CPU present map is read by ACPI BIOS GPE.2 handler
to notify OS about CPU hot-add events. CPU hot-remove isn't supported.


Modern ACPI CPU hotplug interface registers
-------------------------------------------

Register block base address:

- ICH9-LPC IO port 0x0cd8
- PIIX-PM  IO port 0xaf00

Register block size:

- ACPI_CPU_HOTPLUG_REG_LEN = 12

All accesses to registers described below, imply little-endian byte order.

Reserved registers behavior:

- write accesses are ignored
- read accesses return all bits set to 0.

The last stored value in 'CPU selector' must refer to a possible CPU, otherwise

- reads from any register return 0
- writes to any other register are ignored until valid value is stored into it

On QEMU start, 'CPU selector' is initialized to a valid value, on reset it
keeps the current value.

Read access behavior
^^^^^^^^^^^^^^^^^^^^

offset [0x0-0x3]
  Command data 2: (DWORD access)

  If value last stored in 'Command field' is:

  0:
    reads as 0x0
  3:
    upper 32 bits of architecture specific CPU ID value
  other values:
    reserved

offset [0x4]
  CPU device status fields: (1 byte access)

  bits:

  0:
    Device is enabled and may be used by guest
  1:
    Device insert event, used to distinguish device for which
    no device check event to OSPM was issued.
    It's valid only when bit 0 is set.
  2:
    Device remove event, used to distinguish device for which
    no device eject request to OSPM was issued. Firmware must
    ignore this bit.
  3:
    reserved and should be ignored by OSPM
  4:
    if set to 1, OSPM requests firmware to perform device eject.
  5-7:
    reserved and should be ignored by OSPM

offset [0x5-0x7]
  reserved

offset [0x8]
  Command data: (DWORD access)

  If value last stored in 'Command field' is one of:

  0:
    contains 'CPU selector' value of a CPU with pending event[s]
  3:
    lower 32 bits of architecture specific CPU ID value
    (in x86 case: APIC ID)
  otherwise:
    contains 0

Write access behavior
^^^^^^^^^^^^^^^^^^^^^

offset [0x0-0x3]
  CPU selector: (DWORD access)

  Selects active CPU device. All following accesses to other
  registers will read/store data from/to selected CPU.
  Valid values: [0 .. max_cpus)

offset [0x4]
  CPU device control fields: (1 byte access)

  bits:

  0:
    reserved, OSPM must clear it before writing to register.
  1:
    if set to 1 clears device insert event, set by OSPM
    after it has emitted device check event for the
    selected CPU device
  2:
    if set to 1 clears device remove event, set by OSPM
    after it has emitted device eject request for the
    selected CPU device.
  3:
    if set to 1 initiates device eject, set by OSPM when it
    triggers CPU device removal and calls _EJ0 method or by firmware
    when bit #4 is set. In case bit #4 were set, it's cleared as
    part of device eject.
  4:
    if set to 1, OSPM hands over device eject to firmware.
    Firmware shall issue device eject request as described above
    (bit #3) and OSPM should not touch device eject bit (#3) in case
    it's asked firmware to perform CPU device eject.
  5-7:
    reserved, OSPM must clear them before writing to register

offset[0x5]
  Command field: (1 byte access)

  value:

  0:
    selects a CPU device with inserting/removing events and
    following reads from 'Command data' register return
    selected CPU ('CPU selector' value).
    If no CPU with events found, the current 'CPU selector' doesn't
    change and corresponding insert/remove event flags are not modified.

  1:
    following writes to 'Command data' register set OST event
    register in QEMU
  2:
    following writes to 'Command data' register set OST status
    register in QEMU
  3:
    following reads from 'Command data' and 'Command data 2' return
    architecture specific CPU ID value for currently selected CPU.
  other values:
    reserved

offset [0x6-0x7]
  reserved

offset [0x8]
  Command data: (DWORD access)

  If last stored 'Command field' value is:

  1:
    stores value into OST event register
  2:
    stores value into OST status register, triggers
    ACPI_DEVICE_OST QMP event from QEMU to external applications
    with current values of OST event and status registers.
  other values:
    reserved

Typical usecases
----------------

(x86) Detecting and enabling modern CPU hotplug interface
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

QEMU starts with legacy CPU hotplug interface enabled. Detecting and
switching to modern interface is based on the 2 legacy CPU hotplug features:

#. Writes into CPU bitmap are ignored.
#. CPU bitmap always has bit #0 set, corresponding to boot CPU.

Use following steps to detect and enable modern CPU hotplug interface:

#. Store 0x0 to the 'CPU selector' register, attempting to switch to modern mode
#. Store 0x0 to the 'CPU selector' register, to ensure valid selector value
#. Store 0x0 to the 'Command field' register
#. Read the 'Command data 2' register.
   If read value is 0x0, the modern interface is enabled.
   Otherwise legacy or no CPU hotplug interface available

Get a cpu with pending event
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

#. Store 0x0 to the 'CPU selector' register.
#. Store 0x0 to the 'Command field' register.
#. Read the 'CPU device status fields' register.
#. If both bit #1 and bit #2 are clear in the value read, there is no CPU
   with a pending event and selected CPU remains unchanged.
#. Otherwise, read the 'Command data' register. The value read is the
   selector of the CPU with the pending event (which is already selected).

Enumerate CPUs present/non present CPUs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

#. Set the present CPU count to 0.
#. Set the iterator to 0.
#. Store 0x0 to the 'CPU selector' register, to ensure that it's in
   a valid state and that access to other registers won't be ignored.
#. Store 0x0 to the 'Command field' register to make 'Command data'
   register return 'CPU selector' value of selected CPU
#. Read the 'CPU device status fields' register.
#. If bit #0 is set, increment the present CPU count.
#. Increment the iterator.
#. Store the iterator to the 'CPU selector' register.
#. Read the 'Command data' register.
#. If the value read is not zero, goto 05.
#. Otherwise store 0x0 to the 'CPU selector' register, to put it
   into a valid state and exit.
   The iterator at this point equals "max_cpus".