[Skiboot] [PATCH 045/110] doc: Combine and extend OPAL_SENSOR_READ[_U64] docs

[Stewart Smith]

Signed-off-by: Stewart Smith <stewart at linux.ibm.com>
---
 doc/opal-api/opal-sensor-read-88.rst      | 71 +++++++++++++++--------
 doc/opal-api/opal-sensor-read-u64-162.rst | 16 -----
 2 files changed, 47 insertions(+), 40 deletions(-)
 delete mode 100644 doc/opal-api/opal-sensor-read-u64-162.rst

diff --git a/doc/opal-api/opal-sensor-read-88.rst b/doc/opal-api/opal-sensor-read-88.rst
index 6bfc41492bda..793dcfdf6f5d 100644
--- a/doc/opal-api/opal-sensor-read-88.rst
+++ b/doc/opal-api/opal-sensor-read-88.rst
@@ -1,8 +1,16 @@
+.. _OPAL_SENSOR_READ:
+
 OPAL_SENSOR_READ
 ================
 
+.. code-block:: c
+
+   #define OPAL_SENSOR_READ			88
+
+   int64_t opal_sensor_read(uint32_t sensor_hndl, int token, uint32_t *sensor_data);
+
 The OPAL sensor call reads a sensor data using a unique handler to
-identity the targeted sensor. The `sensor_handler` is provided
+identity the targeted sensor. The `sensor_handle` is provided
 via the device tree and is opaque to the OS (although we currently
 do use an encoding scheme).
 
@@ -14,46 +22,61 @@ the completion of the request.
 The OPAL API doesn't enforce alimit on the number of sensor calls that can
 be in flight.
 
+Internally, :ref:`OPAL_SENSOR_READ` is implemented as a wrapper around
+:ref:`OPAL_SENSOR_READ_U64`. Any code targeting processor generations prior
+to POWER9 will need to use :ref:`OPAL_CHECK_TOKEN` to ensure :ref:`OPAL_SENSOR_READ_U64`
+is present and gracefully fall back to :ref:`OPAL_SENSOR_READ` if it is not.
 
 Parameters
 ----------
 ::
 
-	uint32_t sensor_handler
+	uint32_t sensor_handle
 	int	 token
 	uint32_t *sensor_data
 
 
 Return values
 -------------
-OPAL_SUCCESS
+:ref:`OPAL_SUCCESS`
   Success!
-
-OPAL_PARAMETER
-  invalid sensor handler
-
-OPAL_UNSUPPORTED
+:ref:`OPAL_PARAMETER`
+  invalid sensor handle
+:ref:`OPAL_UNSUPPORTED`
   platform does not support reading sensors.
-
-Some sensors may have to be read asynchronously (e.g. because OPAL must
-communicate with a service processor). One example is sensors provided
-by the FSP on IBM FSP systems.
-
-OPAL_ASYNC_COMPLETION
+:ref:`OPAL_ASYNC_COMPLETION`
   a request was sent and an async completion will
   be triggered with the @token argument
-
-OPAL_PARTIAL
+:ref:`OPAL_PARTIAL`
   the request completed but the data returned is invalid
-
-OPAL_BUSY_EVENT
+:ref:`OPAL_BUSY_EVENT`
   a previous request is still pending
-
-OPAL_NO_MEM
+:ref:`OPAL_NO_MEM`
   allocation failed
-
-OPAL_INTERNAL_ERROR
+:ref:`OPAL_INTERNAL_ERROR`
   communication failure with the FSP
-
-OPAL_HARDWARE
+:ref:`OPAL_HARDWARE`
   FSP is not available
+
+.. _OPAL_SENSOR_READ_U64:
+
+OPAL_SENSOR_READ_U64
+====================
+
+.. code-block:: c
+
+   #define OPAL_SENSOR_READ_U64			162
+
+   s64 opal_sensor_read_u64(u32 sensor_hndl, int token, u64 *sensor_data);
+
+The OPAL sensor call to read sensor data of type u64. Unlike
+opal_sensor_read which reads upto u32 this call can be used to
+read values of sensors upto 64bits. The calling conventions and
+return values are same as :ref:`OPAL_SENSOR_READ`.
+
+All sensors can be read through the :ref:`OPAL_SENSOR_READ_U64` call that
+can be read using the :ref:`OPAL_SENSOR_READ` call. Internally,
+:ref:`OPAL_SENSOR_READ` is a wrapper around :ref:`OPAL_SENSOR_READ_U64`.
+Any code targeting processor generations prior to POWER9 will need to use
+:ref:`OPAL_CHECK_TOKEN` to ensure :ref:`OPAL_SENSOR_READ_U64`
+is present and gracefully fall back to :ref:`OPAL_SENSOR_READ` if it is not.
diff --git a/doc/opal-api/opal-sensor-read-u64-162.rst b/doc/opal-api/opal-sensor-read-u64-162.rst
deleted file mode 100644
index b75bcbc26c62..000000000000
--- a/doc/opal-api/opal-sensor-read-u64-162.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-OPAL_SENSOR_READ_U64
-====================
-
-The OPAL sensor call to read sensor data of type u64. Unlike
-opal_sensor_read which reads upto u32 this call can be used to
-read values of sensors upto 64bits. The calling conventions and
-return values are same as OPAL_SENSOR_READ.
-(ref: doc/opal-api/opal-sensor-read-88.rst)
-
-Parameters
-----------
-::
-
-	u32 sensor_handler
-	int	 token
-	u64 *sensor_data
-- 
2.21.0