mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests 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

90
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
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 |
+----------+-------------+-------------+-----------------------------------+
+----------+--------+--------+-------------------------------------------+
| Field | Length | Offset | Description |
+----------+--------+--------+-------------------------------------------+
| offset | 4 | 0 | offset in QEMU's NFIT structures blob to |
| | | | read from |
+----------+--------+--------+-------------------------------------------+
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 |
| | | | |
+----------+-------------+-------------+-----------------------------------+
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 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.
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 0x100, OSPM should restart to read FIT (read from offset 0
again).
If it returns status code 0x100, OSPM should restart to read FIT (read
from offset 0 again).