dts: add device tree documentation

Let's document what has been done so far for DTS sensors in the device
tree under node ibm,opal/sensors/

Signed-off-by: Cédric Le Goater <clg@fr.ibm.com>
Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>

1 files changed, 67 insertions, 0 deletions

diff --git a/doc/device-tree/ibm,opal/sensors.txt b/doc/device-tree/ibm,opal/sensors.txt
new file mode 100644
index 0000000..81aeff8
--- /dev/null
+++ b/doc/device-tree/ibm,opal/sensors.txt
@@ -0,0 +1,67 @@
+ibm,opal/sensors/ device tree nodes
+--------------------------------------
+
+All sensors of a POWER8 system are made available to the OS in the
+ibm,opal/sensors/ directory. Each sensor is identified with a node
+which name follows this pattern :
+
+	<resource class name>@<resource identifier>/
+
+For example :
+
+	core-temp@20/
+
+Each node has a minimum set of properties describing the sensor :
+
+  - a "compatible" property which should be "ibm,opal-sensor"
+
+  - a "sensor-type" property, which can be "temp", "fan", "power".
+    More will be added when new resources are supported. This type
+    is used "as is" by the Linux driver to map sensors in the sysfs
+    interface of the hwmon framework of Linux.
+
+  - a "sensor-data" property giving a unique handler for the
+    OPAL_SENSOR_READ call to be used by Linux to get the value of
+    a sensor attribute. A sensor handler has the following encoding :
+
+		|  Attr. |  Res.  |   Resource     |
+		| Number | Class  |      Id        |
+		|--------|--------|----------------|
+
+  - a "sensor-status" property giving the state of the sensor. The
+    status bits have the slightly meanings depending on the resource
+    type but testing against 0x6 should raise an alarm.
+
+  - an optional "label" property
+
+
+Each node can have some extra properties depending on the resource
+they represent. See the tree below for more information.
+
+ibm,opal/sensors/ {
+
+	/*
+	 * Core temperatures (DTS) nodes.
+	 *
+	 * We use the PIR of the core as a resource identifier.
+	 */
+	core-temp@20 {
+		compatible = "ibm,opal-sensor";
+		name = "core-temp";
+		sensor-type = "temp";
+
+		/* Status bits :
+		 *
+		 * 0x0003	FATAL
+		 * 0x0002	CRITICAL
+		 * 0x0001	WARNING
+		 */
+		sensor-data = <0x00800020>;
+
+		/*
+		 * These are extra properties to help Linux output.
+		 */
+		ibm,pir = <0x20>;
+		label = "Core";
+	};
+};