From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:43574) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c4VuU-0007y2-2r for qemu-devel@nongnu.org; Wed, 09 Nov 2016 11:39:39 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1c4VuQ-0003kE-UA for qemu-devel@nongnu.org; Wed, 09 Nov 2016 11:39:38 -0500 Received: from mx1.redhat.com ([209.132.183.28]:42014) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1c4VuQ-0003k4-Lx for qemu-devel@nongnu.org; Wed, 09 Nov 2016 11:39:34 -0500 Date: Wed, 9 Nov 2016 17:39:30 +0100 From: Igor Mammedov Message-ID: <20161109173930.2178c158@nial.brq.redhat.com> In-Reply-To: <1478517229-140028-7-git-send-email-guangrong.xiao@linux.intel.com> References: <1478517229-140028-1-git-send-email-guangrong.xiao@linux.intel.com> <1478517229-140028-7-git-send-email-guangrong.xiao@linux.intel.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Subject: Re: [Qemu-devel] [PATCH 06/14] docs: improve the doc of Read FIT method List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Xiao Guangrong Cc: pbonzini@redhat.com, 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 On Mon, 7 Nov 2016 19:13:41 +0800 Xiao Guangrong wrote: > Improve the description and clearly document the length field >=20 > Suggested-by: Igor Mammedov > Signed-off-by: Xiao Guangrong Reviewed-by: Igor Mammedov > --- > docs/specs/acpi_nvdimm.txt | 96 +++++++++++++++++++++++-----------------= ------ > 1 file changed, 47 insertions(+), 49 deletions(-) >=20 > 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). > =20 > -QEMU NVDIMM Implemention > -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > +QEMU NVDIMM Implementation > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D > QEMU uses 4 bytes IO Port starting from 0x0a18 and a RAM-based memory pa= ge > for NVDIMM ACPI. > =20 > @@ -80,8 +80,17 @@ Memory: > emulates _DSM access and writes the output data to it. > =20 > 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 a= re > + reserved for other purposes. > + > + Reserved handles: > + 0 is reserved for nvdimm root device named NVDR. > + 0x10000 is reserved for QEMU internal DSM function calle= d 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. > =20 > -Device Handle Reservation > -------------------------- > -As we mentioned above, byte 0 ~ byte 3 in the DSM memory save NVDIMM dev= ice > -handle. The handle is completely QEMU internal thing, the values in range > -[0, 0xFFFF] indicate nvdimm device (O means nvdimm root device named NVD= R), > -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. > =20 > Input parameters: > Arg0 =E2=80=93 UUID {set to 648B9CF2-CDA1-4312-8AD9-49C4AF32BD62} > @@ -161,29 +154,34 @@ There is the function introduced by QEMU and only u= sed by QEMU internal. > Arg2 - Function Index, 0x1 > Arg3 - A package containing a buffer whose layout is as follows: > =20 > - +----------+-------------+-------------+-----------------------------= ------+ > - | 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 be= en | > - | status | 4 | 0 | updated = | > - | | | | other follows Chapter 3 in D= SM | > - | | | | Spec Rev1 = | > - +----------+-------------+-------------+-----------------------------= ------+ > - | fit data | Varies | 4 | FIT data = | > - | | | | = | > - +----------+-------------+-------------+-----------------------------= ------+ > - > - The FIT offset is maintained by the caller itself, current offset plu= gs > - 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 offse= t 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 wh= ile | > + | status | 4 | 4 | read by _FIT wasn't completed, other = | > + | | | | codes follow Chapter 3 in DSM Spec Rev= 1 | > + +----------+-----------------+---------------------------------------= ----+ > + | fit data | Varies | 8 | contains FIT data, this field is prese= nt | > + | | | | 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).