From patchwork Fri May 31 06:12:35 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stewart Smith X-Patchwork-Id: 1108081 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.ozlabs.org (lists.ozlabs.org [203.11.71.2]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 45FZBZ197tz9sDX for ; Fri, 31 May 2019 16:23:02 +1000 (AEST) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=linux.ibm.com Received: from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) by lists.ozlabs.org (Postfix) with ESMTP id 45FZBZ0C4jzDqcL for ; Fri, 31 May 2019 16:23:02 +1000 (AEST) X-Original-To: skiboot@lists.ozlabs.org Delivered-To: skiboot@lists.ozlabs.org Authentication-Results: lists.ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=linux.ibm.com (client-ip=148.163.158.5; helo=mx0a-001b2d01.pphosted.com; envelope-from=stewart@linux.ibm.com; receiver=) Authentication-Results: lists.ozlabs.org; dmarc=none (p=none dis=none) header.from=linux.ibm.com Received: from mx0a-001b2d01.pphosted.com (mx0b-001b2d01.pphosted.com [148.163.158.5]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by lists.ozlabs.org (Postfix) with ESMTPS id 45FZ0K4NKgzDqYM for ; Fri, 31 May 2019 16:14:09 +1000 (AEST) Received: from pps.filterd (m0098416.ppops.net [127.0.0.1]) by mx0b-001b2d01.pphosted.com (8.16.0.27/8.16.0.27) with SMTP id x4V643V1019014 for ; Fri, 31 May 2019 02:14:06 -0400 Received: from e11.ny.us.ibm.com (e11.ny.us.ibm.com [129.33.205.201]) by mx0b-001b2d01.pphosted.com with ESMTP id 2stty1pner-1 (version=TLSv1.2 cipher=AES256-GCM-SHA384 bits=256 verify=NOT) for ; Fri, 31 May 2019 02:14:06 -0400 Received: from localhost by e11.ny.us.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Fri, 31 May 2019 07:14:05 +0100 Received: from b01cxnp22036.gho.pok.ibm.com (9.57.198.26) by e11.ny.us.ibm.com (146.89.104.198) with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted; (version=TLSv1/SSLv3 cipher=AES256-GCM-SHA384 bits=256/256) Fri, 31 May 2019 07:14:04 +0100 Received: from b01ledav003.gho.pok.ibm.com (b01ledav003.gho.pok.ibm.com [9.57.199.108]) by b01cxnp22036.gho.pok.ibm.com (8.14.9/8.14.9/NCO v10.0) with ESMTP id x4V6E3QP31982048 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Fri, 31 May 2019 06:14:03 GMT Received: from b01ledav003.gho.pok.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id 3ECB4B2065 for ; Fri, 31 May 2019 06:14:03 +0000 (GMT) Received: from b01ledav003.gho.pok.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id B8A67B206A for ; Fri, 31 May 2019 06:14:02 +0000 (GMT) Received: from birb.localdomain (unknown [9.185.142.91]) by b01ledav003.gho.pok.ibm.com (Postfix) with ESMTP for ; Fri, 31 May 2019 06:14:02 +0000 (GMT) Received: by birb.localdomain (Postfix, from userid 1000) id 02625503F6F; Fri, 31 May 2019 16:13:57 +1000 (AEST) From: Stewart Smith To: skiboot@lists.ozlabs.org Date: Fri, 31 May 2019 16:12:35 +1000 X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190531061351.22973-1-stewart@linux.ibm.com> References: <20190531061351.22973-1-stewart@linux.ibm.com> MIME-Version: 1.0 X-TM-AS-GCONF: 00 x-cbid: 19053106-2213-0000-0000-0000039856AD X-IBM-SpamModules-Scores: X-IBM-SpamModules-Versions: BY=3.00011189; HX=3.00000242; KW=3.00000007; PH=3.00000004; SC=3.00000286; SDB=6.01211088; UDB=6.00636341; IPR=6.00992124; MB=3.00027126; MTD=3.00000008; XFM=3.00000015; UTC=2019-05-31 06:14:04 X-IBM-AV-DETECTION: SAVI=unused REMOTE=unused XFE=unused x-cbparentid: 19053106-2214-0000-0000-00005EA4D93B Message-Id: <20190531061351.22973-35-stewart@linux.ibm.com> X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:, , definitions=2019-05-31_03:, , signatures=0 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 priorityscore=1501 malwarescore=0 suspectscore=1 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=892 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1905310040 Subject: [Skiboot] [PATCH 034/110] doc: Flesh out NVRAM docs X-BeenThere: skiboot@lists.ozlabs.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Mailing list for skiboot development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: skiboot-bounces+incoming=patchwork.ozlabs.org@lists.ozlabs.org Sender: "Skiboot" Reference LoPAPR as where all the requirements come from, and document what the device tree looks like. Signed-off-by: Stewart Smith --- doc/device-tree/ibm,opal/nvram.rst | 13 ++++ doc/opal-api/opal-nvram-read-write-7-8.rst | 72 ++++++++++++++++++---- 2 files changed, 74 insertions(+), 11 deletions(-) create mode 100644 doc/device-tree/ibm,opal/nvram.rst diff --git a/doc/device-tree/ibm,opal/nvram.rst b/doc/device-tree/ibm,opal/nvram.rst new file mode 100644 index 000000000000..e1b432f428db --- /dev/null +++ b/doc/device-tree/ibm,opal/nvram.rst @@ -0,0 +1,13 @@ +.. _device-tree/ibm,opal/nvram: + +nvram Device Tree Node +====================== + +.. code-block:: dts + + nvram { + compatible = "ibm,opal-nvram"; + #bytes = <0x90000>; + }; + +Indicates support (and size of) the :ref:`nvram` facility. diff --git a/doc/opal-api/opal-nvram-read-write-7-8.rst b/doc/opal-api/opal-nvram-read-write-7-8.rst index fe06886bdf9c..54cf30a0cee6 100644 --- a/doc/opal-api/opal-nvram-read-write-7-8.rst +++ b/doc/opal-api/opal-nvram-read-write-7-8.rst @@ -1,13 +1,52 @@ +.. _nvram: + +========== +OPAL NVRAM +========== + +The NVRAM requirements for OPAL systems is derived from LoPAPR, and all +requirements listed in it apply to OPAL with some exceptions. Note that +Section 8.4.1.1.3 "OF Configuration Variables" does NOT apply to OPAL, +neither does 8.4.1.2 "DASD Spin-up Control". Not that the RTAS calls of +`nvram-fetch` and `nvram-store` are roughly equivalent to the +:ref:`OPAL_READ_NVRAM` and :ref:`OPAL_WRITE_NVRAM` calls. + +LoPAPR has a minimum requirement of 8KB of Non-Volatile Memory. While this +requirement carries over, it's important to note that historically all OPAL +systems have had roughly 500kb of NVRAM. + +See :ref:`device-tree/ibm,opal/nvram` for details on how NVRAM is represented +in the device tree. It's fairly simple, it looks like this: + +.. code-block:: dts + + nvram { + compatible = "ibm,opal-nvram"; + #bytes = <0x90000>; + }; + + +.. _OPAL_READ_NVRAM: + OPAL_READ_NVRAM =============== -:: + +.. code-block:: c #define OPAL_READ_NVRAM 7 -``OPAL_READ_NVRAM`` call requests OPAL to read the data from system NVRAM + int64_t opal_read_nvram(uint64_t buffer, uint64_t size, uint64_t offset); + +:ref:`OPAL_READ_NVRAM` call requests OPAL to read the data from system NVRAM memory into a memory buffer. The data at ``offset`` from nvram_image will be copied to memory ``buffer`` of size ``size``. +This is a *synchronous* OPAL call, as OPAL will typically read the content of +NVRAM from its storage (typically flash) during boot, so the call duration +should be along the lines of a ``memcpy()`` operation rather than reading +from storage. + + Parameters ---------- :: @@ -28,23 +67,28 @@ Parameters Return Values ------------- -``OPAL_SUCCESS`` +:ref:`OPAL_SUCCESS` data from nvram to memory ``buffer`` copied successfully -``OPAL_PARAMETER`` +:ref:`OPAL_PARAMETER` a parameter ``offset`` or ``size`` was incorrect -``OPAL_HARDWARE`` +:ref:`OPAL_HARDWARE` either nvram is not initialized or permanent error related to nvram hardware. +.. _OPAL_WRITE_NVRAM: + OPAL_WRITE_NVRAM ================ -:: + +.. code-block:: c #define OPAL_WRITE_NVRAM 8 -``OPAL_WRITE_NVRAM`` call requests OPAL to write the data to actual system NVRAM memory - from memory ``buffer`` at ``offset``, of size ``size`` + int64_t opal_write_nvram(uint64_t buffer, uint64_t size, uint64_t offset); + +:ref:`OPAL_WRITE_NVRAM` call requests OPAL to write the data to actual system NVRAM memory +from memory ``buffer`` at ``offset``, of size ``size`` Parameters ---------- @@ -66,11 +110,17 @@ Parameters Return Values ------------- -``OPAL_SUCCESS`` +:ref:`OPAL_SUCCESS` data from memory ``buffer`` to actual nvram_image copied successfully -``OPAL_PARAMETER`` +:ref:`OPAL_PARAMETER` a parameter ``offset`` or ``size`` was incorrect -``OPAL_HARDWARE`` +:ref:`OPAL_HARDWARE` either nvram is not initialized or permanent error related to nvram hardware. + +:ref:`OPAL_BUSY` + OPAL is currently busy, retry the :ref:`OPAL_WRITE_NVRAM` call. + +:ref:`OPAL_BUSY_EVENT` + OPAL is currently busy, call :ref:`OPAL_POLL_EVENTS` and then retry :ref:`OPAL_WRITE_NVRAM`