psr: occ: Add support to change power-shifting-ratio

Add support to set the CPU-GPU power shifting ratio which is used by
the OCC power capping algorithm. PSR value of 100 takes all power away
from CPU first and a PSR value of 0 caps GPU first.

Documentation enhanced by Stewart Smith.

Signed-off-by: Shilpasri G Bhat <shilpa.bhat@linux.vnet.ibm.com>
Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>

2 files changed, 132 insertions, 0 deletions

diff --git a/doc/device-tree/ibm,opal/power-mgt/psr.rst b/doc/device-tree/ibm,opal/power-mgt/psr.rst
new file mode 100644
index 0000000..edae8da
--- /dev/null
+++ b/doc/device-tree/ibm,opal/power-mgt/psr.rst
@@ -0,0 +1,53 @@
+power-mgt/psr
+------------------
+
+Some systems allow modification of how power consumption throttling
+is balanced between entities in a system. A typical one may be how the power
+management complex should balance throttling CPU versus the GPU. An OPAL
+call can be used to set these ratios, which are described in the device
+tree.
+
+In the future, there may be more available settings than just CPU
+versus GPU.
+
+Each child node in the "psr" node represents a configurable psr
+sensor.
+
+For example : ::
+        cpu-to-gpu@1
+
+The compatible property is set to "ibm,opal-power-shift-ratio".
+
+Each child node has below properties:
+
+`handle`
+  Handle to indicate the type of psr
+
+`label`
+  Name of the psr sensor
+
+The format of the handle is internal, and ``not`` ABI, although
+currently it uses the following encoding ::
+
+	| Class |Reserved|  RID	| Type |
+	|-------|--------|------|------|
+
+.. code-block:: dts
+
+   power-mgt {
+     psr {
+        compatible = "ibm,opal-power-shift-ratio"
+
+        cpu-to-gpu@0 {
+                name = "cpu-to-gpu"
+                handle = <0x00000000>
+                label = "cpu_to_gpu_0"
+        };
+
+        cpu-to-gpu@1 {
+                name = "cpu-to-gpu"
+                handle = <0x00000100>
+                label = "cpu_to_gpu_1"
+        };
+     };
+    };
diff --git a/doc/opal-api/opal-power-shift-ratio.rst b/doc/opal-api/opal-power-shift-ratio.rst
new file mode 100644
index 0000000..7f1f71f
--- /dev/null
+++ b/doc/opal-api/opal-power-shift-ratio.rst
@@ -0,0 +1,79 @@
+.. _opal-psr:
+
+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.
+
+The call can be asynchronus, where the token parameter is used to wait
+for the completion.
+
+Parameters
+----------
+::
+        u32 handle
+        int token
+        u32 *ratio
+
+Returns
+-------
+OPAL_SUCCESS
+  Success
+
+OPAL_PARAMETER
+  Invalid ratio pointer
+
+OPAL_UNSUPPORTED
+  No support for reading psr
+
+OPAL_HARDWARE
+  Unable to procced due to the current hardware state
+
+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 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
+completion.
+
+Parameters
+----------
+::
+        u32 handle
+        int token
+        u32 ratio
+
+Returns
+-------
+OPAL_SUCCESS
+  Success
+
+OPAL_PARAMETER
+  Invalid ratio requested
+
+OPAL_UNSUPPORTED
+  No support for changing the ratio
+
+OPAL_PERMISSION
+  Hardware cannot take the request
+
+OPAL_ASYNC_COMPLETION
+  Request was sent and an async completion message will be sent with
+  token and status of the request.
+
+OPAL_HARDWARE
+  Unable to procced due to the current hardware state
+
+OPAL_BUSY
+  Previous request in progress
+
+OPAL_INTERNAL_ERROR
+  Error in request response
+
+OPAL_TIMEOUT
+  Timeout in request completion