qemu-patch-raspberry4/docs/specs/acpi_cpu_hotplug.txt

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 new 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.

=====================================
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 resisters 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:
    offset:
    [0x0-0x3] Command data 2: (DWORD access)
              if value last stored in 'Command field':
                0: reads as 0x0
                other values: reserved
    [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.
           3-7: reserved and should be ignored by OSPM
    [0x5-0x7] reserved
    [0x8] Command data: (DWORD access)
          contains 0 unless value last stored in 'Command field' is one of:
              0: contains 'CPU selector' value of a CPU with pending event[s]

write access:
    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.
    [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
            4-7: reserved, OSPM must clear them before writing to register
    [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
            other values: reserved
    [0x6-0x7] reserved
    [0x8] Command data: (DWORD access)
          if last stored 'Command field' value:
              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