[Skiboot] [PATCH v2 10/13] sensor: add device tree documentation

[Cédric Le Goater]

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

Signed-off-by: Cédric Le Goater <clg at fr.ibm.com>
---
 doc/device-tree/ibm,opal/sensors.txt |  146 ++++++++++++++++++++++++++++++++++
 1 file changed, 146 insertions(+)
 create mode 100644 doc/device-tree/ibm,opal/sensors.txt

diff --git a/doc/device-tree/ibm,opal/sensors.txt b/doc/device-tree/ibm,opal/sensors.txt
new file mode 100644
index 000000000000..06c57351ce9a
--- /dev/null
+++ b/doc/device-tree/ibm,opal/sensors.txt
@@ -0,0 +1,146 @@
+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 :
+
+	amb-temp at 6000/
+	cooling-fan at 2100/
+	cooling-fan at 2101/
+	...
+	core-temp at 20/
+	mem-temp at 1/
+	...
+	power-supply at 1000/
+	power-supply at 1001/
+
+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 at 20 {
+		compatible = "ibm,opal-sensor";
+		name = "core-temp";
+		sensor-type = "temp";
+
+		/* Status bits :
+		 *
+		 * 0x0006	CRITICAL+WARNING -> FATAL
+		 * 0x0004	CRITICAL
+		 * 0x0002	WARNING
+		 * 0x0001	PRESENT
+		 */
+		sensor-data = <0x00800020>;
+
+		/*
+		 * These are extra properties to help Linux output.
+		 */
+		ibm,pir = <0x20>;
+		label = "Core";
+	};
+
+
+	/*
+	 * IBM POWER8 system (FSP) sensor nodes
+	 *
+	 * resource names and identifiers are determined by the FSP.
+	 */
+	power-supply at 1000 {
+		compatible = "ibm,opal-sensor";
+		name = "power-supply";
+		sensor-data = <0x02031000>;
+
+		/* Status bits :
+		 *
+		 * 0x0004	AC FAULTED
+		 * 0x0002	FAULTED
+		 * 0x0001	PRESENT
+		 */
+		sensor-status = <0x00031000>;
+		sensor-type = "power";
+	};
+
+	amb-temp at 6000 {
+		compatible = "ibm,opal-sensor";
+		name = "amb-temp";
+		sensor-data = <0x01096000>;
+
+
+		/* Status bits :
+		 *
+		 * 0x0004	EM ALERT
+		 * 0x0002	FAULTED
+		 * 0x0001	PRESENT
+		 */
+		sensor-status = <0x00096000>;
+		sensor-type = "temp";
+
+		/*
+		 * Contains zeros. Unused for the moment.
+		 */
+		sensor-threshold = <0x02096000>;
+
+		/*
+		 * IBM location code. Unused for the moment but we
+		 * could use it in a label eventually
+		 */
+		ibm,loc-code = "D1";
+	};
+
+	cooling-fan at 2100 {
+		compatible = "ibm,opal-sensor";
+		name = "cooling-fan";
+		sensor-data = <0x02052100>;
+
+		/* Status bits :
+		 *
+		 * 0x0004	AC FAULTED
+		 * 0x0002	FAULTED
+		 * 0x0001	PRESENT
+		 */
+		sensor-status = <0x00052100>;
+		sensor-type = "fan";
+
+		/*
+		 * Contains zeros. Unused for the moment.
+		 */
+		sensor-threshold = <0x01052100>;
+
+		ibm,loc-code = "A1";
+	};
+};
-- 
1.7.10.4