diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/specs/acpi_cpu_hotplug.rst | 235 | ||||
| -rw-r--r-- | docs/specs/acpi_cpu_hotplug.txt | 160 | ||||
| -rw-r--r-- | docs/specs/acpi_mem_hotplug.rst | 128 | ||||
| -rw-r--r-- | docs/specs/acpi_mem_hotplug.txt | 94 | ||||
| -rw-r--r-- | docs/specs/acpi_nvdimm.rst | 228 | ||||
| -rw-r--r-- | docs/specs/acpi_nvdimm.txt | 188 | ||||
| -rw-r--r-- | docs/specs/acpi_pci_hotplug.rst (renamed from docs/specs/acpi_pci_hotplug.txt) | 37 | ||||
| -rw-r--r-- | docs/specs/index.rst | 4 |
8 files changed, 615 insertions, 459 deletions
diff --git a/docs/specs/acpi_cpu_hotplug.rst b/docs/specs/acpi_cpu_hotplug.rst new file mode 100644 index 0000000000..351057c967 --- /dev/null +++ b/docs/specs/acpi_cpu_hotplug.rst @@ -0,0 +1,235 @@ +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". diff --git a/docs/specs/acpi_cpu_hotplug.txt b/docs/specs/acpi_cpu_hotplug.txt deleted file mode 100644 index 9bd59ae0da..0000000000 --- a/docs/specs/acpi_cpu_hotplug.txt +++ /dev/null @@ -1,160 +0,0 @@ -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. 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 - [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 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 - [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". diff --git a/docs/specs/acpi_mem_hotplug.rst b/docs/specs/acpi_mem_hotplug.rst new file mode 100644 index 0000000000..069819bc3e --- /dev/null +++ b/docs/specs/acpi_mem_hotplug.rst @@ -0,0 +1,128 @@ +QEMU<->ACPI BIOS memory hotplug interface +========================================= + +ACPI BIOS GPE.3 handler is dedicated for notifying OS about memory hot-add +and hot-remove events. + +Memory hot-plug interface (IO port 0xa00-0xa17, 1-4 byte access) +---------------------------------------------------------------- + +Read access behavior +^^^^^^^^^^^^^^^^^^^^ + +[0x0-0x3] + Lo part of memory device phys address +[0x4-0x7] + Hi part of memory device phys address +[0x8-0xb] + Lo part of memory device size in bytes +[0xc-0xf] + Hi part of memory device size in bytes +[0x10-0x13] + Memory device proximity domain +[0x14] + Memory device status fields + + 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 1 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 + +[0x15-0x17] + reserved + +Write access behavior +^^^^^^^^^^^^^^^^^^^^^ + + +[0x0-0x3] + Memory device slot selector, selects active memory device. + All following accesses to other registers in 0xa00-0xa17 + region will read/store data from/to selected memory device. +[0x4-0x7] + OST event code reported by OSPM +[0x8-0xb] + OST status code reported by OSPM +[0xc-0x13] + reserved, writes into it are ignored +[0x14] + Memory device control fields + + bits: + + 0: + reserved, OSPM must clear it before writing to register. + Due to BUG in versions prior 2.4 that field isn't cleared + when other fields are written. Keep it reserved and don't + try to reuse it. + 1: + if set to 1 clears device insert event, set by OSPM + after it has emitted device check event for the + selected memory device + 2: + if set to 1 clears device remove event, set by OSPM + after it has emitted device eject request for the + selected memory device + 3: + if set to 1 initiates device eject, set by OSPM when it + triggers memory device removal and calls _EJ0 method + 4-7: + reserved, OSPM must clear them before writing to register + +Selecting memory device slot beyond present range has no effect on platform: + +- write accesses to memory hot-plug registers not documented above are ignored +- read accesses to memory hot-plug registers not documented above return + all bits set to 1. + +Memory hot remove process diagram +--------------------------------- + +:: + + +-------------+ +-----------------------+ +------------------+ + | 1. QEMU | | 2. QEMU | |3. QEMU | + | device_del +---->+ device unplug request +----->+Send SCI to guest,| + | | | cb | |return control to | + | | | | |management | + +-------------+ +-----------------------+ +------------------+ + + +---------------------------------------------------------------------+ + + +---------------------+ +-------------------------+ + | OSPM: | remove event | OSPM: | + | send Eject Request, | | Scan memory devices | + | clear remove event +<-------------+ for event flags | + | | | | + +---------------------+ +-------------------------+ + | + | + +---------v--------+ +-----------------------+ + | Guest OS: | success | OSPM: | + | process Ejection +----------->+ Execute _EJ0 method, | + | request | | set eject bit in flags| + +------------------+ +-----------------------+ + |failure | + v v + +------------------------+ +-----------------------+ + | OSPM: | | QEMU: | + | set OST event & status | | call device unplug cb | + | fields | | | + +------------------------+ +-----------------------+ + | | + v v + +------------------+ +-------------------+ + |QEMU: | |QEMU: | + |Send OST QMP event| |Send device deleted| + | | |QMP event | + +------------------+ | | + +-------------------+ diff --git a/docs/specs/acpi_mem_hotplug.txt b/docs/specs/acpi_mem_hotplug.txt deleted file mode 100644 index 3df3620ce4..0000000000 --- a/docs/specs/acpi_mem_hotplug.txt +++ /dev/null @@ -1,94 +0,0 @@ -QEMU<->ACPI BIOS memory hotplug interface --------------------------------------- - -ACPI BIOS GPE.3 handler is dedicated for notifying OS about memory hot-add -and hot-remove events. - -Memory hot-plug interface (IO port 0xa00-0xa17, 1-4 byte access): ---------------------------------------------------------------- -0xa00: - read access: - [0x0-0x3] Lo part of memory device phys address - [0x4-0x7] Hi part of memory device phys address - [0x8-0xb] Lo part of memory device size in bytes - [0xc-0xf] Hi part of memory device size in bytes - [0x10-0x13] Memory device proximity domain - [0x14] Memory device status fields - 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 1 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 - [0x15-0x17] reserved - - write access: - [0x0-0x3] Memory device slot selector, selects active memory device. - All following accesses to other registers in 0xa00-0xa17 - region will read/store data from/to selected memory device. - [0x4-0x7] OST event code reported by OSPM - [0x8-0xb] OST status code reported by OSPM - [0xc-0x13] reserved, writes into it are ignored - [0x14] Memory device control fields - bits: - 0: reserved, OSPM must clear it before writing to register. - Due to BUG in versions prior 2.4 that field isn't cleared - when other fields are written. Keep it reserved and don't - try to reuse it. - 1: if set to 1 clears device insert event, set by OSPM - after it has emitted device check event for the - selected memory device - 2: if set to 1 clears device remove event, set by OSPM - after it has emitted device eject request for the - selected memory device - 3: if set to 1 initiates device eject, set by OSPM when it - triggers memory device removal and calls _EJ0 method - 4-7: reserved, OSPM must clear them before writing to register - -Selecting memory device slot beyond present range has no effect on platform: - - write accesses to memory hot-plug registers not documented above are - ignored - - read accesses to memory hot-plug registers not documented above return - all bits set to 1. - -Memory hot remove process diagram: ----------------------------------- - +-------------+ +-----------------------+ +------------------+ - | 1. QEMU | | 2. QEMU | |3. QEMU | - | device_del +---->+ device unplug request +----->+Send SCI to guest,| - | | | cb | |return control to | - +-------------+ +-----------------------+ |management | - +------------------+ - - +---------------------------------------------------------------------+ - - +---------------------+ +-------------------------+ - | OSPM: | remove event | OSPM: | - | send Eject Request, | | Scan memory devices | - | clear remove event +<-------------+ for event flags | - | | | | - +---------------------+ +-------------------------+ - | - | - +---------v--------+ +-----------------------+ - | Guest OS: | success | OSPM: | - | process Ejection +----------->+ Execute _EJ0 method, | - | request | | set eject bit in flags| - +------------------+ +-----------------------+ - |failure | - v v - +------------------------+ +-----------------------+ - | OSPM: | | QEMU: | - | set OST event & status | | call device unplug cb | - | fields | | | - +------------------------+ +-----------------------+ - | | - v v - +------------------+ +-------------------+ - |QEMU: | |QEMU: | - |Send OST QMP event| |Send device deleted| - | | |QMP event | - +------------------+ | | - +-------------------+ diff --git a/docs/specs/acpi_nvdimm.rst b/docs/specs/acpi_nvdimm.rst new file mode 100644 index 0000000000..ab0335253d --- /dev/null +++ b/docs/specs/acpi_nvdimm.rst @@ -0,0 +1,228 @@ +QEMU<->ACPI BIOS NVDIMM interface +================================= + +QEMU supports NVDIMM via ACPI. This document describes the basic concepts of +NVDIMM ACPI and the interface between QEMU and the ACPI BIOS. + +NVDIMM ACPI Background +---------------------- + +NVDIMM is introduced in ACPI 6.0 which defines an NVDIMM root device under +_SB scope with a _HID of "ACPI0012". For each NVDIMM present or intended +to be supported by platform, platform firmware also exposes an ACPI +Namespace Device under the root device. + +The NVDIMM child devices under the NVDIMM root device are defined with _ADR +corresponding to the NFIT device handle. The NVDIMM root device and the +NVDIMM devices can have device specific methods (_DSM) to provide additional +functions specific to a particular NVDIMM implementation. + +This is an example from ACPI 6.0, a platform contains one NVDIMM:: + + Scope (\_SB){ + Device (NVDR) // Root device + { + Name (_HID, "ACPI0012") + Method (_STA) {...} + Method (_FIT) {...} + Method (_DSM, ...) {...} + Device (NVD) + { + Name(_ADR, h) //where h is NFIT Device Handle for this NVDIMM + Method (_DSM, ...) {...} + } + } + } + +Methods supported on both NVDIMM root device and NVDIMM device +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +_DSM (Device Specific Method) + It is a control method that enables devices to provide device specific + control functions that are consumed by the device driver. + The NVDIMM DSM specification can be found at + http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf + + Arguments: + + Arg0 + A Buffer containing a UUID (16 Bytes) + Arg1 + An Integer containing the Revision ID (4 Bytes) + Arg2 + An Integer containing the Function Index (4 Bytes) + Arg3 + A package containing parameters for the function specified by the + UUID, Revision ID, and Function Index + + Return Value: + + If Function Index = 0, a Buffer containing a function index bitfield. + Otherwise, the return value and type depends on the UUID, revision ID + and function index which are described in the DSM specification. + +Methods on NVDIMM ROOT Device +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +_FIT(Firmware Interface Table) + It evaluates to a buffer returning data in the format of a series of NFIT + Type Structure. + + Arguments: None + + Return Value: + A Buffer containing a list of NFIT Type structure entries. + + The detailed definition of the structure can be found at ACPI 6.0: 5.2.25 + NVDIMM Firmware Interface Table (NFIT). + +QEMU NVDIMM Implementation +-------------------------- + +QEMU uses 4 bytes IO Port starting from 0x0a18 and a RAM-based memory page +for NVDIMM ACPI. + +Memory: + QEMU uses BIOS Linker/loader feature to ask BIOS to allocate a memory + page and dynamically patch its address into an int32 object named "MEMA" + in ACPI. + + This page is RAM-based and it is used to transfer data between _DSM + method and QEMU. If ACPI has control, this pages is owned by ACPI which + writes _DSM input data to it, otherwise, it is owned by QEMU which + emulates _DSM access and writes the output data to it. + + ACPI writes _DSM Input Data (based on the offset in the page): + + [0x0 - 0x3] + 4 bytes, NVDIMM Device Handle. + + The handle is completely QEMU internal thing, the values in + range [1, 0xFFFF] indicate nvdimm device. Other values are + reserved for other purposes. + + Reserved handles: + + - 0 is reserved for nvdimm root device named NVDR. + - 0x10000 is reserved for QEMU internal DSM function called on + the root device. + + [0x4 - 0x7] + 4 bytes, Revision ID, that is the Arg1 of _DSM method. + + [0x8 - 0xB] + 4 bytes. Function Index, that is the Arg2 of _DSM method. + + [0xC - 0xFFF] + 4084 bytes, the Arg3 of _DSM method. + + QEMU writes Output Data (based on the offset in the page): + + [0x0 - 0x3] + 4 bytes, the length of result + + [0x4 - 0xFFF] + 4092 bytes, the DSM result filled by QEMU + +IO Port 0x0a18 - 0xa1b: + ACPI writes the address of the memory page allocated by BIOS to this + port then QEMU gets the control and fills the result in the memory page. + + Write Access: + + [0x0a18 - 0xa1b] + 4 bytes, the address of the memory page allocated by BIOS. + +_DSM process diagram +-------------------- + +"MEMA" indicates the address of memory page allocated by BIOS. + +:: + + +----------------------+ +-----------------------+ + | 1. OSPM | | 2. OSPM | + | save _DSM input data | | write "MEMA" to | Exit to QEMU + | to the page +----->| IO port 0x0a18 +------------+ + | indicated by "MEMA" | | | | + +----------------------+ +-----------------------+ | + | + v + +--------------------+ +-----------+ +------------------+--------+ + | 5 QEMU | | 4 QEMU | | 3. QEMU | + | write _DSM result | | emulate | | get _DSM input data from | + | to the page +<------+ _DSM +<-----+ the page indicated by the | + | | | | | value from the IO port | + +--------+-----------+ +-----------+ +---------------------------+ + | + | Enter Guest + | + v + +--------------------------+ +--------------+ + | 6 OSPM | | 7 OSPM | + | result size is returned | | _DSM return | + | by reading DSM +----->+ | + | result from the page | | | + +--------------------------+ +--------------+ + +NVDIMM hotplug +-------------- + +ACPI BIOS GPE.4 handler is dedicated for notifying OS about nvdimm device +hot-add event. + +QEMU internal use only _DSM functions +------------------------------------- + +Read FIT +^^^^^^^^ + +_FIT method uses _DSM method to fetch NFIT structures blob from QEMU +in 1 page sized increments which are then concatenated and returned +as _FIT method result. + +Input parameters: + +Arg0 + UUID {set to 648B9CF2-CDA1-4312-8AD9-49C4AF32BD62} +Arg1 + Revision ID (set to 1) +Arg2 + Function Index, 0x1 +Arg3 + A package containing a buffer whose layout is as follows: + + +----------+--------+--------+-------------------------------------------+ + | Field | Length | Offset | Description | + +----------+--------+--------+-------------------------------------------+ + | offset | 4 | 0 | offset in QEMU's NFIT structures blob to | + | | | | read from | + +----------+--------+--------+-------------------------------------------+ + +Output layout in the dsm memory page: + + +----------+--------+--------+-------------------------------------------+ + | Field | Length | Offset | Description | + +----------+--------+--------+-------------------------------------------+ + | length | 4 | 0 | length of entire returned data | + | | | | (including this header) | + +----------+--------+--------+-------------------------------------------+ + | | | | return status codes | + | | | | | + | | | | - 0x0 - success | + | | | | - 0x100 - error caused by NFIT update | + | status | 4 | 4 | while read by _FIT wasn't completed | + | | | | - other codes follow Chapter 3 in | + | | | | DSM Spec Rev1 | + +----------+--------+--------+-------------------------------------------+ + | fit data | Varies | 8 | contains FIT data. This field is present | + | | | | if status field is 0. | + +----------+--------+--------+-------------------------------------------+ + +The FIT offset is maintained by the OSPM itself, current offset plus +the size of the fit data returned by the function is the next offset +OSPM should read. When all FIT data has been read out, zero fit data +size is returned. + +If it returns status code 0x100, OSPM should restart to read FIT (read +from offset 0 again). diff --git a/docs/specs/acpi_nvdimm.txt b/docs/specs/acpi_nvdimm.txt deleted file mode 100644 index 3ec42ecbce..0000000000 --- a/docs/specs/acpi_nvdimm.txt +++ /dev/null @@ -1,188 +0,0 @@ -QEMU<->ACPI BIOS NVDIMM interface ---------------------------------- - -QEMU supports NVDIMM via ACPI. This document describes the basic concepts of -NVDIMM ACPI and the interface between QEMU and the ACPI BIOS. - -NVDIMM ACPI Background ----------------------- -NVDIMM is introduced in ACPI 6.0 which defines an NVDIMM root device under -_SB scope with a _HID of “ACPI0012”. For each NVDIMM present or intended -to be supported by platform, platform firmware also exposes an ACPI -Namespace Device under the root device. - -The NVDIMM child devices under the NVDIMM root device are defined with _ADR -corresponding to the NFIT device handle. The NVDIMM root device and the -NVDIMM devices can have device specific methods (_DSM) to provide additional -functions specific to a particular NVDIMM implementation. - -This is an example from ACPI 6.0, a platform contains one NVDIMM: - -Scope (\_SB){ - Device (NVDR) // Root device - { - Name (_HID, “ACPI0012”) - Method (_STA) {...} - Method (_FIT) {...} - Method (_DSM, ...) {...} - Device (NVD) - { - Name(_ADR, h) //where h is NFIT Device Handle for this NVDIMM - Method (_DSM, ...) {...} - } - } -} - -Method supported on both NVDIMM root device and NVDIMM device -_DSM (Device Specific Method) - It is a control method that enables devices to provide device specific - control functions that are consumed by the device driver. - The NVDIMM DSM specification can be found at: - http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf - - Arguments: - Arg0 – A Buffer containing a UUID (16 Bytes) - Arg1 – An Integer containing the Revision ID (4 Bytes) - Arg2 – An Integer containing the Function Index (4 Bytes) - Arg3 – A package containing parameters for the function specified by the - UUID, Revision ID, and Function Index - - Return Value: - If Function Index = 0, a Buffer containing a function index bitfield. - Otherwise, the return value and type depends on the UUID, revision ID - and function index which are described in the DSM specification. - -Methods on NVDIMM ROOT Device -_FIT(Firmware Interface Table) - It evaluates to a buffer returning data in the format of a series of NFIT - Type Structure. - - Arguments: None - - Return Value: - A Buffer containing a list of NFIT Type structure entries. - - The detailed definition of the structure can be found at ACPI 6.0: 5.2.25 - NVDIMM Firmware Interface Table (NFIT). - -QEMU NVDIMM Implementation -========================== -QEMU uses 4 bytes IO Port starting from 0x0a18 and a RAM-based memory page -for NVDIMM ACPI. - -Memory: - QEMU uses BIOS Linker/loader feature to ask BIOS to allocate a memory - page and dynamically patch its address into an int32 object named "MEMA" - in ACPI. - - This page is RAM-based and it is used to transfer data between _DSM - method and QEMU. If ACPI has control, this pages is owned by ACPI which - writes _DSM input data to it, otherwise, it is owned by QEMU which - emulates _DSM access and writes the output data to it. - - ACPI writes _DSM Input Data (based on the offset in the page): - [0x0 - 0x3]: 4 bytes, NVDIMM Device Handle. - - The handle is completely QEMU internal thing, the values in - range [1, 0xFFFF] indicate nvdimm device. Other values are - reserved for other purposes. - - Reserved handles: - 0 is reserved for nvdimm root device named NVDR. - 0x10000 is reserved for QEMU internal DSM function called on - the root device. - - [0x4 - 0x7]: 4 bytes, Revision ID, that is the Arg1 of _DSM method. - [0x8 - 0xB]: 4 bytes. Function Index, that is the Arg2 of _DSM method. - [0xC - 0xFFF]: 4084 bytes, the Arg3 of _DSM method. - - QEMU Writes Output Data (based on the offset in the page): - [0x0 - 0x3]: 4 bytes, the length of result - [0x4 - 0xFFF]: 4092 bytes, the DSM result filled by QEMU - -IO Port 0x0a18 - 0xa1b: - ACPI writes the address of the memory page allocated by BIOS to this - port then QEMU gets the control and fills the result in the memory page. - - write Access: - [0x0a18 - 0xa1b]: 4 bytes, the address of the memory page allocated - by BIOS. - -_DSM process diagram: ---------------------- -"MEMA" indicates the address of memory page allocated by BIOS. - - +----------------------+ +-----------------------+ - | 1. OSPM | | 2. OSPM | - | save _DSM input data | | write "MEMA" to | Exit to QEMU - | to the page +----->| IO port 0x0a18 +------------+ - | indicated by "MEMA" | | | | - +----------------------+ +-----------------------+ | - | - v - +------------- ----+ +-----------+ +------------------+--------+ - | 5 QEMU | | 4 QEMU | | 3. QEMU | - | write _DSM result | | emulate | | get _DSM input data from | - | to the page +<------+ _DSM +<-----+ the page indicated by the | - | | | | | value from the IO port | - +--------+-----------+ +-----------+ +---------------------------+ - | - | Enter Guest - | - v - +--------------------------+ +--------------+ - | 6 OSPM | | 7 OSPM | - | result size is returned | | _DSM return | - | by reading DSM +----->+ | - | result from the page | | | - +--------------------------+ +--------------+ - -NVDIMM hotplug --------------- -ACPI BIOS GPE.4 handler is dedicated for notifying OS about nvdimm device -hot-add event. - -QEMU internal use only _DSM function ------------------------------------- -1) Read FIT - _FIT method uses _DSM method to fetch NFIT structures blob from QEMU - in 1 page sized increments which are then concatenated and returned - as _FIT method result. - - Input parameters: - Arg0 – UUID {set to 648B9CF2-CDA1-4312-8AD9-49C4AF32BD62} - Arg1 – Revision ID (set to 1) - Arg2 - Function Index, 0x1 - Arg3 - A package containing a buffer whose layout is as follows: - - +----------+--------+--------+-------------------------------------------+ - | Field | Length | Offset | Description | - +----------+--------+--------+-------------------------------------------+ - | offset | 4 | 0 | offset in QEMU's NFIT structures blob to | - | | | | read from | - +----------+--------+--------+-------------------------------------------+ - - Output layout in the dsm memory page: - +----------+--------+--------+-------------------------------------------+ - | Field | Length | Offset | Description | - +----------+--------+--------+-------------------------------------------+ - | length | 4 | 0 | length of entire returned data | - | | | | (including this header) | - +----------+-----------------+-------------------------------------------+ - | | | | return status codes | - | | | | 0x0 - success | - | | | | 0x100 - error caused by NFIT update while | - | status | 4 | 4 | read by _FIT wasn't completed, other | - | | | | codes follow Chapter 3 in DSM Spec Rev1 | - +----------+-----------------+-------------------------------------------+ - | fit data | Varies | 8 | contains FIT data, this field is present | - | | | | if status field is 0; | - +----------+--------+--------+-------------------------------------------+ - - The FIT offset is maintained by the OSPM itself, current offset plus - the size of the fit data returned by the function is the next offset - OSPM should read. When all FIT data has been read out, zero fit data - size is returned. - - If it returns status code 0x100, OSPM should restart to read FIT (read - from offset 0 again). diff --git a/docs/specs/acpi_pci_hotplug.txt b/docs/specs/acpi_pci_hotplug.rst index a839434f31..685bc5c322 100644 --- a/docs/specs/acpi_pci_hotplug.txt +++ b/docs/specs/acpi_pci_hotplug.rst @@ -1,45 +1,48 @@ QEMU<->ACPI BIOS PCI hotplug interface --------------------------------------- +====================================== QEMU supports PCI hotplug via ACPI, for PCI bus 0. This document describes the interface between QEMU and the ACPI BIOS. -ACPI GPE block (IO ports 0xafe0-0xafe3, byte access): ------------------------------------------ +ACPI GPE block (IO ports 0xafe0-0xafe3, byte access) +---------------------------------------------------- Generic ACPI GPE block. Bit 1 (GPE.1) used to notify PCI hotplug/eject event to ACPI BIOS, via SCI interrupt. -PCI slot injection notification pending (IO port 0xae00-0xae03, 4-byte access): ---------------------------------------------------------------- +PCI slot injection notification pending (IO port 0xae00-0xae03, 4-byte access) +------------------------------------------------------------------------------ + Slot injection notification pending. One bit per slot. Read by ACPI BIOS GPE.1 handler to notify OS of injection events. Read-only. -PCI slot removal notification (IO port 0xae04-0xae07, 4-byte access): ------------------------------------------------------ +PCI slot removal notification (IO port 0xae04-0xae07, 4-byte access) +-------------------------------------------------------------------- + Slot removal notification pending. One bit per slot. Read by ACPI BIOS GPE.1 handler to notify OS of removal events. Read-only. -PCI device eject (IO port 0xae08-0xae0b, 4-byte access): ----------------------------------------- +PCI device eject (IO port 0xae08-0xae0b, 4-byte access) +------------------------------------------------------- Write: Used by ACPI BIOS _EJ0 method to request device removal. One bit per slot. Read: Hotplug features register. Used by platform to identify features available. Current base feature set (no bits set): - - Read-only "up" register @0xae00, 4-byte access, bit per slot - - Read-only "down" register @0xae04, 4-byte access, bit per slot - - Read/write "eject" register @0xae08, 4-byte access, - write: bit per slot eject, read: hotplug feature set - - Read-only hotplug capable register @0xae0c, 4-byte access, bit per slot -PCI removability status (IO port 0xae0c-0xae0f, 4-byte access): ------------------------------------------------ +- Read-only "up" register @0xae00, 4-byte access, bit per slot +- Read-only "down" register @0xae04, 4-byte access, bit per slot +- Read/write "eject" register @0xae08, 4-byte access, + write: bit per slot eject, read: hotplug feature set +- Read-only hotplug capable register @0xae0c, 4-byte access, bit per slot + +PCI removability status (IO port 0xae0c-0xae0f, 4-byte access) +-------------------------------------------------------------- Used by ACPI BIOS _RMV method to indicate removability status to OS. One -bit per slot. Read-only +bit per slot. Read-only. diff --git a/docs/specs/index.rst b/docs/specs/index.rst index b7b08ea30d..65e9663916 100644 --- a/docs/specs/index.rst +++ b/docs/specs/index.rst @@ -13,3 +13,7 @@ guest hardware that is specific to QEMU. acpi_hw_reduced_hotplug tpm acpi_hest_ghes + acpi_cpu_hotplug + acpi_mem_hotplug + acpi_pci_hotplug + acpi_nvdimm |