| Message ID | 1478517229-140028-7-git-send-email-guangrong.xiao@linux.intel.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Mon, Nov 07, 2016 at 07:13:41PM +0800, Xiao Guangrong wrote: > 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> > --- > docs/specs/acpi_nvdimm.txt | 96 +++++++++++++++++++++++----------------------- > 1 file changed, 47 insertions(+), 49 deletions(-) Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
On Mon, 7 Nov 2016 19:13:41 +0800 Xiao Guangrong <guangrong.xiao@linux.intel.com> wrote: > 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: Igor Mammedov <imammedo@redhat.com> > --- > 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).
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).
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> --- docs/specs/acpi_nvdimm.txt | 96 +++++++++++++++++++++++----------------------- 1 file changed, 47 insertions(+), 49 deletions(-)