From patchwork Mon Nov 7 11:13:41 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Xiao Guangrong X-Patchwork-Id: 9414871 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id D13456022E for ; Mon, 7 Nov 2016 11:39:12 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id C1E6A28CD1 for ; Mon, 7 Nov 2016 11:39:12 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id A95A128CD4; Mon, 7 Nov 2016 11:39:12 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=unavailable version=3.3.1 Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 1DD6528CD1 for ; Mon, 7 Nov 2016 11:39:02 +0000 (UTC) Received: from localhost ([::1]:53169 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c3iGT-0006YS-BE for patchwork-qemu-devel@patchwork.kernel.org; Mon, 07 Nov 2016 06:39:01 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:44644) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c3i7A-0007M1-Au for qemu-devel@nongnu.org; Mon, 07 Nov 2016 06:29:25 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1c3i76-0001Ro-1K for qemu-devel@nongnu.org; Mon, 07 Nov 2016 06:29:24 -0500 Received: from mga11.intel.com ([192.55.52.93]:55637) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1c3i75-0001Jt-PZ for qemu-devel@nongnu.org; Mon, 07 Nov 2016 06:29:19 -0500 Received: from fmsmga001.fm.intel.com ([10.253.24.23]) by fmsmga102.fm.intel.com with ESMTP; 07 Nov 2016 03:29:19 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos; i="5.31,606,1473145200"; d="scan'208"; a="1065006891" Received: from xiaoreal1.sh.intel.com (HELO xiaoreal1.sh.intel.com.sh.intel.com) ([10.239.48.133]) by fmsmga001.fm.intel.com with ESMTP; 07 Nov 2016 03:29:16 -0800 From: Xiao Guangrong To: pbonzini@redhat.com, imammedo@redhat.com Date: Mon, 7 Nov 2016 19:13:41 +0800 Message-Id: <1478517229-140028-7-git-send-email-guangrong.xiao@linux.intel.com> X-Mailer: git-send-email 1.8.3.1 In-Reply-To: <1478517229-140028-1-git-send-email-guangrong.xiao@linux.intel.com> References: <1478517229-140028-1-git-send-email-guangrong.xiao@linux.intel.com> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 192.55.52.93 Subject: [Qemu-devel] [PATCH 06/14] docs: improve the doc of Read FIT method X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Xiao Guangrong , ehabkost@redhat.com, kvm@vger.kernel.org, mst@redhat.com, gleb@kernel.org, mtosatti@redhat.com, qemu-devel@nongnu.org, stefanha@redhat.com, dan.j.williams@intel.com, rth@twiddle.net Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" X-Virus-Scanned: ClamAV using ClamSMTP Improve the description and clearly document the length field Suggested-by: Igor Mammedov Signed-off-by: Xiao Guangrong Reviewed-by: Stefan Hajnoczi Reviewed-by: Igor Mammedov --- 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).