From: Xiao Guangrong <guangrong.xiao@linux.intel.com> To: pbonzini@redhat.com, imammedo@redhat.com Cc: gleb@kernel.org, mtosatti@redhat.com, stefanha@redhat.com, mst@redhat.com, rth@twiddle.net, ehabkost@redhat.com, dan.j.williams@intel.com, kvm@vger.kernel.org, qemu-devel@nongnu.org, Xiao Guangrong <guangrong.xiao@linux.intel.com> Subject: [PATCH 06/14] docs: improve the doc of Read FIT method Date: Mon, 7 Nov 2016 19:13:41 +0800 [thread overview] Message-ID: <1478517229-140028-7-git-send-email-guangrong.xiao@linux.intel.com> (raw) In-Reply-To: <1478517229-140028-1-git-send-email-guangrong.xiao@linux.intel.com> 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(-) 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). -- 1.8.3.1
WARNING: multiple messages have this Message-ID (diff)
From: Xiao Guangrong <guangrong.xiao@linux.intel.com> To: pbonzini@redhat.com, imammedo@redhat.com Cc: gleb@kernel.org, mtosatti@redhat.com, stefanha@redhat.com, mst@redhat.com, rth@twiddle.net, ehabkost@redhat.com, dan.j.williams@intel.com, kvm@vger.kernel.org, qemu-devel@nongnu.org, Xiao Guangrong <guangrong.xiao@linux.intel.com> Subject: [Qemu-devel] [PATCH 06/14] docs: improve the doc of Read FIT method Date: Mon, 7 Nov 2016 19:13:41 +0800 [thread overview] Message-ID: <1478517229-140028-7-git-send-email-guangrong.xiao@linux.intel.com> (raw) In-Reply-To: <1478517229-140028-1-git-send-email-guangrong.xiao@linux.intel.com> 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(-) 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). -- 1.8.3.1
next prev parent reply other threads:[~2016-11-07 11:29 UTC|newest] Thread overview: 86+ messages / expand[flat|nested] mbox.gz Atom feed top 2016-11-07 11:13 [PATCH 00/14] improve nvdimm hotplug Xiao Guangrong 2016-11-07 11:13 ` [Qemu-devel] " Xiao Guangrong 2016-11-07 11:13 ` [PATCH 01/14] qdev: hotplug: drop HotplugHandler.post_plug callback Xiao Guangrong 2016-11-07 11:13 ` [Qemu-devel] " Xiao Guangrong 2016-11-07 15:30 ` Stefan Hajnoczi 2016-11-07 15:30 ` [Qemu-devel] " Stefan Hajnoczi 2016-11-09 16:37 ` Igor Mammedov 2016-11-09 16:37 ` [Qemu-devel] " Igor Mammedov 2016-11-07 11:13 ` [PATCH 02/14] nvdimm acpi: drop the lock of fit buffer Xiao Guangrong 2016-11-07 11:13 ` [Qemu-devel] " Xiao Guangrong 2016-11-07 15:30 ` Stefan Hajnoczi 2016-11-07 15:30 ` [Qemu-devel] " Stefan Hajnoczi 2016-11-09 16:38 ` Igor Mammedov 2016-11-09 16:38 ` [Qemu-devel] " Igor Mammedov 2016-11-07 11:13 ` [PATCH 03/14] pc: memhp: move nvdimm hotplug out of memory hotplug Xiao Guangrong 2016-11-07 11:13 ` [Qemu-devel] " Xiao Guangrong 2016-11-07 15:31 ` Stefan Hajnoczi 2016-11-07 15:31 ` [Qemu-devel] " Stefan Hajnoczi 2016-11-09 16:38 ` Igor Mammedov 2016-11-09 16:38 ` [Qemu-devel] " Igor Mammedov 2016-11-07 11:13 ` [PATCH 04/14] pc: memhp: stop handling nvdimm hotplug in pc_dimm_unplug Xiao Guangrong 2016-11-07 11:13 ` [Qemu-devel] " Xiao Guangrong 2016-11-07 15:32 ` Stefan Hajnoczi 2016-11-07 15:32 ` [Qemu-devel] " Stefan Hajnoczi 2016-11-09 16:38 ` Igor Mammedov 2016-11-09 16:38 ` [Qemu-devel] " Igor Mammedov 2016-11-07 11:13 ` [PATCH 05/14] nvdimm acpi: clean up nvdimm_build_acpi Xiao Guangrong 2016-11-07 11:13 ` [Qemu-devel] " Xiao Guangrong 2016-11-07 15:32 ` Stefan Hajnoczi 2016-11-07 15:32 ` [Qemu-devel] " Stefan Hajnoczi 2016-11-09 16:39 ` Igor Mammedov 2016-11-09 16:39 ` [Qemu-devel] " Igor Mammedov 2016-11-07 11:13 ` Xiao Guangrong [this message] 2016-11-07 11:13 ` [Qemu-devel] [PATCH 06/14] docs: improve the doc of Read FIT method Xiao Guangrong 2016-11-07 15:32 ` Stefan Hajnoczi 2016-11-07 15:32 ` [Qemu-devel] " Stefan Hajnoczi 2016-11-09 16:39 ` Igor Mammedov 2016-11-09 16:39 ` [Qemu-devel] " Igor Mammedov 2016-11-07 11:13 ` [PATCH 07/14] nvdimm acpi: rename nvdimm_plugged_device_list Xiao Guangrong 2016-11-07 11:13 ` [Qemu-devel] " Xiao Guangrong 2016-11-07 15:33 ` Stefan Hajnoczi 2016-11-07 15:33 ` [Qemu-devel] " Stefan Hajnoczi 2016-11-09 16:39 ` Igor Mammedov 2016-11-09 16:39 ` [Qemu-devel] " Igor Mammedov 2016-11-07 11:13 ` [PATCH 08/14] nvdimm acpi: cleanup nvdimm_build_fit Xiao Guangrong 2016-11-07 11:13 ` [Qemu-devel] " Xiao Guangrong 2016-11-07 15:33 ` Stefan Hajnoczi 2016-11-07 15:33 ` [Qemu-devel] " Stefan Hajnoczi 2016-11-09 16:40 ` Igor Mammedov 2016-11-09 16:40 ` [Qemu-devel] " Igor Mammedov 2016-11-07 11:13 ` [PATCH 09/14] nvdimm acpi: rename nvdimm_acpi_hotplug Xiao Guangrong 2016-11-07 11:13 ` [Qemu-devel] " Xiao Guangrong 2016-11-07 15:33 ` Stefan Hajnoczi 2016-11-07 15:33 ` [Qemu-devel] " Stefan Hajnoczi 2016-11-09 16:40 ` Igor Mammedov 2016-11-09 16:40 ` [Qemu-devel] " Igor Mammedov 2016-11-07 11:13 ` [PATCH 10/14] nvdimm acpi: define DSM return codes Xiao Guangrong 2016-11-07 11:13 ` [Qemu-devel] " Xiao Guangrong 2016-11-07 15:34 ` Stefan Hajnoczi 2016-11-07 15:34 ` [Qemu-devel] " Stefan Hajnoczi 2016-11-09 16:40 ` Igor Mammedov 2016-11-09 16:40 ` [Qemu-devel] " Igor Mammedov 2016-11-07 11:13 ` [PATCH 11/14] nvdimm acpi: fix two comments Xiao Guangrong 2016-11-07 11:13 ` [Qemu-devel] " Xiao Guangrong 2016-11-07 15:34 ` Stefan Hajnoczi 2016-11-07 15:34 ` [Qemu-devel] " Stefan Hajnoczi 2016-11-09 16:41 ` Igor Mammedov 2016-11-09 16:41 ` [Qemu-devel] " Igor Mammedov 2016-11-07 11:13 ` [PATCH 12/14] nvdimm acpi: rename nvdimm_dsm_reserved_root Xiao Guangrong 2016-11-07 11:13 ` [Qemu-devel] " Xiao Guangrong 2016-11-07 15:34 ` Stefan Hajnoczi 2016-11-07 15:34 ` [Qemu-devel] " Stefan Hajnoczi 2016-11-09 16:41 ` Igor Mammedov 2016-11-09 16:41 ` [Qemu-devel] " Igor Mammedov 2016-11-07 11:13 ` [PATCH 13/14] nvdimm acpi: use aml_name_decl to define named object Xiao Guangrong 2016-11-07 11:13 ` [Qemu-devel] " Xiao Guangrong 2016-11-07 15:34 ` Stefan Hajnoczi 2016-11-07 15:34 ` [Qemu-devel] " Stefan Hajnoczi 2016-11-09 16:41 ` Igor Mammedov 2016-11-09 16:41 ` [Qemu-devel] " Igor Mammedov 2016-11-07 11:13 ` [PATCH 14/14] nvdimm acpi: introduce NVDIMM_DSM_MEMORY_SIZE Xiao Guangrong 2016-11-07 11:13 ` [Qemu-devel] " Xiao Guangrong 2016-11-07 15:35 ` Stefan Hajnoczi 2016-11-07 15:35 ` [Qemu-devel] " Stefan Hajnoczi 2016-11-09 16:41 ` Igor Mammedov 2016-11-09 16:41 ` [Qemu-devel] " Igor Mammedov
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=1478517229-140028-7-git-send-email-guangrong.xiao@linux.intel.com \ --to=guangrong.xiao@linux.intel.com \ --cc=dan.j.williams@intel.com \ --cc=ehabkost@redhat.com \ --cc=gleb@kernel.org \ --cc=imammedo@redhat.com \ --cc=kvm@vger.kernel.org \ --cc=mst@redhat.com \ --cc=mtosatti@redhat.com \ --cc=pbonzini@redhat.com \ --cc=qemu-devel@nongnu.org \ --cc=rth@twiddle.net \ --cc=stefanha@redhat.com \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.