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

Tue Apr 2 17:28:39 AEDT 2019

Eric Richter <erichte at linux.ibm.com> writes:
> 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.

Several thousand internet points for writing any documentation at all :)

>
> 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

An overview of the API would probably fit in well here, I think I am
getting most of the "How does this work" based on our previous
discussions rather than docs.

> @@ -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

These should have types and not just uint64_t

> +
> +``k_name``
> +   the name of the requested variable as a 16-bit char

UCS-2 or UTF-16?

> +
> +``k_vendor``
> +   the vendor guid of the requested variable

GUID should probably be defined somewhere.

> +
> +``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

is a NULL permitted? as in, finding out how big the variable is by
passing NULL for addr and getting the data size back?

> +
> +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

What about
#define OPAL_UNSUPPORTED        -7
instead?

> +
> +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
>
> _______________________________________________
> Skiboot mailing list
> Skiboot at lists.ozlabs.org
> https://lists.ozlabs.org/listinfo/skiboot
>

-- 
Stewart Smith
OPAL Architect, IBM.