1QEMU<->ACPI BIOS CPU hotplug interface 2-------------------------------------- 3 4QEMU supports CPU hotplug via ACPI. This document 5describes the interface between QEMU and the ACPI BIOS. 6 7ACPI BIOS GPE.2 handler is dedicated for notifying OS about CPU hot-add 8and hot-remove events. 9 10============================================ 11Legacy ACPI CPU hotplug interface registers: 12-------------------------------------------- 13CPU 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--------------------------------------------------------------- 20QEMU sets corresponding CPU bit on hot-add event and issues SCI 21with GPE.2 event set. CPU present map is read by ACPI BIOS GPE.2 handler 22to notify OS about CPU hot-add events. CPU hot-remove isn't supported. 23 24===================================== 25Modern ACPI CPU hotplug interface registers: 26------------------------------------- 27Register block base address: 28 ICH9-LPC IO port 0x0cd8 29 PIIX-PM IO port 0xaf00 30Register block size: 31 ACPI_CPU_HOTPLUG_REG_LEN = 12 32 33All accesses to registers described below, imply little-endian byte order. 34 35Reserved resisters behavior: 36 - write accesses are ignored 37 - read accesses return all bits set to 0. 38 39The 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 42On QEMU start, 'CPU selector' is initialized to a valid value, on reset it 43keeps the current value. 44 45read 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 71write 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 118Typical 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". 161