[Skiboot] [RFC v2 2/8] doc: add opal secvar documentation

[Eric Richter]

This patch contains all the relevant documentation for the secure variable
support in OPAL. This may be split and squashed with their relevant
implementations in the future, but kept separate for now.

Notably missing at the moment is the documentation for the SECBOOT PNOR
partition usage, which will be included in a future revision.

v2:
 - removed k_ prefix on all parameters
 - changed all uint64_t types to their actual intended type
 - added a new overview preamble, work in progress

Signed-off-by: Eric Richter <erichte at linux.ibm.com>
---
 doc/opal-api/opal-secvar.rst | 188 +++++++++++++++++++++++++++++++++++
 1 file changed, 188 insertions(+)
 create mode 100644 doc/opal-api/opal-secvar.rst

diff --git a/doc/opal-api/opal-secvar.rst b/doc/opal-api/opal-secvar.rst
new file mode 100644
index 00000000..382b9eb4
--- /dev/null
+++ b/doc/opal-api/opal-secvar.rst
@@ -0,0 +1,188 @@
+OPAL Secure Variables
+=====================
+
+Overview
+--------
+
+In order to support host OS secure boot on POWER systems, the platform needs
+some form of tamper-resistant persistant storage for authorized public keys.
+Furthermore, these keys must be retrieveable by the host kernel, and new
+keys must be able to be submitted.
+
+OPAL exposes an abstracted "variable" API, in which these keys can be stored
+and retrieved. At a high level, ``opal_secvar_get`` retrieves a specific
+variable corresponding to a name+vendor guid pair (see "types" below).
+``opal_secvar_get_next`` can be used to iterate through the stored
+variables. ``opal_secvar_enqueue_update`` can be used to submit a new
+variable for processing on next boot.
+
+Types
+-----
+
+This document uses the following non-standard types:
+::
+
+   char16_t - 16-bit char, in little endian ucs2
+   guid_t   - 16-byte UUID blob
+
+
+OPAL_SECVAR_GET
+===============
+::
+
+   #define OPAL_SECVAR_GET                         170
+
+``OPAL_SECVAR_GET`` call retrieves a data blob associated with the supplied
+name and vendor guid.
+
+Parameters
+----------
+::
+
+   char16_t *name
+   guid_t   *vendor
+   uint32_t *attributes
+   uint64_t *data_size
+   void     *data
+
+``name``
+   the name of the requested variable as a 16-bit char
+
+``vendor``
+   the vendor guid of the requested variable
+
+``attributes``
+   optional bitfield reference to be set by OPAL for attributes
+related to the variable data
+
+``data_size``
+   reference to the size of the ``data`` buffer. OPAL sets this if
+the buffer size is insufficient for the requested variable
+
+``data``
+   return buffer to store the data blob of the requested variable if
+a match was found. May be set to NULL to request only the size
+
+Return Values
+-------------
+
+``OPAL_SUCCESS``
+   data from the requested variable was copied successfully, or
+``data`` was set to NULL and the ``data_size`` was set to the
+requested variable's size
+
+``OPAL_PARAMETER``
+   ``name``, ``vendor`` or ``data_size`` are invalid buffers,
+contain invalid values
+
+``OPAL_EMPTY``
+   no variable with the supplied ``name`` and ``vendor`` was found
+
+``OPAL_PARTIAL``
+   the buffer size provided in ``data_size`` is too small for the
+requested variable
+
+``OPAL_UNSUPPORTED``
+   secure variable support is disabled
+
+OPAL_SECVAR_GET_NEXT
+====================
+::
+
+   #define OPAL_SECVAR_GET_NEXT                        171
+
+``OPAL_SECVAR_GET_NEXT`` returns the name and vendor guid of the next
+variable in the secure variable bank in sequence.
+
+Parameters
+----------
+::
+
+   size_t   *name_size
+   char16_t *name
+   guid_t   *vendor
+
+``name_size``
+   size of the ``name`` buffer. OPAL sets this to the size of the
+next variable in sequence
+
+``name``
+   name of the previous variable or empty. The name of the next
+variable in sequence will be copied to ``name``
+
+``vendor``
+   vendor guid of the previous variable or empty. The vendor of the
+next vendor in sequence will be copied to ``vendor``
+
+Return Values
+-------------
+
+``OPAL_SUCCESS``
+  the name and vendor of the next variable in sequence was copied
+successfully
+
+``OPAL_PARAMETER``
+  ``name`` or ``vendor`` are invalid buffers, or were not found.
+``name_size`` is an invalid value. A variable matching the
+supplied non-empty ``name`` and ``vendor`` was not found
+
+``OPAL_EMPTY``
+  end of list reached
+
+``OPAL_PARTIAL``
+  the size specified in ``name_size`` is insufficient for the next
+variable's name size
+
+``OPAL_HARDWARE``
+  secure variable support is disabled
+
+OPAL_SECVAR_ENQUEUE_UPDATE
+==========================
+::
+
+   #define OPAL_SECVAR_ENQUEUE_UPDATE                    172
+
+``OPAL_SECVAR_ENQUEUE`` call appends the supplied variable data to the
+queue for processing on next boot.
+
+Parameters
+----------
+::
+
+   char16_t *name
+   guid_t   *vendor
+   uint32_t  attributes
+   size_t    data_size
+   void     *data
+
+``name``
+   the name of the submitted variable as a 16-bit char
+
+``vendor``
+   the vendor guid of the submitted variable
+
+``attributes``
+   bitfield of attributes
+
+``data_size``
+   size of the buffer to copy from ``data``
+
+``data``
+   blob of data to be stored
+
+Return Values
+-------------
+
+``OPAL_SUCCESS``
+   the variable was appended to the update queue bank successfully
+
+``OPAL_PARAMETER``
+   ``name``, ``vendor`` or ``data`` are invalid buffers.
+``name`` is empty. ``data_size`` is an invalid value. ``data_size``
+was set to zero (potentially an unsupported deletion attempt)
+
+``OPAL_NO_MEM``
+   OPAL was unable to allocate memory for the variable
+
+``OPAL_UNSUPPORTED``
+   secure variable support is disabled
-- 
2.20.1