From: Peter Maydell <peter.maydell@linaro.org>
To: qemu-devel@nongnu.org
Cc: Igor Mammedov <imammedo@redhat.com>,
Xiao Guangrong <xiaoguangrong.eric@gmail.com>,
"Michael S. Tsirkin" <mst@redhat.com>
Subject: [PATCH 2/5] docs/specs/acpi_mem_hotplug: Convert to rST
Date: Tue, 27 Jul 2021 18:04:11 +0100 [thread overview]
Message-ID: <20210727170414.3368-3-peter.maydell@linaro.org> (raw)
In-Reply-To: <20210727170414.3368-1-peter.maydell@linaro.org>
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
next prev parent reply other threads:[~2021-07-27 17:05 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
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 [this message]
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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210727170414.3368-3-peter.maydell@linaro.org \
--to=peter.maydell@linaro.org \
--cc=imammedo@redhat.com \
--cc=mst@redhat.com \
--cc=qemu-devel@nongnu.org \
--cc=xiaoguangrong.eric@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).