docs/specs/acpi_cpu_hotplug.txt - third_party/qemu - Git at Google

 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 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
                 3: upper 32 bits of architecture specific CPU ID value
                 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]
               3: lower 32 bits of architecture specific CPU ID value
                  (in x86 case: APIC ID)

 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.
               Valid values: [0 .. max_cpus)
     [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
             3: following reads from 'Command data' and 'Command data 2' return
                architecture specific CPU ID value for currently selected CPU.
             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

 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:
         1. Writes into CPU bitmap are ignored.
         2. CPU bitmap always has bit#0 set, corresponding to boot CPU.

       Use following steps to detect and enable modern CPU hotplug interface:
         1. Store 0x0 to the 'CPU selector' register,
            attempting to switch to modern mode
         2. Store 0x0 to the 'CPU selector' register,
            to ensure valid selector value
         3. Store 0x0 to the 'Command field' register,
         4. 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
       1. Store 0x0 to the 'CPU selector' register.
       2. Store 0x0 to the 'Command field' register.
       3. Read the 'CPU device status fields' register.
       4. 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.
       5. 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
       01. Set the present CPU count to 0.
       02. Set the iterator to 0.
       03. 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.
       04. Store 0x0 to the 'Command field' register to make 'Command data'
           register return 'CPU selector' value of selected CPU
       05. Read the 'CPU device status fields' register.
       06. If bit#0 is set, increment the present CPU count.
       07. Increment the iterator.
       08. Store the iterator to the 'CPU selector' register.
       09. Read the 'Command data' register.
       10. If the value read is not zero, goto 05.
       11. 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".
	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 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
	3: upper 32 bits of architecture specific CPU ID value
	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]
	3: lower 32 bits of architecture specific CPU ID value
	(in x86 case: APIC ID)

	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.
	Valid values: [0 .. max_cpus)
	[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
	3: following reads from 'Command data' and 'Command data 2' return
	architecture specific CPU ID value for currently selected CPU.
	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

	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:
	1. Writes into CPU bitmap are ignored.
	2. CPU bitmap always has bit#0 set, corresponding to boot CPU.

	Use following steps to detect and enable modern CPU hotplug interface:
	1. Store 0x0 to the 'CPU selector' register,
	attempting to switch to modern mode
	2. Store 0x0 to the 'CPU selector' register,
	to ensure valid selector value
	3. Store 0x0 to the 'Command field' register,
	4. 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
	1. Store 0x0 to the 'CPU selector' register.
	2. Store 0x0 to the 'Command field' register.
	3. Read the 'CPU device status fields' register.
	4. 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.
	5. 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
	01. Set the present CPU count to 0.
	02. Set the iterator to 0.
	03. 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.
	04. Store 0x0 to the 'Command field' register to make 'Command data'
	register return 'CPU selector' value of selected CPU
	05. Read the 'CPU device status fields' register.
	06. If bit#0 is set, increment the present CPU count.
	07. Increment the iterator.
	08. Store the iterator to the 'CPU selector' register.
	09. Read the 'Command data' register.
	10. If the value read is not zero, goto 05.
	11. 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".