doc: Document OPAL_GET_PARAM and OPAL_SET_PARAM

Signed-off-by: Stewart Smith <stewart@linux.ibm.com>

2 files changed, 122 insertions, 0 deletions

diff --git a/doc/device-tree/ibm,opal/sysparams.rst b/doc/device-tree/ibm,opal/sysparams.rst
new file mode 100644
index 0000000..8b74650
--- /dev/null
+++ b/doc/device-tree/ibm,opal/sysparams.rst
@@ -0,0 +1,38 @@
+.. _device-tree/ibm,opal/sysparams:
+
+sysparams
+=========
+
+.. code-block:: c
+
+   /* System parameter permission */
+   enum OpalSysparamPerm {
+	OPAL_SYSPARAM_READ  = 0x1,
+	OPAL_SYSPARAM_WRITE = 0x2,
+	OPAL_SYSPARAM_RW    = (OPAL_SYSPARAM_READ | OPAL_SYSPARAM_WRITE),
+   };
+
+
+.. code-block:: dts
+
+   sysparams {
+		compatible = "ibm,opal-sysparams";
+                param-id = <0xf0000001 0xf0000003 0xf0000012 0xf0000016 0xf000001d 0xf0000023 0xf0000024 0xf0000025 0xf0000026 0xf0000027>;
+                param-name = "surveillance", "hmc-management", "cupd-policy", "plat-hmc-managed", "fw-license-policy", "world-wide-port-num", "default-boot-device", "next-boot-device", "console-select", "boot-device-path";
+                param-perm = [03 01 03 03 03 02 03 03 03 03];
+                phandle = <0x10000032>;
+                param-len = <0x4 0x4 0x4 0x4 0x4 0xc 0x1 0x1 0x1 0x30>;
+                linux,phandle = <0x10000032>;
+   };
+
+Device tree node for system parameters accessible through the
+:ref:`opal-sysparams` calls :ref:`OPAL_GET_PARAM` and :ref:`OPAL_SET_PARAM`.
+
+While many systems and platforms will support parameters and configuration via
+either nvram or over IPMI, some platforms may have parameters that need to be
+set a different way.
+
+Some parameters may be set Read Only, so the `param-perm` property indicates
+permissions.
+
+Currently, this is only something that exists on FSP based systems.
diff --git a/doc/opal-api/opal-param-89-90.rst b/doc/opal-api/opal-param-89-90.rst
new file mode 100644
index 0000000..1d1ceda
--- /dev/null
+++ b/doc/opal-api/opal-param-89-90.rst
@@ -0,0 +1,84 @@
+.. _opal-sysparams:
+
+=========================
+Get/Set System Parameters
+=========================
+
+The usual way for setting system parameters is via IPMI for things controlled
+by the service processor, or through NVRAM for things controlled by host
+firmware. However, some platforms may have other options not easily (or
+possible to be) exposed over IPMI. These OPAL calls will read (and write)
+these parameters.
+
+The list of parameters is set at boot time, and is represented in the device
+tree (see :ref:`device-tree/ibm,opal/sysparams` for details).
+
+Currently only implemented on FSP based systems.
+
+.. _OPAL_GET_PARAM:
+
+OPAL_GET_PARAM
+==============
+
+.. code-block:: c
+
+   #define OPAL_GET_PARAM				89
+
+   int64_t fsp_opal_get_param(uint64_t async_token, uint32_t param_id,
+                              uint64_t buffer, uint64_t length);
+
+Get the current setting of `param_id`. This is an asynchronous call as OPAL may
+need to communicate with a service processor. The `param_id` and `length` are
+described in the device tree for each parameter (see
+:ref:`device-tree/ibm,opal/sysparams` for details).
+
+Returns
+-------
+:ref:`OPAL_HARDWARE`
+     Hardware issue prevents retreiving parameter. e.g. FSP is offline or
+     absent.
+:ref:`OPAL_PARAMETER`
+     Invalid `param_id`
+:ref:`OPAL_PERMISSION`
+     Not allowed to read parameter.
+:ref:`OPAL_NO_MEM`
+     Not enough free memory in OPAL to process request.
+:ref:`OPAL_INTERNAL_ERROR`
+     Other internal OPAL error
+:ref:`OPAL_ASYNC_COMPLETION`
+     Request is submitted.
+
+.. _OPAL_SET_PARAM:
+
+OPAL_SET_PARAM
+==============
+
+.. code-block:: c
+
+   #define OPAL_SET_PARAM				90
+
+   int64_t fsp_opal_set_param(uint64_t async_token, uint32_t param_id,
+                              uint64_t buffer, uint64_t length);
+
+
+Write a new setting for `param_id`. This is an asynchronous call as OPAL may
+need to communicate with a service processor. The `param_id` and `length` are
+described in the device tree for each parameter (see
+:ref:`device-tree/ibm,opal/sysparams` for details).
+
+
+Returns
+-------
+:ref:`OPAL_HARDWARE`
+     Hardware issue prevents retreiving parameter. e.g. FSP is offline or
+     absent.
+:ref:`OPAL_PARAMETER`
+     Invalid `param_id`
+:ref:`OPAL_PERMISSION`
+     Not allowed to write parameter.
+:ref:`OPAL_NO_MEM`
+     Not enough free memory in OPAL to process request.
+:ref:`OPAL_INTERNAL_ERROR`
+     Other internal OPAL error
+:ref:`OPAL_ASYNC_COMPLETION`
+     Request is submitted.