qemu-devel.nongnu.org archive mirror
 help / color / mirror / Atom feed
* [PATCH 0/5] docs/specs: Convert various ACPI docs to rST
@ 2021-07-27 17:04 Peter Maydell
  2021-07-27 17:04 ` [PATCH 1/5] docs/specs/acpu_cpu_hotplug: Convert " Peter Maydell
                   ` (5 more replies)
  0 siblings, 6 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

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.

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%)

-- 
2.20.1



^ permalink raw reply	[flat|nested] 9+ messages in thread

* [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

* [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 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

* 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

end of thread, other threads:[~2021-08-26 14:34 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
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 ` [PATCH 3/5] docs/specs/acpi_pci_hotplug: " Peter Maydell
2021-07-30 13:04   ` Igor Mammedov
2021-07-27 17:04 ` [PATCH 4/5] docs/specs/acpi_nvdimm: " 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
2021-08-26 14:33   ` Peter Maydell

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).