[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 2/5] docs/specs/acpi_mem_hotplug: Convert to rST
|
From: |
Peter Maydell |
|
Subject: |
[PATCH 2/5] docs/specs/acpi_mem_hotplug: Convert to rST |
|
Date: |
Tue, 27 Jul 2021 18:04:11 +0100 |
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
- [PATCH 0/5] docs/specs: Convert various ACPI docs to rST, Peter Maydell, 2021/07/27
- [PATCH 3/5] docs/specs/acpi_pci_hotplug: Convert to rST, Peter Maydell, 2021/07/27
- [PATCH 2/5] docs/specs/acpi_mem_hotplug: Convert to rST,
Peter Maydell <=
- [PATCH 5/5] MAINTAINERS: Add ACPI specs documents to ACPI and NVDIMM sections, Peter Maydell, 2021/07/27
- [PATCH 1/5] docs/specs/acpu_cpu_hotplug: Convert to rST, Peter Maydell, 2021/07/27
- [PATCH 4/5] docs/specs/acpi_nvdimm: Convert to rST, Peter Maydell, 2021/07/27
- Re: [PATCH 0/5] docs/specs: Convert various ACPI docs to rST, Igor Mammedov, 2021/07/30