[06/14] docs: improve the doc of Read FIT method
diff mbox

Message ID 1478517229-140028-7-git-send-email-guangrong.xiao@linux.intel.com
State New
Headers show

Commit Message

Xiao Guangrong Nov. 7, 2016, 11:13 a.m. UTC
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(-)

Comments

Stefan Hajnoczi Nov. 7, 2016, 3:32 p.m. UTC | #1
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>
Igor Mammedov Nov. 9, 2016, 4:39 p.m. UTC | #2
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).

--
To unsubscribe from this list: send the line "unsubscribe kvm" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Patch
diff mbox

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).