* [PATCH 1/5] docs/specs/acpu_cpu_hotplug: Convert to rST
2021-07-27 17:04 [PATCH 0/5] docs/specs: Convert various ACPI docs to rST Peter Maydell
@ 2021-07-27 17:04 ` Peter Maydell
2021-07-27 17:04 ` [PATCH 2/5] docs/specs/acpi_mem_hotplug: " Peter Maydell
` (4 subsequent siblings)
5 siblings, 0 replies; 9+ messages in thread
From: Peter Maydell @ 2021-07-27 17:04 UTC (permalink / raw)
To: qemu-devel; +Cc: Igor Mammedov, Xiao Guangrong, Michael S. Tsirkin
Do a basic conversion of the acpi_cpu_hotplug spec document to rST.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
docs/specs/acpi_cpu_hotplug.rst | 235 ++++++++++++++++++++++++++++++++
docs/specs/acpi_cpu_hotplug.txt | 160 ----------------------
docs/specs/index.rst | 1 +
3 files changed, 236 insertions(+), 160 deletions(-)
create mode 100644 docs/specs/acpi_cpu_hotplug.rst
delete mode 100644 docs/specs/acpi_cpu_hotplug.txt
diff --git a/docs/specs/acpi_cpu_hotplug.rst b/docs/specs/acpi_cpu_hotplug.rst
new file mode 100644
index 00000000000..351057c9676
--- /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 9bd59ae0dae..00000000000
--- 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/index.rst b/docs/specs/index.rst
index b7b08ea30d7..24b765e1a45 100644
--- a/docs/specs/index.rst
+++ b/docs/specs/index.rst
@@ -13,3 +13,4 @@ guest hardware that is specific to QEMU.
acpi_hw_reduced_hotplug
tpm
acpi_hest_ghes
+ acpi_cpu_hotplug
--
2.20.1
^ permalink raw reply related [flat|nested] 9+ messages in thread* [PATCH 2/5] docs/specs/acpi_mem_hotplug: Convert to rST
2021-07-27 17:04 [PATCH 0/5] docs/specs: Convert various ACPI docs to rST Peter Maydell
2021-07-27 17:04 ` [PATCH 1/5] docs/specs/acpu_cpu_hotplug: Convert " Peter Maydell
@ 2021-07-27 17:04 ` Peter Maydell
2021-07-27 17:04 ` [PATCH 3/5] docs/specs/acpi_pci_hotplug: " Peter Maydell
` (3 subsequent siblings)
5 siblings, 0 replies; 9+ messages in thread
From: Peter Maydell @ 2021-07-27 17:04 UTC (permalink / raw)
To: qemu-devel; +Cc: Igor Mammedov, Xiao Guangrong, Michael S. Tsirkin
Convert the acpi memory hotplug spec to rST.
Note that this includes converting a lot of weird whitespace
characters to plain old spaces (the rST parser does not like
whatever the old ones were).
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
docs/specs/acpi_mem_hotplug.rst | 128 ++++++++++++++++++++++++++++++++
docs/specs/acpi_mem_hotplug.txt | 94 -----------------------
docs/specs/index.rst | 1 +
3 files changed, 129 insertions(+), 94 deletions(-)
create mode 100644 docs/specs/acpi_mem_hotplug.rst
delete mode 100644 docs/specs/acpi_mem_hotplug.txt
diff --git a/docs/specs/acpi_mem_hotplug.rst b/docs/specs/acpi_mem_hotplug.rst
new file mode 100644
index 00000000000..069819bc3e0
--- /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 3df3620ce42..00000000000
--- 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/index.rst b/docs/specs/index.rst
index 24b765e1a45..17cc7868b91 100644
--- a/docs/specs/index.rst
+++ b/docs/specs/index.rst
@@ -14,3 +14,4 @@ guest hardware that is specific to QEMU.
tpm
acpi_hest_ghes
acpi_cpu_hotplug
+ acpi_mem_hotplug
--
2.20.1
^ permalink raw reply related [flat|nested] 9+ messages in thread* [PATCH 3/5] docs/specs/acpi_pci_hotplug: Convert to rST
2021-07-27 17:04 [PATCH 0/5] docs/specs: Convert various ACPI docs to rST Peter Maydell
2021-07-27 17:04 ` [PATCH 1/5] docs/specs/acpu_cpu_hotplug: Convert " Peter Maydell
2021-07-27 17:04 ` [PATCH 2/5] docs/specs/acpi_mem_hotplug: " Peter Maydell
@ 2021-07-27 17:04 ` Peter Maydell
2021-07-30 13:04 ` Igor Mammedov
2021-07-27 17:04 ` [PATCH 4/5] docs/specs/acpi_nvdimm: " Peter Maydell
` (2 subsequent siblings)
5 siblings, 1 reply; 9+ messages in thread
From: Peter Maydell @ 2021-07-27 17:04 UTC (permalink / raw)
To: qemu-devel; +Cc: Igor Mammedov, Xiao Guangrong, Michael S. Tsirkin
Convert the PCI hotplug spec document to rST.
---
...i_pci_hotplug.txt => acpi_pci_hotplug.rst} | 37 ++++++++++---------
docs/specs/index.rst | 1 +
2 files changed, 21 insertions(+), 17 deletions(-)
rename docs/specs/{acpi_pci_hotplug.txt => acpi_pci_hotplug.rst} (51%)
diff --git a/docs/specs/acpi_pci_hotplug.txt b/docs/specs/acpi_pci_hotplug.rst
similarity index 51%
rename from docs/specs/acpi_pci_hotplug.txt
rename to docs/specs/acpi_pci_hotplug.rst
index a839434f313..685bc5c322f 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 17cc7868b91..8296fb19b72 100644
--- a/docs/specs/index.rst
+++ b/docs/specs/index.rst
@@ -15,3 +15,4 @@ guest hardware that is specific to QEMU.
acpi_hest_ghes
acpi_cpu_hotplug
acpi_mem_hotplug
+ acpi_pci_hotplug
--
2.20.1
^ permalink raw reply related [flat|nested] 9+ messages in thread* Re: [PATCH 3/5] docs/specs/acpi_pci_hotplug: Convert to rST
2021-07-27 17:04 ` [PATCH 3/5] docs/specs/acpi_pci_hotplug: " Peter Maydell
@ 2021-07-30 13:04 ` Igor Mammedov
0 siblings, 0 replies; 9+ messages in thread
From: Igor Mammedov @ 2021-07-30 13:04 UTC (permalink / raw)
To: Peter Maydell; +Cc: Xiao Guangrong, jusual, qemu-devel, Michael S. Tsirkin
On Tue, 27 Jul 2021 18:04:12 +0100
Peter Maydell <peter.maydell@linaro.org> wrote:
> Convert the PCI hotplug spec document to rST.
Julia,
This doc doesn't describe ACPI PCI hotplug we have now,
Care to update it?
> ---
> ...i_pci_hotplug.txt => acpi_pci_hotplug.rst} | 37 ++++++++++---------
> docs/specs/index.rst | 1 +
> 2 files changed, 21 insertions(+), 17 deletions(-)
> rename docs/specs/{acpi_pci_hotplug.txt => acpi_pci_hotplug.rst} (51%)
>
> diff --git a/docs/specs/acpi_pci_hotplug.txt b/docs/specs/acpi_pci_hotplug.rst
> similarity index 51%
> rename from docs/specs/acpi_pci_hotplug.txt
> rename to docs/specs/acpi_pci_hotplug.rst
> index a839434f313..685bc5c322f 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 17cc7868b91..8296fb19b72 100644
> --- a/docs/specs/index.rst
> +++ b/docs/specs/index.rst
> @@ -15,3 +15,4 @@ guest hardware that is specific to QEMU.
> acpi_hest_ghes
> acpi_cpu_hotplug
> acpi_mem_hotplug
> + acpi_pci_hotplug
^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH 4/5] docs/specs/acpi_nvdimm: Convert to rST
2021-07-27 17:04 [PATCH 0/5] docs/specs: Convert various ACPI docs to rST Peter Maydell
` (2 preceding siblings ...)
2021-07-27 17:04 ` [PATCH 3/5] docs/specs/acpi_pci_hotplug: " Peter Maydell
@ 2021-07-27 17:04 ` Peter Maydell
2021-07-27 17:04 ` [PATCH 5/5] MAINTAINERS: Add ACPI specs documents to ACPI and NVDIMM sections Peter Maydell
2021-07-30 12:55 ` [PATCH 0/5] docs/specs: Convert various ACPI docs to rST Igor Mammedov
5 siblings, 0 replies; 9+ messages in thread
From: Peter Maydell @ 2021-07-27 17:04 UTC (permalink / raw)
To: qemu-devel; +Cc: Igor Mammedov, Xiao Guangrong, Michael S. Tsirkin
Convert the ACPI NVDIMM spec document to rST.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
docs/specs/acpi_nvdimm.rst | 228 +++++++++++++++++++++++++++++++++++++
docs/specs/acpi_nvdimm.txt | 188 ------------------------------
docs/specs/index.rst | 1 +
3 files changed, 229 insertions(+), 188 deletions(-)
create mode 100644 docs/specs/acpi_nvdimm.rst
delete mode 100644 docs/specs/acpi_nvdimm.txt
diff --git a/docs/specs/acpi_nvdimm.rst b/docs/specs/acpi_nvdimm.rst
new file mode 100644
index 00000000000..ab0335253d7
--- /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 3ec42ecbce4..00000000000
--- 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/index.rst b/docs/specs/index.rst
index 8296fb19b72..65e9663916a 100644
--- a/docs/specs/index.rst
+++ b/docs/specs/index.rst
@@ -16,3 +16,4 @@ guest hardware that is specific to QEMU.
acpi_cpu_hotplug
acpi_mem_hotplug
acpi_pci_hotplug
+ acpi_nvdimm
--
2.20.1
^ permalink raw reply related [flat|nested] 9+ messages in thread* [PATCH 5/5] MAINTAINERS: Add ACPI specs documents to ACPI and NVDIMM sections
2021-07-27 17:04 [PATCH 0/5] docs/specs: Convert various ACPI docs to rST Peter Maydell
` (3 preceding siblings ...)
2021-07-27 17:04 ` [PATCH 4/5] docs/specs/acpi_nvdimm: " Peter Maydell
@ 2021-07-27 17:04 ` Peter Maydell
2021-07-30 12:55 ` [PATCH 0/5] docs/specs: Convert various ACPI docs to rST Igor Mammedov
5 siblings, 0 replies; 9+ messages in thread
From: Peter Maydell @ 2021-07-27 17:04 UTC (permalink / raw)
To: qemu-devel; +Cc: Igor Mammedov, Xiao Guangrong, Michael S. Tsirkin
Add entries for the ACPI specs documents in docs/specs to
appropriate sections of MAINTAINERS.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
This is an educated guess; feel free to suggest that these
files should go in other sections.
---
MAINTAINERS | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index 445f7fe2d19..ae9c2680134 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1751,6 +1751,10 @@ F: qapi/acpi.json
F: tests/qtest/bios-tables-test*
F: tests/qtest/acpi-utils.[hc]
F: tests/data/acpi/
+F: docs/specs/acpi_cpu_hotplug.rst
+F: docs/specs/acpi_mem_hotplug.rst
+F: docs/specs/acpi_pci_hotplug.rst
+F: docs/specs/acpi_hw_reduced_hotplug.rst
ACPI/HEST/GHES
R: Dongjiu Geng <gengdongjiu1@gmail.com>
@@ -2058,6 +2062,7 @@ F: hw/acpi/nvdimm.c
F: hw/mem/nvdimm.c
F: include/hw/mem/nvdimm.h
F: docs/nvdimm.txt
+F: docs/specs/acpi_nvdimm.rst
e1000x
M: Dmitry Fleytman <dmitry.fleytman@gmail.com>
--
2.20.1
^ permalink raw reply related [flat|nested] 9+ messages in thread* Re: [PATCH 0/5] docs/specs: Convert various ACPI docs to rST
2021-07-27 17:04 [PATCH 0/5] docs/specs: Convert various ACPI docs to rST Peter Maydell
` (4 preceding siblings ...)
2021-07-27 17:04 ` [PATCH 5/5] MAINTAINERS: Add ACPI specs documents to ACPI and NVDIMM sections Peter Maydell
@ 2021-07-30 12:55 ` Igor Mammedov
2021-08-26 14:33 ` Peter Maydell
5 siblings, 1 reply; 9+ messages in thread
From: Igor Mammedov @ 2021-07-30 12:55 UTC (permalink / raw)
To: Peter Maydell; +Cc: Xiao Guangrong, qemu-devel, Michael S. Tsirkin
On Tue, 27 Jul 2021 18:04:09 +0100
Peter Maydell <peter.maydell@linaro.org> wrote:
> This patchset does a basic conversion of four ACPI related files in
> docs/specs from plain text to rST format. The aim of the conversion
> is not to produce a maximally pretty result, but simply to do a
> low-effort conversion that at least results in this documentation
> appearing in our manuals rather than merely lying around in the
> source tree.
>
> Patch 4 adds the documentation files to MAINTAINERS file
> blocks; feel free to suggest I've picked the wrong ones.
compiled, and checked end result (html docs) which looks fine to me,
so
Reviewed-by: Igor Mammedov <imammedo@redhat.com>
>
> thanks
> -- PMM
>
> Peter Maydell (5):
> docs/specs/acpu_cpu_hotplug: Convert to rST
> docs/specs/acpi_mem_hotplug: Convert to rST
> docs/specs/acpi_pci_hotplug: Convert to rST
> docs/specs/acpi_nvdimm: Convert to rST
> MAINTAINERS: Add ACPI specs documents to ACPI and NVDIMM sections
>
> docs/specs/acpi_cpu_hotplug.rst | 235 ++++++++++++++++++
> docs/specs/acpi_cpu_hotplug.txt | 160 ------------
> docs/specs/acpi_mem_hotplug.rst | 128 ++++++++++
> docs/specs/acpi_mem_hotplug.txt | 94 -------
> docs/specs/acpi_nvdimm.rst | 228 +++++++++++++++++
> docs/specs/acpi_nvdimm.txt | 188 --------------
> ...i_pci_hotplug.txt => acpi_pci_hotplug.rst} | 37 +--
> docs/specs/index.rst | 4 +
> MAINTAINERS | 5 +
> 9 files changed, 620 insertions(+), 459 deletions(-)
> create mode 100644 docs/specs/acpi_cpu_hotplug.rst
> delete mode 100644 docs/specs/acpi_cpu_hotplug.txt
> create mode 100644 docs/specs/acpi_mem_hotplug.rst
> delete mode 100644 docs/specs/acpi_mem_hotplug.txt
> create mode 100644 docs/specs/acpi_nvdimm.rst
> delete mode 100644 docs/specs/acpi_nvdimm.txt
> rename docs/specs/{acpi_pci_hotplug.txt => acpi_pci_hotplug.rst} (51%)
>
^ permalink raw reply [flat|nested] 9+ messages in thread* Re: [PATCH 0/5] docs/specs: Convert various ACPI docs to rST
2021-07-30 12:55 ` [PATCH 0/5] docs/specs: Convert various ACPI docs to rST Igor Mammedov
@ 2021-08-26 14:33 ` Peter Maydell
0 siblings, 0 replies; 9+ messages in thread
From: Peter Maydell @ 2021-08-26 14:33 UTC (permalink / raw)
To: Igor Mammedov; +Cc: Xiao Guangrong, QEMU Developers, Michael S. Tsirkin
On Fri, 30 Jul 2021 at 13:56, Igor Mammedov <imammedo@redhat.com> wrote:
>
> On Tue, 27 Jul 2021 18:04:09 +0100
> Peter Maydell <peter.maydell@linaro.org> wrote:
>
> > This patchset does a basic conversion of four ACPI related files in
> > docs/specs from plain text to rST format. The aim of the conversion
> > is not to produce a maximally pretty result, but simply to do a
> > low-effort conversion that at least results in this documentation
> > appearing in our manuals rather than merely lying around in the
> > source tree.
> >
> > Patch 4 adds the documentation files to MAINTAINERS file
> > blocks; feel free to suggest I've picked the wrong ones.
>
> compiled, and checked end result (html docs) which looks fine to me,
> so
>
> Reviewed-by: Igor Mammedov <imammedo@redhat.com>
Thanks; I'll take this via target-arm.next.
-- PMM
^ permalink raw reply [flat|nested] 9+ messages in thread