aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/specs/acpi_cpu_hotplug.rst235
-rw-r--r--docs/specs/acpi_cpu_hotplug.txt160
-rw-r--r--docs/specs/acpi_mem_hotplug.rst128
-rw-r--r--docs/specs/acpi_mem_hotplug.txt94
-rw-r--r--docs/specs/acpi_nvdimm.rst228
-rw-r--r--docs/specs/acpi_nvdimm.txt188
-rw-r--r--docs/specs/acpi_pci_hotplug.rst (renamed from docs/specs/acpi_pci_hotplug.txt)37
-rw-r--r--docs/specs/index.rst4
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