[Skiboot] [RFC 2/6] 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.

Signed-off-by: Eric Richter <erichte at linux.ibm.com>
---
 doc/opal-api/opal-secvar.rst | 199 +++++++++++++++++++++++++++++++++++
 1 file changed, 199 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..fd66e5e2
--- /dev/null
+++ b/doc/opal-api/opal-secvar.rst
@@ -0,0 +1,199 @@
+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
+----------
+::
+
+   uint64_t k_name
+   uint64_t k_vendor
+   uint64_t k_attributes
+   uint64_t k_data_size
+   uint64_t k_data
+
+``k_name``
+   the name of the requested variable as a 16-bit char
+
+``k_vendor``
+   the vendor guid of the requested variable
+
+``k_attributes``
+   optional bitfield reference to be set by OPAL for attributes
+related to the variable data
+
+``k_data_size``
+   reference to the size of the ``k_data`` buffer. OPAL sets this if
+the buffer size is insufficient for the requested variable
+
+``k_data``
+   return buffer to store the data blob of the requested variable if
+a match was found
+
+Return Values
+-------------
+
+``OPAL_SUCCESS``
+   data from the requested variable was copied successfully, or
+``k_data`` was set to NULL and the ``k_data_size`` was set to the
+requested variable's size
+
+``OPAL_PARAMETER``
+   ``k_name``, ``k_vendor`` or ``k_data_size`` are invalid buffers,
+contain invalid values
+
+``OPAL_EMPTY``
+   no variable with the supplied ``k_name`` and ``k_vendor`` was found
+
+``OPAL_PARTIAL``
+   the buffer size provided in ``k_data_size`` is too small for the
+requested variable
+
+``OPAL_HARDWARE``
+   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
+----------
+::
+
+   uint64_t k_name_size
+   uint64_t k_name
+   uint64_t k_vendor
+
+``k_name_size``
+   size of the ``k_name`` buffer. OPAL sets this to the size of the
+next variable in sequence
+
+``k_name``
+   name of the previous variable or empty. The name of the next
+variable in sequence will be copied to ``k_name``
+
+``k_vendor``
+   vendor guid of the previous variable or empty. The vendor of the
+next vendor in sequence will be copied to ``k_vendor``
+
+Return Values
+-------------
+
+``OPAL_SUCCESS``
+  the name and vendor of the next variable in sequence was copied
+successfully
+
+``OPAL_PARAMETER``
+  ``k_name`` or ``k_vendor`` are invalid buffers, or were not found.
+``k_name_size`` is an invalid value. A variable matching
+the supplied non-empty ``k_name`` and ``k_vendor`` was not found
+
+``OPAL_EMPTY``
+  end of list reached
+
+``OPAL_PARTIAL``
+  the size specified in ``k_name_size`` is insufficient for the next
+variable's name size
+
+``OPAL_HARDWARE``
+  secure variable support is disabled
+
+OPAL_SECVAR_ENQUEUE
+===================
+::
+
+   #define OPAL_SECVAR_ENQUEUE                        172
+
+``OPAL_SECVAR_ENQUEUE`` call appends the supplied variable data to the
+queue for processing on next boot.
+
+Parameters
+----------
+::
+
+   uint64_t k_name
+   uint64_t k_vendor
+   uint64_t k_attributes
+   uint64_t k_data_size
+   uint64_t k_data
+
+``k_name``
+   the name of the submitted variable as a 16-bit char
+
+``k_vendor``
+   the vendor guid of the submitted variable
+
+``k_attributes``
+   bitfield of attributes
+
+``k_data_size``
+   size of the buffer to copy from ``k_data``
+
+``k_data``
+   blob of data to be stored
+
+Return Values
+-------------
+
+``OPAL_SUCCESS``
+   the variable was appended to the update queue bank successfully
+
+``OPAL_PARAMETER``
+   ``k_name``, ``k_vendor`` or ``k_data`` are invalid buffers.
+``k_name`` is empty. ``k_data_size`` is an invalid value.
+
+``OPAL_NO_MEM``
+   OPAL was unable to allocate memory for the variable
+
+``OPAL_UNSUPPORTED``
+   ``k_data_size`` was set to zero, implying an empty ``k_data`` buffer
+(may be used for variable deletion in the future)
+
+``OPAL_HARDWARE``
+   secure variable support is disabled
+
+OPAL_SECVAR_INFO
+================
+::
+
+   #define OPAL_SECVAR_INFO                        173
+
+``OPAL_SECVAR_INFO`` returns size information about the variable
+storage. Not currently implemented.
+
+Parameters
+----------
+::
+
+   uint64_t k_attributes
+   uint64_t k_storage_space
+   uint64_t k_remaining_space
+   uint64_t k_max_variable_size
+
+``k_attributes``
+   TODO
+
+``k_storage_space``
+   maximum storage space in bytes
+
+``k_remaining_space``
+   remaining storage space in bytes
+
+``k_max_variable_size``
+   maximum acceptable size for a data blob
+
+Return Values
+-------------
+
+``OPAL_UNSUPPORTED``
+  Runtime service is currently a stub, not currently implemented.
-- 
2.17.2