1 files changed, 126 insertions, 0 deletions
diff --git a/roms/skiboot/doc/opal-api/opal-nvram-read-write-7-8.rst b/roms/skiboot/doc/opal-api/opal-nvram-read-write-7-8.rst
new file mode 100644
index 000000000..54cf30a0c
--- /dev/null
+++ b/roms/skiboot/doc/opal-api/opal-nvram-read-write-7-8.rst
@@ -0,0 +1,126 @@
+.. _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
+
+   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
+----------
+::
+
+   uint64_t buffer
+   uint64_t size
+   uint64_t offset
+
+``buffer``
+   the data from nvram will be copied to ``buffer``
+
+``size``
+   the data of size ``size`` will be copied
+
+``offset``
+   the data will be copied from address equal to base ``nvram_image`` plus ``offset``
+
+Return Values
+-------------
+
+:ref:`OPAL_SUCCESS`
+  data from nvram to memory ``buffer`` copied successfully
+
+:ref:`OPAL_PARAMETER`
+  a parameter ``offset`` or ``size`` was incorrect
+
+: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
+
+   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
+----------
+::
+
+   uint64_t buffer
+   uint64_t size
+   uint64_t offset
+
+``buffer``
+   data from ``buffer`` will be copied to nvram
+
+``size``
+   the data of size ``size`` will be copied
+
+``offset``
+   the data will be copied to address which is equal to base ``nvram_image`` plus ``offset``
+
+Return Values
+-------------
+
+:ref:`OPAL_SUCCESS`
+  data from memory ``buffer`` to actual nvram_image copied successfully
+
+:ref:`OPAL_PARAMETER`
+  a parameter ``offset`` or ``size`` was incorrect
+
+: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`