[PATCH 5/6] thermal: iio Documentation

[Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=a, Size: 3882 bytes --]

An overview document about thermal iio binding.

Signed-off-by: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>
---
 Documentation/thermal/thermal_iio_binding | 88 +++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 Documentation/thermal/thermal_iio_binding

diff --git a/Documentation/thermal/thermal_iio_binding b/Documentation/thermal/thermal_iio_binding
new file mode 100644
index 0000000..df501f1
--- /dev/null
+++ b/Documentation/thermal/thermal_iio_binding
@@ -0,0 +1,88 @@
+
+Thermal IIO Bindings
+
+When CONFIG_THERMAL_IIO is enabled, in addition to the regular thermal
+zone attributes, an additional entry for an IIO device is created.
+IIO sysfs ABI documents is available at Documentation/ABI/sysfs-bus-iio.
+
+The following example shows the contents of the IIO:device in a thermal
+zone.
+
+thermal_zoneX
+├── iio:device9
+│   ├── buffer
+│   │   ├── enable
+│   │   ├── length
+│   │   └── watermark
+│   ├── events
+│   │   ├── in_temp_thresh_either_en
+│   │   └── in_temp_thresh_either_value
+│   ├── in_temp_raw
+│   ├── name
+│   ├── scan_elements
+│   │   ├── in_temp_en
+│   │   ├── in_temp_index
+│   │   ├── in_temp_type
+│   │   ├── in_timestamp_en
+│   │   ├── in_timestamp_index
+│   │   └── in_timestamp_type
+│   ├── subsystem -> ../../../../../bus/iio
+│   ├── trigger0
+│   │   └── name
+│   ├── trigger
+│   │   └── current_trigger
+│   └── uevent
+├── integral_cutoff
+...
+... other thermal_zone attributes
+...
+
+
+IIO Attributes
+
+name: This shows iio device name, which will match thermal_zone/type attribute
+in_temp_raw: This will show raw temperature values same as thermal_zone/temp
+attribute.
+
+trigger/current_trigger: This is IIO way of specifying data ready indication.
+If the thermal client can provide asynchronous notifications, then a iio trigger
+device is created under trigger0. The name of this trigger will be thermal
+device name suffixed with devX. To enable iio buffer notifications,
+trigger/current_trigger cab be updated with this trigger. For example
+
+#echo "x86_pkg_temp-dev9" > trigger/current_trigger
+
+In addition of samples can be pushed to iio buffers with external standard IIO
+device triggers, E.g. sysfs trigger.
+
+How to enable events?
+To enable events a suitable threshold temperature can be written to
+in_temp_thresh_either_value
+and enable by writing 1 to in_temp_thresh_either_en.
+
+To monitor events a good user space program is here:
+tools/iio/iio_event_monitor.c
+
+For example
+# echo 50000 > /sys/devices/virtual/thermal/thermal_zone9/iio:device9/events/in_temp_thresh_either_value
+# echo 1 > /sys/devices/virtual/thermal/thermal_zone9/iio:device9/events/in_temp_thresh_either_en
+# ./iio_event_monitor x86_pkg_temp
+Found IIO device with name x86_pkg_temp with device number 9
+Event: time: 1443297126626859289, type: temp, channel: 0, evtype: thresh, direction: either
+
+How to read temperature samples?
+When thermal client or core driver calls thermal_zone_device_update, this will
+result in sample pushed to iio buffers. These samples can be read from
+/dev/iio:deviceX file.
+
+To enable buffer select scan_elements
+# echo 1 > scan_elements/in_temp_en
+
+Set buffer length to n samples and enable buffer.
+# echo 2 > buffer/length
+# echo 1 > buffer/enable
+
+Then user can poll/select or /dev/iio:deviceX (Here X correspond to iio device number),
+and read temperature samples. A good example is at tools/iio/generic_buffer.c.
+
+
-- 
2.4.3