doc: Clean up OPAL power shift ratio docs
.. _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
