[Skiboot] [PATCH 046/110] doc: Clean up OPAL power shift ratio docs

[Stewart Smith]

Signed-off-by: Stewart Smith <stewart at linux.ibm.com>
---
 doc/opal-api/opal-power-shift-ratio.rst | 60 +++++++++++++------------
 1 file changed, 32 insertions(+), 28 deletions(-)

diff --git a/doc/opal-api/opal-power-shift-ratio.rst b/doc/opal-api/opal-power-shift-ratio.rst
index b9c7854532dd..4437b55bb730 100644
--- a/doc/opal-api/opal-power-shift-ratio.rst
+++ b/doc/opal-api/opal-power-shift-ratio.rst
@@ -1,7 +1,19 @@
 .. _opal-psr:
 
+======================
+OPAL Power Shift Ratio
+======================
+
+Sometimes power management firmware needs to throttle power availability
+to system components in order to keep within power cap or thermal limits.
+It's possible to set a preference as to what trade-offs power management
+firmware will make. For example, certain workloads may heavily prefer
+throttling CPU over GPUs or vice-versa.
+
+.. _OPAL_GET_POWER_SHIFT_RATIO:
+
 OPAL_GET_POWER_SHIFT_RATIO
-==============================
+==========================
 OPAL call to read the power-shifting-ratio using a handle to identify
 the type (e.g CPU vs. GPU, CPU vs. MEM) which is exported via
 device-tree.
@@ -21,24 +33,23 @@ u32 \*ratio
 
 Returns
 -------
-OPAL_SUCCESS
-  Success
 
-OPAL_PARAMETER
+:ref:`OPAL_SUCCESS`
+  Success
+:ref:`OPAL_PARAMETER`
   Invalid ratio pointer
-
-OPAL_UNSUPPORTED
+:ref:`OPAL_UNSUPPORTED`
   No support for reading psr
-
-OPAL_HARDWARE
+:ref:`OPAL_HARDWARE`
   Unable to procced due to the current hardware state
-
-OPAL_ASYNC_COMPLETION
+:ref:`OPAL_ASYNC_COMPLETION`
   Request was sent and an async completion message will be sent with
   token and status of the request.
 
+.. _OPAL_SET_POWER_SHIFT_RATIO:
+
 OPAL_SET_POWER_SHIFT_RATIO
-==============================
+==========================
 OPAL call to set power-shifting-ratio using a handle to identify
 the type of PSR which is exported in device-tree. This call can be
 asynchronus where the token parameter is used to wait for the
@@ -56,30 +67,23 @@ u32 ratio
 
 Returns
 -------
-OPAL_SUCCESS
-  Success
 
-OPAL_PARAMETER
+:ref:`OPAL_SUCCESS`
+  Success
+:ref:`OPAL_PARAMETER`
   Invalid ratio requested
-
-OPAL_UNSUPPORTED
+:ref:`OPAL_UNSUPPORTED`
   No support for changing the ratio
-
-OPAL_PERMISSION
+:ref:`OPAL_PERMISSION`
   Hardware cannot take the request
-
-OPAL_ASYNC_COMPLETION
+:ref:`OPAL_ASYNC_COMPLETION`
   Request was sent and an async completion message will be sent with
   token and status of the request.
-
-OPAL_HARDWARE
+:ref:`OPAL_HARDWARE`
   Unable to procced due to the current hardware state
-
-OPAL_BUSY
+:ref:`OPAL_BUSY`
   Previous request in progress
-
-OPAL_INTERNAL_ERROR
+:ref:`OPAL_INTERNAL_ERROR`
   Error in request response
-
-OPAL_TIMEOUT
+:ref:`OPAL_TIMEOUT`
   Timeout in request completion
-- 
2.21.0