powercap: occ: Add a generic powercap framework

This patch adds a generic powercap framework and exports OCC powercap
sensors using which system powercap can be set inband through OPAL-OCC
command-response interface.

Documentation for powercap 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, 144 insertions, 0 deletions

diff --git a/doc/device-tree/ibm,opal/power-mgt/powercap.rst b/doc/device-tree/ibm,opal/power-mgt/powercap.rst
new file mode 100644
index 0000000..e47caa4
--- /dev/null
+++ b/doc/device-tree/ibm,opal/power-mgt/powercap.rst
@@ -0,0 +1,48 @@
+power-mgt/powercap
+------------------
+
+The powercap sensors are populated in this node. Each child node in
+the "powercap" node represents a power-cappable component.
+
+For example : ::
+        system-powercap/
+
+The OPAL_GET_POWERCAP and OPAL_SET_POWERCAP calls take a handle for
+what powercap property to get/set which is defined in the child node.
+
+The compatible property for the linux driver which will be
+"ibm,opal-powercap"
+
+Each child node has below properties:
+
+`powercap-current`
+  Handle to indicate the current powercap
+
+`powercap-min`
+  Minimum possible powercap
+
+`powercap-max`
+  Maximum possible powercap
+
+Powercap handle uses the following encoding: ::
+
+        | Class |    Reserved   | Attribute |
+        |-------|---------------|-----------|
+
+Note: The format of the powercap handle is ``NOT`` ABI and may change in
+the future.
+
+.. code-block:: dts
+
+   power-mgt {
+     powercap {
+        compatible = "ibm,opal-powercap";
+
+        system-powercap {
+                name = "system-powercap"
+                powercap-current = <0x00000002>
+                powercap-min = <0x00000000>
+                powercap-max = <0x00000001>
+        };
+     };
+    }
diff --git a/doc/opal-api/opal-powercap.rst b/doc/opal-api/opal-powercap.rst
new file mode 100644
index 0000000..00f6866
--- /dev/null
+++ b/doc/opal-api/opal-powercap.rst
@@ -0,0 +1,96 @@
+.. _opal-powercap:
+
+OPAL_GET_POWERCAP
+==================
+The OPAL_GET_POWERCAP call retreives current information on the power
+cap.
+
+For each entity that can be power capped, the device tree
+binding indicates what handle should be passed for each of the power cap
+properties (minimum possible, maximum possible, current powercap).
+
+The current power cap must be between the minimium possible and maximum
+possible power cap. The minimum and maximum values are dynamic to allow
+for them possibly being changed by other factors or entities
+(e.g. service processor).
+
+The call can be asynchronus, where the token parameter is used to wait
+for the completion.
+
+Parameters
+----------
+::
+        u32 handle
+        int token
+        u32 *pcap
+
+Returns
+-------
+OPAL_SUCCESS
+  Success
+
+OPAL_PARAMETER
+  Invalid pcap pointer
+
+OPAL_UNSUPPORTED
+  No support for reading powercap sensor
+
+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_POWERCAP
+============================
+The OPAL_SET_POWERCAP call sets a power cap.
+
+For each entity that can be power capped, the device tree
+binding indicates what handle should be passed for each of the power cap
+properties (minimum possible, maximum possible, current powercap).
+
+The current power cap must be between the minimium possible and maximum
+possible power cap.
+
+You cannot currently set the minimum or maximum power cap, and thus
+OPAL_PERMISSION will be returned if it is attempted to set. In the
+future, this may change - but for now, the correct behaviour for an
+Operating System is to not attempt to set them.
+
+Parameters
+----------
+::
+        u32 handle
+        int token
+        u32 pcap
+
+Returns
+-------
+OPAL_SUCCESS
+  Success
+
+OPAL_PARAMETER
+  Invalid powercap requested beyond powercap limits
+
+OPAL_UNSUPPORTED
+  No support for changing the powercap
+
+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