[Skiboot] [PATCH 034/110] doc: Flesh out NVRAM docs

[Stewart Smith]

Reference LoPAPR as where all the requirements come from, and document
what the device tree looks like.

Signed-off-by: Stewart Smith <stewart at linux.ibm.com>
---
 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`
-- 
2.21.0