[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PULL v3 16/28] docs: improve the doc of Read FIT method
From: |
Michael S. Tsirkin |
Subject: |
[Qemu-devel] [PULL v3 16/28] docs: improve the doc of Read FIT method |
Date: |
Tue, 15 Nov 2016 21:21:53 +0200 |
From: Xiao Guangrong <address@hidden>
Improve the description and clearly document the length field
Suggested-by: Igor Mammedov <address@hidden>
Signed-off-by: Xiao Guangrong <address@hidden>
Reviewed-by: Michael S. Tsirkin <address@hidden>
Signed-off-by: Michael S. Tsirkin <address@hidden>
Reviewed-by: Stefan Hajnoczi <address@hidden>
Reviewed-by: Igor Mammedov <address@hidden>
---
docs/specs/acpi_nvdimm.txt | 96 +++++++++++++++++++++++-----------------------
1 file changed, 47 insertions(+), 49 deletions(-)
diff --git a/docs/specs/acpi_nvdimm.txt b/docs/specs/acpi_nvdimm.txt
index d244147..3f322e6 100644
--- a/docs/specs/acpi_nvdimm.txt
+++ b/docs/specs/acpi_nvdimm.txt
@@ -65,8 +65,8 @@ _FIT(Firmware Interface Table)
The detailed definition of the structure can be found at ACPI 6.0: 5.2.25
NVDIMM Firmware Interface Table (NFIT).
-QEMU NVDIMM Implemention
-========================
+QEMU NVDIMM Implementation
+==========================
QEMU uses 4 bytes IO Port starting from 0x0a18 and a RAM-based memory page
for NVDIMM ACPI.
@@ -80,8 +80,17 @@ Memory:
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, 0 is reserved for NVDIMM
- Root device.
+ [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.
@@ -132,28 +141,12 @@ NVDIMM hotplug
ACPI BIOS GPE.4 handler is dedicated for notifying OS about nvdimm device
hot-add event.
-Device Handle Reservation
--------------------------
-As we mentioned above, byte 0 ~ byte 3 in the DSM memory save NVDIMM device
-handle. The handle is completely QEMU internal thing, the values in range
-[0, 0xFFFF] indicate nvdimm device (O means nvdimm root device named NVDR),
-other values are reserved by other purpose.
-
-Current reserved handle:
-0x10000 is reserved for QEMU internal DSM function called on the root
-device.
-
QEMU internal use only _DSM function
------------------------------------
-UUID, 648B9CF2-CDA1-4312-8AD9-49C4AF32BD62, is reserved for QEMU internal
-DSM function.
-
-There is the function introduced by QEMU and only used by QEMU internal.
-
1) Read FIT
- As we only reserved one page for NVDIMM ACPI it is impossible to map the
- whole FIT data to guest's address space. This function is used by _FIT
- method to read a piece of FIT data from QEMU.
+ _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}
@@ -161,29 +154,34 @@ There is the function introduced by QEMU and only used by
QEMU internal.
Arg2 - Function Index, 0x1
Arg3 - A package containing a buffer whose layout is as follows:
- +----------+-------------+-------------+-----------------------------------+
- | Filed | Byte Length | Byte Offset | Description |
- +----------+-------------+-------------+-----------------------------------+
- | offset | 4 | 0 | the offset of FIT buffer |
- +----------+-------------+-------------+-----------------------------------+
-
- Output:
- +----------+-------------+-------------+-----------------------------------+
- | Filed | Byte Length | Byte Offset | Description |
- +----------+-------------+-------------+-----------------------------------+
- | | | | return status codes |
- | | | | 0x100 indicates fit has been |
- | status | 4 | 0 | updated |
- | | | | other follows Chapter 3 in DSM |
- | | | | Spec Rev1 |
- +----------+-------------+-------------+-----------------------------------+
- | fit data | Varies | 4 | FIT data |
- | | | | |
- +----------+-------------+-------------+-----------------------------------+
-
- The FIT offset is maintained by the caller itself, current offset plugs
- the length returned by the function is the next offset we should read.
- When all the FIT data has been read out, zero length is returned.
-
- If it returns 0x100, OSPM should restart to read FIT (read from offset 0
- again).
+ +----------+--------+--------+-------------------------------------------+
+ | 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).
--
MST
- [Qemu-devel] [PULL v3 06/28] intel_iommu: fix incorrect assert, (continued)
- [Qemu-devel] [PULL v3 06/28] intel_iommu: fix incorrect assert, Michael S. Tsirkin, 2016/11/15
- [Qemu-devel] [PULL v3 07/28] acpi: fix DMAR device scope for IOAPIC, Michael S. Tsirkin, 2016/11/15
- [Qemu-devel] [PULL v3 08/28] virtio: allow per-device-class legacy features, Michael S. Tsirkin, 2016/11/15
- [Qemu-devel] [PULL v3 09/28] virtio-net: mark VIRTIO_NET_F_GSO as legacy, Michael S. Tsirkin, 2016/11/15
- [Qemu-devel] [PULL v3 10/28] vhost: migration blocker only if shared log is used, Michael S. Tsirkin, 2016/11/15
- [Qemu-devel] [PULL v3 11/28] qdev: hotplug: drop HotplugHandler.post_plug callback, Michael S. Tsirkin, 2016/11/15
- [Qemu-devel] [PULL v3 12/28] nvdimm acpi: drop the lock of fit buffer, Michael S. Tsirkin, 2016/11/15
- [Qemu-devel] [PULL v3 13/28] pc: memhp: move nvdimm hotplug out of memory hotplug, Michael S. Tsirkin, 2016/11/15
- [Qemu-devel] [PULL v3 14/28] pc: memhp: stop handling nvdimm hotplug in pc_dimm_unplug, Michael S. Tsirkin, 2016/11/15
- [Qemu-devel] [PULL v3 15/28] nvdimm acpi: clean up nvdimm_build_acpi, Michael S. Tsirkin, 2016/11/15
- [Qemu-devel] [PULL v3 16/28] docs: improve the doc of Read FIT method,
Michael S. Tsirkin <=
- [Qemu-devel] [PULL v3 17/28] nvdimm acpi: rename nvdimm_plugged_device_list, Michael S. Tsirkin, 2016/11/15
- [Qemu-devel] [PULL v3 18/28] nvdimm acpi: cleanup nvdimm_build_fit, Michael S. Tsirkin, 2016/11/15
- [Qemu-devel] [PULL v3 19/28] nvdimm acpi: rename nvdimm_acpi_hotplug, Michael S. Tsirkin, 2016/11/15
- [Qemu-devel] [PULL v3 21/28] nvdimm acpi: fix two comments, Michael S. Tsirkin, 2016/11/15
- [Qemu-devel] [PULL v3 20/28] nvdimm acpi: define DSM return codes, Michael S. Tsirkin, 2016/11/15
- [Qemu-devel] [PULL v3 22/28] nvdimm acpi: rename nvdimm_dsm_reserved_root, Michael S. Tsirkin, 2016/11/15
- [Qemu-devel] [PULL v3 23/28] nvdimm acpi: use aml_name_decl to define named object, Michael S. Tsirkin, 2016/11/15
- [Qemu-devel] [PULL v3 24/28] nvdimm acpi: introduce NVDIMM_DSM_MEMORY_SIZE, Michael S. Tsirkin, 2016/11/15
- [Qemu-devel] [PULL v3 25/28] vhost: adapt vhost_verify_ring_mappings() to virtio 1 ring layout, Michael S. Tsirkin, 2016/11/15
- [Qemu-devel] [PULL v3 26/28] vhost: drop legacy vring layout bits, Michael S. Tsirkin, 2016/11/15