From 615a55827c590d75bff8a660fc20675fea6c73d3 Mon Sep 17 00:00:00 2001
From: Peter Maydell <peter.maydell@linaro.org>
Date: Tue, 27 Jul 2021 18:04:11 +0100
Subject: [PATCH] docs/specs/acpi_mem_hotplug: Convert to rST
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>
Reviewed-by: Igor Mammedov <imammedo@redhat.com>
Message-id: 20210727170414.3368-3-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 0000000000..069819bc3e
--- /dev/null
+++ b/docs/specs/acpi_mem_hotplug.rst
@@ -0,0 +1,128 @@
+QEMU<->ACPI BIOS memory hotplug interface
+=========================================
+
+ACPI BIOS GPE.3 handler is dedicated for notifying OS about memory hot-add
+and hot-remove events.
+
+Memory hot-plug interface (IO port 0xa00-0xa17, 1-4 byte access)
+----------------------------------------------------------------
+
+Read access behavior
+^^^^^^^^^^^^^^^^^^^^
+
+[0x0-0x3]
+ Lo part of memory device phys address
+[0x4-0x7]
+ Hi part of memory device phys address
+[0x8-0xb]
+ Lo part of memory device size in bytes
+[0xc-0xf]
+ Hi part of memory device size in bytes
+[0x10-0x13]
+ Memory device proximity domain
+[0x14]
+ Memory device status fields
+
+ bits:
+
+ 0:
+ Device is enabled and may be used by guest
+ 1:
+ Device insert event, used to distinguish device for which
+ no device check event to OSPM was issued.
+ It's valid only when bit 1 is set.
+ 2:
+ Device remove event, used to distinguish device for which
+ no device eject request to OSPM was issued.
+ 3-7:
+ reserved and should be ignored by OSPM
+
+[0x15-0x17]
+ reserved
+
+Write access behavior
+^^^^^^^^^^^^^^^^^^^^^
+
+
+[0x0-0x3]
+ Memory device slot selector, selects active memory device.
+ All following accesses to other registers in 0xa00-0xa17
+ region will read/store data from/to selected memory device.
+[0x4-0x7]
+ OST event code reported by OSPM
+[0x8-0xb]
+ OST status code reported by OSPM
+[0xc-0x13]
+ reserved, writes into it are ignored
+[0x14]
+ Memory device control fields
+
+ bits:
+
+ 0:
+ reserved, OSPM must clear it before writing to register.
+ Due to BUG in versions prior 2.4 that field isn't cleared
+ when other fields are written. Keep it reserved and don't
+ try to reuse it.
+ 1:
+ if set to 1 clears device insert event, set by OSPM
+ after it has emitted device check event for the
+ selected memory device
+ 2:
+ if set to 1 clears device remove event, set by OSPM
+ after it has emitted device eject request for the
+ selected memory device
+ 3:
+ if set to 1 initiates device eject, set by OSPM when it
+ triggers memory device removal and calls _EJ0 method
+ 4-7:
+ reserved, OSPM must clear them before writing to register
+
+Selecting memory device slot beyond present range has no effect on platform:
+
+- write accesses to memory hot-plug registers not documented above are ignored
+- read accesses to memory hot-plug registers not documented above return
+ all bits set to 1.
+
+Memory hot remove process diagram
+---------------------------------
+
+::
+
+ +-------------+ +-----------------------+ +------------------+
+ | 1. QEMU | | 2. QEMU | |3. QEMU |
+ | device_del +---->+ device unplug request +----->+Send SCI to guest,|
+ | | | cb | |return control to |
+ | | | | |management |
+ +-------------+ +-----------------------+ +------------------+
+
+ +---------------------------------------------------------------------+
+
+ +---------------------+ +-------------------------+
+ | OSPM: | remove event | OSPM: |
+ | send Eject Request, | | Scan memory devices |
+ | clear remove event +<-------------+ for event flags |
+ | | | |
+ +---------------------+ +-------------------------+
+ |
+ |
+ +---------v--------+ +-----------------------+
+ | Guest OS: | success | OSPM: |
+ | process Ejection +----------->+ Execute _EJ0 method, |
+ | request | | set eject bit in flags|
+ +------------------+ +-----------------------+
+ |failure |
+ v v
+ +------------------------+ +-----------------------+
+ | OSPM: | | QEMU: |
+ | set OST event & status | | call device unplug cb |
+ | fields | | |
+ +------------------------+ +-----------------------+
+ | |
+ v v
+ +------------------+ +-------------------+
+ |QEMU: | |QEMU: |
+ |Send OST QMP event| |Send device deleted|
+ | | |QMP event |
+ +------------------+ | |
+ +-------------------+
diff --git a/docs/specs/acpi_mem_hotplug.txt b/docs/specs/acpi_mem_hotplug.txt
deleted file mode 100644
index 3df3620ce4..0000000000
--- a/docs/specs/acpi_mem_hotplug.txt
+++ /dev/null
@@ -1,94 +0,0 @@
-QEMU<->ACPI BIOS memory hotplug interface
---------------------------------------
-
-ACPI BIOS GPE.3 handler is dedicated for notifying OS about memory hot-add
-and hot-remove events.
-
-Memory hot-plug interface (IO port 0xa00-0xa17, 1-4 byte access):
----------------------------------------------------------------
-0xa00:
- read access:
- [0x0-0x3] Lo part of memory device phys address
- [0x4-0x7] Hi part of memory device phys address
- [0x8-0xb] Lo part of memory device size in bytes
- [0xc-0xf] Hi part of memory device size in bytes
- [0x10-0x13] Memory device proximity domain
- [0x14] Memory device status fields
- bits:
- 0: Device is enabled and may be used by guest
- 1: Device insert event, used to distinguish device for which
- no device check event to OSPM was issued.
- It's valid only when bit 1 is set.
- 2: Device remove event, used to distinguish device for which
- no device eject request to OSPM was issued.
- 3-7: reserved and should be ignored by OSPM
- [0x15-0x17] reserved
-
- write access:
- [0x0-0x3] Memory device slot selector, selects active memory device.
- All following accesses to other registers in 0xa00-0xa17
- region will read/store data from/to selected memory device.
- [0x4-0x7] OST event code reported by OSPM
- [0x8-0xb] OST status code reported by OSPM
- [0xc-0x13] reserved, writes into it are ignored
- [0x14] Memory device control fields
- bits:
- 0: reserved, OSPM must clear it before writing to register.
- Due to BUG in versions prior 2.4 that field isn't cleared
- when other fields are written. Keep it reserved and don't
- try to reuse it.
- 1: if set to 1 clears device insert event, set by OSPM
- after it has emitted device check event for the
- selected memory device
- 2: if set to 1 clears device remove event, set by OSPM
- after it has emitted device eject request for the
- selected memory device
- 3: if set to 1 initiates device eject, set by OSPM when it
- triggers memory device removal and calls _EJ0 method
- 4-7: reserved, OSPM must clear them before writing to register
-
-Selecting memory device slot beyond present range has no effect on platform:
- - write accesses to memory hot-plug registers not documented above are
- ignored
- - read accesses to memory hot-plug registers not documented above return
- all bits set to 1.
-
-Memory hot remove process diagram:
-----------------------------------
- +-------------+âââââ+-----------------------+ââââââ+------------------+âââââ
-â|ââ1.âQEMUââââ|âââââ|â2.âQEMUâââââââââââââââ|ââââââ|3.âQEMUâââââââââââ|âââââ
-â|ââdevice_delâ+---->+âdeviceâunplugârequestâ+----->+SendâSCIâtoâguest,|âââââ
-â|âââââââââââââ|âââââ|âââââââââcbââââââââââââ|ââââââ|returnâcontrolâtoâ|âââââ
-â+-------------+âââââ+-----------------------+ââââââ|managementââââââââ|âââââ
-ââââââââââââââââââââââââââââââââââââââââââââââââââââ+------------------+âââââ
-âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ
-â+---------------------------------------------------------------------+âââââ
-âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ
-â+---------------------+ââââââââââââââ+-------------------------+ââââââââââââ
-â|âOSPM:âââââââââââââââ|âremoveâeventâ|âOSPM:âââââââââââââââââââ|ââââââââââââ
-â|âsendâEjectâRequest,â|ââââââââââââââ|âScanâmemoryâdevicesâââââ|ââââââââââââ
-â|âclearâremoveâeventââ+<-------------+âforâeventâflagsâââââââââ|ââââââââââââ
-â|âââââââââââââââââââââ|ââââââââââââââ|âââââââââââââââââââââââââ|ââââââââââââ
-â+---------------------+ââââââââââââââ+-------------------------+ââââââââââââ
-âââââââââââ|âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ
-âââââââââââ|âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ
-â+---------v--------+ââââââââââââ+-----------------------+âââââââââââââââââââ
-â|âGuestâOS:ââââââââ|ââsuccessâââ|âOSPM:âââââââââââââââââ|âââââââââââââââââââ
-â|âprocessâEjectionâ+----------->+âExecuteâ_EJ0âmethod, â|âââââââââââââââââââ
-â|ârequest âââââââââ|ââââââââââââ|âsetâejectâbitâinâflags|âââââââââââââââââââ
-â+------------------+ââââââââââââ+-----------------------+âââââââââââââââââââ
-âââââââââââ|failureâââââââââââââââââââââââââ|ââââââââââââââââââââââââââââââââ
-âââââââââââvââââââââââââââââââââââââââââââââvââââââââââââââââââââââââââââââââ
-â+------------------------+ââââââ+-----------------------+âââââââââââââââââââ
-â|âOSPM:ââââââââââââââââââ|ââââââ|âQEMU:âââââââââââââââââ|âââââââââââââââââââ
-â|âsetâOSTâeventâ&âstatusâ|ââââââ|âcallâdeviceâunplugâcbâ|âââââââââââââââââââ
-â|âfieldsâââââââââââââââââ|ââââââ|âââââââââââââââââââââââ|âââââââââââââââââââ
-â+------------------------+ââââââ+-----------------------+âââââââââââââââââââ
-ââââââââââ|ââââââââââââââââââââââââââââââââââ|âââââââââââââââââââââââââââââââ
-ââââââââââvââââââââââââââââââââââââââââââââââvâââââââââââââââââââââââââââââââ
-â+------------------+ââââââââââââââ+-------------------+âââââââââââââââââââââ
-â|QEMU:âââââââââââââ|ââââââââââââââ|QEMU:ââââââââââââââ|âââââââââââââââââââââ
-â|SendâOSTâQMPâevent|ââââââââââââââ|Sendâdeviceâdeleted|âââââââââââââââââââââ
-â|ââââââââââââââââââ|ââââââââââââââ|QMPâeventââââââââââ|âââââââââââââââââââââ
-â+------------------+ââââââââââââââ|âââââââââââââââââââ|âââââââââââââââââââââ
-âââââââââââââââââââââââââââââââââââ+-------------------+
diff --git a/docs/specs/index.rst b/docs/specs/index.rst
index 24b765e1a4..17cc7868b9 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.30.2