david.venhoff/QEMU-Nyx-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: improve the doc of Read FIT method

Browse Source 
Improve the description and clearly document the length field

Suggested-by: Igor Mammedov <imammedo@redhat.com>
Signed-off-by: Xiao Guangrong <guangrong.xiao@linux.intel.com>
Reviewed-by: Michael S. Tsirkin <mst@redhat.com>
Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Reviewed-by: Igor Mammedov <imammedo@redhat.com>
This commit is contained in:
Xiao Guangrong 2016-11-07 19:13:41 +08:00 committed by Michael S. Tsirkin
parent 264813cb9d
commit 45a994944a
1 changed files with 44 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
docs/specs/acpi_nvdimm.txt
View File

@ -65,8 +65,8 @@ _FIT(Firmware Interface Table)
The detailed definition of the structure can be found at ACPI 6.0: 5.2.25 The detailed definition of the structure can be found at ACPI 6.0: 5.2.25
NVDIMM Firmware Interface Table (NFIT). 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 QEMU uses 4 bytes IO Port starting from 0x0a18 and a RAM-based memory page
for NVDIMM ACPI. for NVDIMM ACPI.
@ -80,8 +80,17 @@ Memory:
emulates _DSM access and writes the output data to it. emulates _DSM access and writes the output data to it.
ACPI writes _DSM Input Data (based on the offset in the page): ACPI writes _DSM Input Data (based on the offset in the page):
[0x0 - 0x3]: 4 bytes, NVDIMM Device Handle, 0 is reserved for NVDIMM [0x0 - 0x3]: 4 bytes, NVDIMM Device Handle.
Root device.
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. [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. [0x8 - 0xB]: 4 bytes. Function Index, that is the Arg2 of _DSM method.
[0xC - 0xFFF]: 4084 bytes, the Arg3 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 ACPI BIOS GPE.4 handler is dedicated for notifying OS about nvdimm device
hot-add event. 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 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 1) Read FIT
As we only reserved one page for NVDIMM ACPI it is impossible to map the _FIT method uses _DSM method to fetch NFIT structures blob from QEMU
whole FIT data to guest's address space. This function is used by _FIT in 1 page sized increments which are then concatenated and returned
method to read a piece of FIT data from QEMU. as _FIT method result.
Input parameters: Input parameters:
Arg0 – UUID {set to 648B9CF2-CDA1-4312-8AD9-49C4AF32BD62} 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 Arg2 - Function Index, 0x1
Arg3 - A package containing a buffer whose layout is as follows: Arg3 - A package containing a buffer whose layout is as follows:
+----------+-------------+-------------+-----------------------------------+ +----------+--------+--------+-------------------------------------------+
| Filed | Byte Length | Byte Offset | Description | | Field | Length | Offset | Description |
+----------+-------------+-------------+-----------------------------------+ +----------+--------+--------+-------------------------------------------+
| offset | 4 | 0 | the offset of FIT buffer | | offset | 4 | 0 | offset in QEMU's NFIT structures blob to |
+----------+-------------+-------------+-----------------------------------+ | | | | read from |
+----------+--------+--------+-------------------------------------------+
Output: Output layout in the dsm memory page:
+----------+-------------+-------------+-----------------------------------+ +----------+--------+--------+-------------------------------------------+
| Filed | Byte Length | Byte Offset | Description | | Field | Length | Offset | Description |
+----------+-------------+-------------+-----------------------------------+ +----------+--------+--------+-------------------------------------------+
| length | 4 | 0 | length of entire returned data |
| | | | (including this header) |
+----------+-----------------+-------------------------------------------+
| | | | return status codes | | | | | return status codes |
| | | | 0x100 indicates fit has been | | | | | 0x0 - success |
| status | 4 | 0 | updated | | | | | 0x100 - error caused by NFIT update while |
| | | | other follows Chapter 3 in DSM | | status | 4 | 4 | read by _FIT wasn't completed, other |
| | | | Spec Rev1 | | | | | codes follow Chapter 3 in DSM Spec Rev1 |
+----------+-------------+-------------+-----------------------------------+ +----------+-----------------+-------------------------------------------+
| fit data | Varies | 4 | FIT data | | fit data | Varies | 8 | contains FIT data, this field is present |
| | | | | | | | | if status field is 0; |
+----------+-------------+-------------+-----------------------------------+ +----------+--------+--------+-------------------------------------------+
The FIT offset is maintained by the caller itself, current offset plugs The FIT offset is maintained by the OSPM itself, current offset plus
the length returned by the function is the next offset we should read. the size of the fit data returned by the function is the next offset
When all the FIT data has been read out, zero length is returned. OSPM should read. When all FIT data has been read out, zero fit data
size is returned.
If it returns 0x100, OSPM should restart to read FIT (read from offset 0 If it returns status code 0x100, OSPM should restart to read FIT (read
again). from offset 0 again).