[PATCH] DocBook documentation for IIO

[PATCH] DocBook documentation for IIO

[Daniel Baluta]

In our effort to support vendors writing drivers for their own
sensors we introduce IIO documentation in DocBook format.

It documents Industrial I/O core including IIO devices, buffers, triggers and
triggered buffers. It also offers a short list of online resources
for the IIO subsystem.

This is far from being complete any suggestions are welcomed. At a first
glance we also need to add documentation for events. We are also working
on auto-generating template drivers based on the type of the IIO sensors.

Generated html files should be available online here http://dbaluta.github.io/
or you could run make htmldocs in the root of your kernel repo to get them.

Daniel Baluta (1):
  DocBook: Add initial documentation for IIO

 Documentation/DocBook/Makefile |   2 +-
 Documentation/DocBook/iio.tmpl | 588 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 589 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/DocBook/iio.tmpl

-- 
1.9.1

[PATCH] DocBook: Add initial documentation for IIO

[Daniel Baluta]

This is intended to help developers faster find their way
inside the Industrial I/O core and reduce time spent on IIO
drivers development.

Signed-off-by: Daniel Baluta <daniel.baluta@intel.com>
---
 Documentation/DocBook/Makefile |   2 +-
 Documentation/DocBook/iio.tmpl | 593 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 594 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/DocBook/iio.tmpl

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index b6a6a2e..9e08606 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -15,7 +15,7 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
 	    80211.xml debugobjects.xml sh.xml regulator.xml \
 	    alsa-driver-api.xml writing-an-alsa-driver.xml \
 	    tracepoint.xml drm.xml media_api.xml w1.xml \
-	    writing_musb_glue_layer.xml crypto-API.xml
+	    writing_musb_glue_layer.xml crypto-API.xml iio.xml
 
 include Documentation/DocBook/media/Makefile
 
diff --git a/Documentation/DocBook/iio.tmpl b/Documentation/DocBook/iio.tmpl
new file mode 100644
index 0000000..417bb26
--- /dev/null
+++ b/Documentation/DocBook/iio.tmpl
@@ -0,0 +1,593 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
+
+<book id="iioid">
+  <bookinfo>
+    <title>Industrial I/O driver developer's guide </title>
+
+    <authorgroup>
+      <author>
+        <firstname>Daniel</firstname>
+        <surname>Baluta</surname>
+        <affiliation>
+          <address>
+            <email>daniel.baluta@intel.com</email>
+          </address>
+        </affiliation>
+      </author>
+    </authorgroup>
+
+    <copyright>
+      <year>2015</year>
+      <holder>Intel Corporation</holder>
+    </copyright>
+
+    <legalnotice>
+      <para>
+        This documentation is free software; you can redistribute
+        it and/or modify it under the terms of the GNU General Public
+        License version 2.
+      </para>
+
+      <para>
+        This program is distributed in the hope that it will be
+        useful, but WITHOUT ANY WARRANTY; without even the implied
+        warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+        For more details see the file COPYING in the source
+        distribution of Linux.
+      </para>
+    </legalnotice>
+  </bookinfo>
+
+  <toc></toc>
+
+  <chapter id="intro">
+    <title>Introduction</title>
+    <para>
+      The main purpose of the Industrial I/O subsystem (IIO) is to provide
+      support for devices that in some sense are analog to digital converts
+      (ADCs). As many actual devices combine some ADCs with digital to analog
+      converters (DACs), that functionality is also supported. The aim is to
+      fill the gap between the somewhat similar hwmon and input subsystems.
+      Hwmon is very much directed at low sample rate sensors used in
+      applications such as fan speed control and temperature measurement. Input
+      is, as its name suggests, focused on human interaction input devices
+      (keyboard, mouse, touchscreen). In some cases there is considerable
+      overlap between these and IIO.
+  </para>
+  <para>
+    Devices that fall into this category are:
+
+    <itemizedlist>
+      <listitem>
+        analog to digital converters (ADCs)
+      </listitem>
+      <listitem>
+        accelerometers
+      </listitem>
+      <listitem>
+        capacitance to digital converters (CDCs)
+      </listitem>
+      <listitem>
+        digital to analog converters (DACs)
+      </listitem>
+      <listitem>
+        gyroscopes
+      </listitem>
+      <listitem>
+        inertial measurement units (IMUs)
+      </listitem>
+      <listitem>
+        color and light sensors
+      </listitem>
+      <listitem>
+        magnetometers
+      </listitem>
+      <listitem>
+        pressure sensors
+      </listitem>
+      <listitem>
+        proximity sensors
+      </listitem>
+      <listitem>
+        temperature sensors
+      </listitem>
+    </itemizedlist>
+    Usually these sensors are connected via SPI or I2C. It is also a common
+    use case to have combo functionality (e.g. light plus proximity sensor).
+  </para>
+  </chapter>
+  <chapter id='iiosubsys'>
+    <title>Industrial I/O core</title>
+    <para>
+      The Industrial I/O core offers:
+      <itemizedlist>
+        <listitem>
+         a unified framework for writing drivers for many different types of
+         embedded sensors.
+        </listitem>
+        <listitem>
+         a standard interface to user space applications manipulating sensors.
+        </listitem>
+      </itemizedlist>
+      The implementation can be found under <filename>
+      drivers/iio/industrialio-*</filename>
+  </para>
+  <sect1 id="iiodevice">
+    <title> Industrial I/O devices </title>
+
+!Finclude/linux/iio/iio.h iio_dev
+!Fdrivers/iio/industrialio-core.c iio_device_alloc
+!Fdrivers/iio/industrialio-core.c iio_device_free
+!Fdrivers/iio/industrialio-core.c iio_device_register
+!Fdrivers/iio/industrialio-core.c iio_device_unregister
+
+    <para>
+      An IIO device usually corresponds to a single hardware sensor and it
+      provides all the information needed by a driver handling a device.
+      Let's first have a look at the functionality embedded in an IIO
+      device then we will show how a device driver makes use of an IIO
+      device.
+    </para>
+    <para>
+        There are two ways for a user space application to interact
+        with an IIO driver.
+      <itemizedlist>
+        <listitem>
+          <filename>/sys/bus/iio/iio:deviceX/</filename>, this
+          represents a hardware sensor and groups together the data
+          channels of the same chip.
+        </listitem>
+        <listitem>
+          <filename>/dev/iio:deviceX</filename>, character device node
+          interface used for faster data transfer and for events information
+          retrieval.
+        </listitem>
+      </itemizedlist>
+    </para>
+    A typical IIO driver will register itself as an I2C or SPI driver and will
+    create two routines, <function> probe </function> and <function> remove
+    </function>. At <function>probe</function>:
+    <itemizedlist>
+    <listitem>call <function>iio_device_alloc</function>, which allocates memory
+      for an IIO device.
+    </listitem>
+    <listitem> initialize IIO device fields with driver specific information
+              (e.g. device name, device channels).
+    </listitem>
+    <listitem>call <function> iio_device_register</function>, this registers the
+      device with the IIO core. After this call the device is ready to accept
+      requests from user space applications.
+    </listitem>
+    </itemizedlist>
+      At <function>remove</function>, we free the resources allocated in
+      <function>probe</function> in reverse order:
+    <itemizedlist>
+    <listitem><function>iio_device_unregister</function>, unregister the device
+      from the IIO core.
+    </listitem>
+    <listitem><function>iio_device_free</function>, free the memory allocated
+      for the IIO device.
+    </listitem>
+    </itemizedlist>
+
+    <sect2 id="iioattr"> <title> IIO device sysfs interface </title>
+      <para>
+        Attributes are sysfs files used to expose chip info and also allowing
+        applications to set various configuration parameters. Common
+        attributes are:
+        <itemizedlist>
+          <listitem><filename>/sys/bus/iio/iio:deviceX/name</filename>,
+          description of the physical chip for device X.
+          </listitem>
+          <listitem><filename>/sys/bus/iio/iio:deviceX/dev</filename>,
+            shows the major:minor pair associated with
+            /dev/iio:deviceX node.
+          </listitem>
+          <listitem><filename>/sys/bus/iio:deviceX/sampling_frequency_available
+          </filename> available discrete set of sampling frequency values
+          for device X.
+          </listitem>
+      </itemizedlist>
+      Available standard attributes for IIO devices are described in the
+      <filename>Documentation/ABI/testing/sysfs-bus-iio </filename> file
+      in the Linux kernel sources.
+      </para>
+    </sect2>
+    <sect2 id="iiochannel"> <title> IIO device channels </title>
+!Finclude/linux/iio/iio.h iio_chan_spec structure.
+      <para>
+        An IIO device channel is a representation of a data channel. An
+        IIO device can have one or multiple channels. For example:
+        <itemizedlist>
+          <listitem>
+          a thermometer sensor has one channel representing the
+          temperature measurement.
+          </listitem>
+          <listitem>
+          a light sensor has two channels indicating the measurements in
+          the visible and infrared spectrum.
+          </listitem>
+          <listitem>
+          an accelerometer can have up two 3 channels representing
+          acceleration on X, Y and Z axes.
+          </listitem>
+        </itemizedlist>
+      An IIO channel is described by the <type> struct iio_chan_spec
+      </type>. A thermometer driver for the temperature sensor in the
+      example above would have to describe its channel as follows:
+      <programlisting>
+      static const struct iio_chan_spec temp_channel[] = {
+          {
+              .type = IIO_TEMP,
+              .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED),
+          },
+      };
+      </programlisting>
+
+      When there are multiple channels per device we need to set the <type>
+      .modified </type> field of <type>iio_chan_spec</type> to 1. For example,
+      a light sensor can have two channels one, for infrared light and one for
+      both infrared and visible light.
+      <programlisting>
+      static const struct iio_chan_spec light_channels[] = {
+          {
+              .type = IIO_INTENSITY,
+              .modified = 1,
+              .channel2 = IIO_MOD_LIGHT_IR,
+              .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
+              .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ),
+          },
+          {
+              .type = IIO_INTENSITY,
+              .modified = 1,
+              .channel2 = IIO_MOD_LIGHT_BOTH,
+              .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
+              .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ),
+          },
+      }
+      </programlisting>
+
+      This channel's definition will generate two separate sysfs files
+      for raw data retrieval:
+      <itemizedlist>
+      <listitem>
+      <filename>/sys/bus/iio/iio:deviceX/in_intensity_ir_raw</filename>
+      </listitem>
+      <listitem>
+      <filename>/sys/bus/iio/iio:deviceX/in_intensity_both_raw</filename>
+      </listitem>
+      </itemizedlist>
+      and one shared sysfs file for sampling frequency:
+      <itemizedlist>
+      <listitem>
+      <filename>/sys/bus/iio/iio:deviceX/in_intensity_sampling_frequency.
+      </filename>
+      </listitem>
+      </itemizedlist>
+      </para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="iiobuffer"> <title> Industrial I/O buffers </title>
+!Finclude/linux/iio/buffer.h iio_buffer
+!Edrivers/iio/industrialio-buffer.c
+
+    <para>
+    The Industrial I/O core offers a way for continuous data capture
+    based on a trigger source. Multiple data channels can be read at once
+    from <filename>/dev/iio:deviceX</filename> character device node,
+    thus reducing the CPU load.
+    </para>
+
+    <sect2 id="iiobuffersysfs">
+    <title>IIO buffer sysfs interface </title>
+    <para>
+      An IIO buffer has an associated attributes directory under <filename>
+      /sys/bus/iio/iio:deviceX/buffer/</filename>. Here are the existing
+      attributes:
+      <itemizedlist>
+      <listitem>
+      <emphasis>length</emphasis>, number of data samples contained by the
+        buffer.
+      </listitem>
+      <listitem>
+        <emphasis>enable</emphasis>, activate buffer capture.
+      </listitem>
+      </itemizedlist>
+    </para>
+    <para> In order to be useful, a buffer needs to have an associated
+      trigger. Future chapters will add details about triggers and how
+      drivers use triggers to start data capture, moving samples from device
+      registers to buffer storage and then upward to user space applications.
+    </para>
+    </sect2>
+    <sect2 id="iiobuffersetup"> <title> IIO buffer setup </title>
+      <para>The important bits for selecting data channels
+      configuration are exposed to userspace applications via the <filename>
+      /sys/bus/iio/iio:deviceX/scan_elements/</filename> directory. This
+      file contains attributes of the following form:
+      <itemizedlist>
+      <listitem><emphasis>enable</emphasis>, used for enabling a channel.
+        If and only if his attribute is non zero, thena triggered capture
+        will contain data sample for this channel.
+      </listitem>
+      <listitem><emphasis>type</emphasis>,  description of the scan element
+        data storage within the buffer and hence the form in which it is
+        read from user space. Format is <emphasis>
+        [be|le]:[s|u]bits/storagebits[>>shift] </emphasis>.
+        <itemizedlist>
+        <listitem> <emphasis>be</emphasis> or <emphasis>le</emphasis> specifies
+          big or little endian.
+        </listitem>
+        <listitem>
+        <emphasis>s </emphasis>or <emphasis>u</emphasis> specifies if
+        signed (2's complement) or unsigned.
+        </listitem>
+        <listitem>bits is the number of bits of data
+        </listitem>
+        <listitem>storagebits is the space (after padding) that it occupies in the
+          buffer.
+        </listitem>
+        <listitem>
+        <emphasis>shift</emphasis> if specified, is the shift that needs
+          to be a applied prior to masking out unused bits
+        </listitem>
+        </itemizedlist>
+      </listitem>
+      </itemizedlist>
+
+      For implementing buffer support a driver should initialize the following
+      fields in <type>iio_chan_spec</type> definition:
+
+      <programlisting>
+      struct iio_chan_spec {
+          /* other members */
+          int scan_index
+          struct {
+              u8 realbits;
+              u8 storagebits;
+              u8 shift;
+              enum iio_endian endianness;
+          } scan_type;
+      }
+      </programlisting>
+      Here is what a 3-axis, 12 bits accelerometer channels definition
+      looks like with buffer support:
+
+      <programlisting>
+      struct struct iio_chan_spec accel_channels[] = {
+          {
+            .type = IIO_ACCEL,
+            .modified = 1,
+            .channel2 = IIO_MOD_X,
+            /* other stuff here */
+            .scan_index = 0,
+            .scan_type = {
+              .sign = 's',
+              .realbits = 12,
+              .storgebits = 16,
+              .shift = 4,
+              .endianess = IIO_CPU,
+            },
+        }
+        /* similar for Y and  Z axis */
+    }
+    </programlisting>
+    Here <emphasis> scan_index </emphasis> is used for ordering data samples
+    (scans) when read from buffer.
+    </para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="iiotrigger"> <title> Industrial I/O triggers  </title>
+!Finclude/linux/iio/trigger.h iio_trigger
+!Edrivers/iio/industrialio-trigger.c
+    <para>
+      In many situations it is useful for a driver to be able to
+      capture data based on some external event (trigger) as opposed
+      to periodically polling for data. An IIO trigger can be provided
+      by a device driver that also has an IIO device based on hardware
+      generated events (e.g. data ready or threshold exceeded) or
+      provided by a separate driver from an independent interrupt
+      source (e.g. GPIO line connected to some external system, timer
+      interrupt or user space reading a specific file in sysfs). A
+      trigger may initialize data capture for a number of sensors and
+      also it may be completely unrelated to the sensor itself.
+    </para>
+
+    <sect2 id="iiotrigsysfs"> <title> IIO trigger sysfs interface </title>
+      There are two locations in sysfs related to triggers:
+      <itemizedlist>
+        <listitem><filename>/sys/bus/iio/devices/triggerX</filename>,
+          this file is created once an IIO triggered is registered with
+          the IIO core and corresponds to trigger with index X. Because
+          triggers can be very different depending on type there are few
+          standard attributes that we can describe here:
+          <itemizedlist>
+            <listitem>
+              <emphasis>name</emphasis>, trigger name that can be later
+                used to for association with a device.
+            </listitem>
+            <listitem>
+            <emphasis>sampling_frequency</emphasis>, some timer based
+              triggers use this attribute to specify the frequency for
+              trigger calls.
+            </listitem>
+          </itemizedlist>
+        </listitem>
+        <listitem>
+          <filename>/sys/bus/iio/devices/iio:deviceX/trigger/</filename>, this
+          directory is created once the device supports a triggered
+          buffer. We can associate a trigger with our device by writing
+            trigger's name in the<filename>current_trigger</filename> file.
+        </listitem>
+      </itemizedlist>
+    </sect2>
+
+    <sect2 id="iiotrigattr"> <title> IIO trigger setup</title>
+
+    <para>
+      Let's see a simple example of how to setup a trigger to be used
+      by a driver.
+
+      <programlisting>
+      struct iio_trigger_ops trigger_ops = {
+          .set_trigger_state = sample_trigger_state,
+          .validate_device = sample_validate_device,
+      }
+
+      struct iio_trigger *trig;
+
+      /* first, allocate memory for our trigger */
+      trig = iio_trigger_alloc(dev, "trig-%s-%d", name, idx);
+
+      /* setup trigger operations field */
+      trig->ops = &amp;trigger_ops;
+
+      /* now register the trigger with the IIO core */
+      iio_trigger_register(trig);
+      </programlisting>
+    </para>
+    </sect2>
+
+    <sect2 id="iiotrigsetup"> <title> IIO trigger ops</title>
+!Finclude/linux/iio/trigger.h iio_trigger_ops
+     <para>
+        Notice that a trigger has a set of operations attached:
+        <itemizedlist>
+        <listitem>
+          <function>set_trigger_state</function>, switch the trigger on/off
+          on demand.
+        </listitem>
+        <listitem>
+          <function>validate_device</function>, function to validate the
+          device when the current trigger gets changed.
+        </listitem>
+        </itemizedlist>
+      </para>
+    </sect2>
+  </sect1>
+  <sect1 id="iiotriggered_buffer">
+    <title> Industrial I/O triggered buffers </title>
+    <para>
+    Now that we know what buffers and triggers are let's see how they
+    work together.
+    </para>
+    <sect2 id="iiotrigbufsetup"> <title> IIO triggered buffer setup</title>
+!Edrivers/iio/industrialio-triggered-buffer.c
+!Finclude/linux/iio/iio.h iio_buffer_setup_ops
+
+
+    <para>
+    A typical triggered buffer setup looks like this:
+    <programlisting>
+    const struct iio_buffer_setup_ops sensor_buffer_setup_ops = {
+      .preenable    = sensor_buffer_preenable,
+      .postenable   = sensor_buffer_postenable,
+      .postdisable  = sensor_buffer_postdisable,
+      .predisable   = sensor_buffer_predisable,
+    };
+
+    irqreturn_t sensor_iio_pollfunc(int irq, void *p)
+    {
+        pf->timestamp = iio_get_time_ns();
+        return IRQ_WAKE_THREAD;
+    }
+
+    irqreturn_t sensor_trigger_handler(int irq, void *p)
+    {
+        u16 buf[8];
+
+        /* read data for each active channel */
+        for_each_set_bit(bit, active_scan_mask, masklength)
+            buf[i++] = sensor_get_data(bit)
+
+        iio_push_to_buffers_with_timestamp(indio_dev, buffer, timestamp);
+
+        iio_trigger_notify_done(trigger);
+    }
+
+    /* setup triggered buffer, usually in probe function */
+    iio_triggered_buffer_setup(indio_dev, sensor_iio_polfunc,
+                               sensor_trigger_handler,
+                               sensor_buffer_setup_ops);
+    </programlisting>
+    </para>
+    The important things to notice here are:
+    <itemizedlist>
+    <listitem><function> iio_buffer_setup_ops</function>, buffer setup
+    functions to be called at predefined points in buffer configuration
+    sequence (e.g. before enable, after disable). If not specified, IIO
+    core uses default <type>iio_triggered_buffer_setup_ops</type>.
+    </listitem>
+    <listitem><function>sensor_iio_pollfunc</function>, function that
+    will be used as top half of poll function. It usually does little
+    processing (as it runs in interrupt context). Most common operation
+    is recording of the current timestamp and for this reason one can
+    use the IIO core defined <function>iio_pollfunc_store_time</function>
+    function.
+    </listitem>
+    <listitem><function>sensor_trigger_handler</function>, function that
+    will be used as bottom half of poll function. Here all the
+    processing takes place. It usually reads data from the device and
+    stores it in the internal buffer together with the timestamp
+    recorded in the top half.
+    </listitem>
+    </itemizedlist>
+    </sect2>
+  </sect1>
+  </chapter>
+  <chapter id='iioresources'>
+    <title> Resources </title>
+      IIO core may change during time so the best documentation to read is the
+      source code. There are several locations where you should look:
+      <itemizedlist>
+        <listitem>
+          <filename>drivers/iio/</filename>, contains the IIO core plus
+          and directories for each sensor type (e.g. accel, magnetometer,
+          etc.)
+        </listitem>
+        <listitem>
+          <filename>include/linux/iio/</filename>, contains the header
+          files, nice to read for the internal kernel interfaces.
+        </listitem>
+        <listitem>
+        <filename>include/uapi/linux/iio/</filename>, contains file to be
+          used by user space applications.
+        </listitem>
+        <listitem>
+         <filename>tools/iio/</filename>, contains tools for rapidly
+          testing buffers, events and device creation.
+        </listitem>
+        <listitem>
+          <filename>drivers/staging/iio/</filename>, contains code for some
+          drivers or experimental features that are not yet mature enough
+          to be moved out.
+        </listitem>
+      </itemizedlist>
+    <para>
+    Besides the code, there are some good online documentation sources:
+    <itemizedlist>
+    <listitem>
+      <ulink url="http://marc.info/?l=linux-iio"> Industrial I/O mailing
+      list </ulink>
+    </listitem>
+    <listitem>
+      <ulink url="http://wiki.analog.com/software/linux/docs/iio/iio">
+      Analog Device IIO wiki page </ulink>
+    </listitem>
+    <listitem>
+      <ulink url="https://fosdem.org/2015/schedule/event/iiosdr/">
+      Using the Linux IIO framework for SDR, Lars-Peter Clausen's
+      presentation at FOSDEM </ulink>
+    </listitem>
+    </itemizedlist>
+    </para>
+  </chapter>
+</book>
+
+<!--
+vim: softtabstop=2:shiftwidth=2:expandtab:textwidth=72
+-->
-- 
1.9.1

Re: [PATCH] DocBook: Add initial documentation for IIO

[Jonathan Corbet]

On Wed,  8 Jul 2015 15:04:48 +0300
Daniel Baluta <daniel.baluta@intel.com> wrote:

> This is intended to help developers faster find their way
> inside the Industrial I/O core and reduce time spent on IIO
> drivers development.

Seems like good stuff to have, sorry it's taken me so long to have a look
at it.  Any other IIO folks want to send comments or an ack?

A few comments of mine below...

[...]
> diff --git a/Documentation/DocBook/iio.tmpl b/Documentation/DocBook/iio.tmpl
> new file mode 100644
> index 0000000..417bb26
> --- /dev/null
> +++ b/Documentation/DocBook/iio.tmpl
> @@ -0,0 +1,593 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
> +	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
> +
> +<book id="iioid">
> +  <bookinfo>
> +    <title>Industrial I/O driver developer's guide </title>
> +
> +    <authorgroup>
> +      <author>
> +        <firstname>Daniel</firstname>
> +        <surname>Baluta</surname>
> +        <affiliation>
> +          <address>
> +            <email>daniel.baluta@intel.com</email>
> +          </address>
> +        </affiliation>
> +      </author>
> +    </authorgroup>
> +
> +    <copyright>
> +      <year>2015</year>
> +      <holder>Intel Corporation</holder>
> +    </copyright>
> +
> +    <legalnotice>
> +      <para>
> +        This documentation is free software; you can redistribute
> +        it and/or modify it under the terms of the GNU General Public
> +        License version 2.
> +      </para>
> +
> +      <para>
> +        This program is distributed in the hope that it will be
> +        useful, but WITHOUT ANY WARRANTY; without even the implied
> +        warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
> +        For more details see the file COPYING in the source
> +        distribution of Linux.

Do we really need this paragraph?  It's not even a "program" by some views,
at least.

> +      </para>
> +    </legalnotice>
> +  </bookinfo>
> +
> +  <toc></toc>
> +
> +  <chapter id="intro">
> +    <title>Introduction</title>
> +    <para>
> +      The main purpose of the Industrial I/O subsystem (IIO) is to provide
> +      support for devices that in some sense are analog to digital converts

s/converts/converters/

[...]
> +    <sect2 id="iioattr"> <title> IIO device sysfs interface </title>
> +      <para>
> +        Attributes are sysfs files used to expose chip info and also allowing
> +        applications to set various configuration parameters. Common
> +        attributes are:
> +        <itemizedlist>
> +          <listitem><filename>/sys/bus/iio/iio:deviceX/name</filename>,
> +          description of the physical chip for device X.
> +          </listitem>
> +          <listitem><filename>/sys/bus/iio/iio:deviceX/dev</filename>,
> +            shows the major:minor pair associated with
> +            /dev/iio:deviceX node.
> +          </listitem>
> +          <listitem><filename>/sys/bus/iio:deviceX/sampling_frequency_available
> +          </filename> available discrete set of sampling frequency values
> +          for device X.
> +          </listitem>
> +      </itemizedlist>

This list might be easier to read by proving the directory name once at the
top, then just putting the attribute names here.

> +      Available standard attributes for IIO devices are described in the
> +      <filename>Documentation/ABI/testing/sysfs-bus-iio </filename> file
> +      in the Linux kernel sources.

Should that move out of testing at some point?

[...]

> +      An IIO channel is described by the <type> struct iio_chan_spec
> +      </type>. A thermometer driver for the temperature sensor in the
> +      example above would have to describe its channel as follows:
> +      <programlisting>
> +      static const struct iio_chan_spec temp_channel[] = {
> +          {
> +              .type = IIO_TEMP,
> +              .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED),
> +          },
> +      };
> +      </programlisting>

It seems we're skipping over the contents of .info_mask_separate?  IIO
developers will need to know about that, right?

> +      When there are multiple channels per device we need to set the <type>
> +      .modified </type> field of <type>iio_chan_spec</type> to 1. For example,
> +      a light sensor can have two channels one, for infrared light and one for
> +      both infrared and visible light.

That seems really opaque.  What does ".modified" actually indicate?
Clearly not the number of channels...

> +      <programlisting>
> +      static const struct iio_chan_spec light_channels[] = {
> +          {
> +              .type = IIO_INTENSITY,
> +              .modified = 1,
> +              .channel2 = IIO_MOD_LIGHT_IR,

It seems like the contents of this field would be good to document too.

[...]

> +    <para> In order to be useful, a buffer needs to have an associated
> +      trigger. Future chapters will add details about triggers and how
> +      drivers use triggers to start data capture, moving samples from device
> +      registers to buffer storage and then upward to user space applications.

I'm gonna hold you to that! :)

> +    </para>
> +    </sect2>
> +    <sect2 id="iiobuffersetup"> <title> IIO buffer setup </title>
> +      <para>The important bits for selecting data channels
> +      configuration are exposed to userspace applications via the <filename>

s/channels/channel/.  Even better would be "data-channel".

> +      /sys/bus/iio/iio:deviceX/scan_elements/</filename> directory. This
> +      file contains attributes of the following form:
> +      <itemizedlist>
> +      <listitem><emphasis>enable</emphasis>, used for enabling a channel.
> +        If and only if his attribute is non zero, thena triggered capture

s/his/its/; also fix "thena"

> +        will contain data sample for this channel.

sample*s*

> +      </listitem>
> +      <listitem><emphasis>type</emphasis>,  description of the scan element
> +        data storage within the buffer and hence the form in which it is
> +        read from user space. Format is <emphasis>
> +        [be|le]:[s|u]bits/storagebits[>>shift] </emphasis>.

OK, I'm slow, but this is not telling me much.  What's "scan element"?

> +        <itemizedlist>
> +        <listitem> <emphasis>be</emphasis> or <emphasis>le</emphasis> specifies
> +          big or little endian.
> +        </listitem>
> +        <listitem>
> +        <emphasis>s </emphasis>or <emphasis>u</emphasis> specifies if
> +        signed (2's complement) or unsigned.
> +        </listitem>
> +        <listitem>bits is the number of bits of data
> +        </listitem>
> +        <listitem>storagebits is the space (after padding) that it occupies in the
> +          buffer.
> +        </listitem>
> +        <listitem>
> +        <emphasis>shift</emphasis> if specified, is the shift that needs
> +          to be a applied prior to masking out unused bits
> +        </listitem>
> +        </itemizedlist>
> +      </listitem>
> +      </itemizedlist>

An example or two would be helpful here.

> +      For implementing buffer support a driver should initialize the following
> +      fields in <type>iio_chan_spec</type> definition:
> +
> +      <programlisting>
> +      struct iio_chan_spec {
> +          /* other members */
> +          int scan_index
> +          struct {
> +              u8 realbits;
> +              u8 storagebits;
> +              u8 shift;
> +              enum iio_endian endianness;
> +          } scan_type;
> +      }
> +      </programlisting>
> +      Here is what a 3-axis, 12 bits accelerometer channels definition
> +      looks like with buffer support:

channel.  (or maybe "channel's").

> +      <programlisting>
> +      struct struct iio_chan_spec accel_channels[] = {
> +          {
> +            .type = IIO_ACCEL,
> +            .modified = 1,
> +            .channel2 = IIO_MOD_X,
> +            /* other stuff here */
> +            .scan_index = 0,
> +            .scan_type = {
> +              .sign = 's',

You didn't mention .sign above.  Why 's'?

[...]
> +    <listitem><function> iio_buffer_setup_ops</function>, buffer setup
> +    functions to be called at predefined points in buffer configuration
> +    sequence (e.g. before enable, after disable). If not specified, IIO
> +    core uses default <type>iio_triggered_buffer_setup_ops</type>.

*the* IIO core uses *the* default...

> +    </listitem>
> +    <listitem><function>sensor_iio_pollfunc</function>, function that

*the* function...

> +    will be used as top half of poll function. It usually does little
> +    processing (as it runs in interrupt context). Most common operation

*The* most common...  [starting a new theme here, it seems]

> +    is recording of the current timestamp and for this reason one can
> +    use the IIO core defined <function>iio_pollfunc_store_time</function>
> +    function.
> +    </listitem>
> +    <listitem><function>sensor_trigger_handler</function>, function that
> +    will be used as bottom half of poll function. Here all the

A couple more the's here, please

> +    processing takes place. It usually reads data from the device and
> +    stores it in the internal buffer together with the timestamp
> +    recorded in the top half.
> +    </listitem>
> +    </itemizedlist>
> +    </sect2>
> +  </sect1>
> +  </chapter>
> +  <chapter id='iioresources'>
> +    <title> Resources </title>
> +      IIO core may change during time so the best documentation to read is the
> +      source code. There are several locations where you should look:

*The* IIO core.  So you say we're wasting our time with this file? :)

> +      <itemizedlist>
> +        <listitem>
> +          <filename>drivers/iio/</filename>, contains the IIO core plus
> +          and directories for each sensor type (e.g. accel, magnetometer,
> +          etc.)
> +        </listitem>
> +        <listitem>
> +          <filename>include/linux/iio/</filename>, contains the header
> +          files, nice to read for the internal kernel interfaces.
> +        </listitem>
> +        <listitem>
> +        <filename>include/uapi/linux/iio/</filename>, contains file to be

file*s*

> +          used by user space applications.

Thanks,

jon

Re: [PATCH] DocBook: Add initial documentation for IIO

[Jonathan Cameron]

On 16 July 2015 11:24:17 BST, Jonathan Corbet <corbet@lwn.net> wrote:
>On Wed,  8 Jul 2015 15:04:48 +0300
>Daniel Baluta <daniel.baluta@intel.com> wrote:
>
>> This is intended to help developers faster find their way
>> inside the Industrial I/O core and reduce time spent on IIO
>> drivers development.
>
>Seems like good stuff to have, sorry it's taken me so long to have a
>look
>at it.  Any other IIO folks want to send comments or an ack?
Will do. Bit of a backlog to catch up with.
 Probably Sunday before I get to this.. Or might review on phone later.

>
>A few comments of mine below...
>
>[...]
>> diff --git a/Documentation/DocBook/iio.tmpl
>b/Documentation/DocBook/iio.tmpl
>> new file mode 100644
>> index 0000000..417bb26
>> --- /dev/null
>> +++ b/Documentation/DocBook/iio.tmpl
>> @@ -0,0 +1,593 @@
>> +<?xml version="1.0" encoding="UTF-8"?>
>> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
>> +	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
>> +
>> +<book id="iioid">
>> +  <bookinfo>
>> +    <title>Industrial I/O driver developer's guide </title>
>> +
>> +    <authorgroup>
>> +      <author>
>> +        <firstname>Daniel</firstname>
>> +        <surname>Baluta</surname>
>> +        <affiliation>
>> +          <address>
>> +            <email>daniel.baluta@intel.com</email>
>> +          </address>
>> +        </affiliation>
>> +      </author>
>> +    </authorgroup>
>> +
>> +    <copyright>
>> +      <year>2015</year>
>> +      <holder>Intel Corporation</holder>
>> +    </copyright>
>> +
>> +    <legalnotice>
>> +      <para>
>> +        This documentation is free software; you can redistribute
>> +        it and/or modify it under the terms of the GNU General
>Public
>> +        License version 2.
>> +      </para>
>> +
>> +      <para>
>> +        This program is distributed in the hope that it will be
>> +        useful, but WITHOUT ANY WARRANTY; without even the implied
>> +        warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
>PURPOSE.
>> +        For more details see the file COPYING in the source
>> +        distribution of Linux.
>
>Do we really need this paragraph?  It's not even a "program" by some
>views,
>at least.
>
>> +      </para>
>> +    </legalnotice>
>> +  </bookinfo>
>> +
>> +  <toc></toc>
>> +
>> +  <chapter id="intro">
>> +    <title>Introduction</title>
>> +    <para>
>> +      The main purpose of the Industrial I/O subsystem (IIO) is to
>provide
>> +      support for devices that in some sense are analog to digital
>converts
>
>s/converts/converters/
>
>[...]
>> +    <sect2 id="iioattr"> <title> IIO device sysfs interface </title>
>> +      <para>
>> +        Attributes are sysfs files used to expose chip info and also
>allowing
>> +        applications to set various configuration parameters. Common
>> +        attributes are:
>> +        <itemizedlist>
>> +         
><listitem><filename>/sys/bus/iio/iio:deviceX/name</filename>,
>> +          description of the physical chip for device X.
>> +          </listitem>
>> +         
><listitem><filename>/sys/bus/iio/iio:deviceX/dev</filename>,
>> +            shows the major:minor pair associated with
>> +            /dev/iio:deviceX node.
>> +          </listitem>
>> +         
><listitem><filename>/sys/bus/iio:deviceX/sampling_frequency_available
>> +          </filename> available discrete set of sampling frequency
>values
>> +          for device X.
>> +          </listitem>
>> +      </itemizedlist>
>
>This list might be easier to read by proving the directory name once at
>the
>top, then just putting the attribute names here.
>
>> +      Available standard attributes for IIO devices are described in
>the
>> +      <filename>Documentation/ABI/testing/sysfs-bus-iio </filename>
>file
>> +      in the Linux kernel sources.
>
>Should that move out of testing at some point?
>
>[...]
>
>> +      An IIO channel is described by the <type> struct iio_chan_spec
>> +      </type>. A thermometer driver for the temperature sensor in
>the
>> +      example above would have to describe its channel as follows:
>> +      <programlisting>
>> +      static const struct iio_chan_spec temp_channel[] = {
>> +          {
>> +              .type = IIO_TEMP,
>> +              .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED),
>> +          },
>> +      };
>> +      </programlisting>
>
>It seems we're skipping over the contents of .info_mask_separate?  IIO
>developers will need to know about that, right?
>
>> +      When there are multiple channels per device we need to set the
><type>
>> +      .modified </type> field of <type>iio_chan_spec</type> to 1.
>For example,
>> +      a light sensor can have two channels one, for infrared light
>and one for
>> +      both infrared and visible light.
>
>That seems really opaque.  What does ".modified" actually indicate?
>Clearly not the number of channels...
>
>> +      <programlisting>
>> +      static const struct iio_chan_spec light_channels[] = {
>> +          {
>> +              .type = IIO_INTENSITY,
>> +              .modified = 1,
>> +              .channel2 = IIO_MOD_LIGHT_IR,
>
>It seems like the contents of this field would be good to document too.
>
>[...]
>
>> +    <para> In order to be useful, a buffer needs to have an
>associated
>> +      trigger. Future chapters will add details about triggers and
>how
>> +      drivers use triggers to start data capture, moving samples
>from device
>> +      registers to buffer storage and then upward to user space
>applications.
>
>I'm gonna hold you to that! :)
>
>> +    </para>
>> +    </sect2>
>> +    <sect2 id="iiobuffersetup"> <title> IIO buffer setup </title>
>> +      <para>The important bits for selecting data channels
>> +      configuration are exposed to userspace applications via the
><filename>
>
>s/channels/channel/.  Even better would be "data-channel".
>
>> +      /sys/bus/iio/iio:deviceX/scan_elements/</filename> directory.
>This
>> +      file contains attributes of the following form:
>> +      <itemizedlist>
>> +      <listitem><emphasis>enable</emphasis>, used for enabling a
>channel.
>> +        If and only if his attribute is non zero, thena triggered
>capture
>
>s/his/its/; also fix "thena"
>
>> +        will contain data sample for this channel.
>
>sample*s*
>
>> +      </listitem>
>> +      <listitem><emphasis>type</emphasis>,  description of the scan
>element
>> +        data storage within the buffer and hence the form in which
>it is
>> +        read from user space. Format is <emphasis>
>> +        [be|le]:[s|u]bits/storagebits[>>shift] </emphasis>.
>
>OK, I'm slow, but this is not telling me much.  What's "scan element"?
>
>> +        <itemizedlist>
>> +        <listitem> <emphasis>be</emphasis> or
><emphasis>le</emphasis> specifies
>> +          big or little endian.
>> +        </listitem>
>> +        <listitem>
>> +        <emphasis>s </emphasis>or <emphasis>u</emphasis> specifies
>if
>> +        signed (2's complement) or unsigned.
>> +        </listitem>
>> +        <listitem>bits is the number of bits of data
>> +        </listitem>
>> +        <listitem>storagebits is the space (after padding) that it
>occupies in the
>> +          buffer.
>> +        </listitem>
>> +        <listitem>
>> +        <emphasis>shift</emphasis> if specified, is the shift that
>needs
>> +          to be a applied prior to masking out unused bits
>> +        </listitem>
>> +        </itemizedlist>
>> +      </listitem>
>> +      </itemizedlist>
>
>An example or two would be helpful here.
>
>> +      For implementing buffer support a driver should initialize the
>following
>> +      fields in <type>iio_chan_spec</type> definition:
>> +
>> +      <programlisting>
>> +      struct iio_chan_spec {
>> +          /* other members */
>> +          int scan_index
>> +          struct {
>> +              u8 realbits;
>> +              u8 storagebits;
>> +              u8 shift;
>> +              enum iio_endian endianness;
>> +          } scan_type;
>> +      }
>> +      </programlisting>
>> +      Here is what a 3-axis, 12 bits accelerometer channels
>definition
>> +      looks like with buffer support:
>
>channel.  (or maybe "channel's").
>
>> +      <programlisting>
>> +      struct struct iio_chan_spec accel_channels[] = {
>> +          {
>> +            .type = IIO_ACCEL,
>> +            .modified = 1,
>> +            .channel2 = IIO_MOD_X,
>> +            /* other stuff here */
>> +            .scan_index = 0,
>> +            .scan_type = {
>> +              .sign = 's',
>
>You didn't mention .sign above.  Why 's'?
>
>[...]
>> +    <listitem><function> iio_buffer_setup_ops</function>, buffer
>setup
>> +    functions to be called at predefined points in buffer
>configuration
>> +    sequence (e.g. before enable, after disable). If not specified,
>IIO
>> +    core uses default <type>iio_triggered_buffer_setup_ops</type>.
>
>*the* IIO core uses *the* default...
>
>> +    </listitem>
>> +    <listitem><function>sensor_iio_pollfunc</function>, function
>that
>
>*the* function...
>
>> +    will be used as top half of poll function. It usually does
>little
>> +    processing (as it runs in interrupt context). Most common
>operation
>
>*The* most common...  [starting a new theme here, it seems]
>
>> +    is recording of the current timestamp and for this reason one
>can
>> +    use the IIO core defined
><function>iio_pollfunc_store_time</function>
>> +    function.
>> +    </listitem>
>> +    <listitem><function>sensor_trigger_handler</function>, function
>that
>> +    will be used as bottom half of poll function. Here all the
>
>A couple more the's here, please
>
>> +    processing takes place. It usually reads data from the device
>and
>> +    stores it in the internal buffer together with the timestamp
>> +    recorded in the top half.
>> +    </listitem>
>> +    </itemizedlist>
>> +    </sect2>
>> +  </sect1>
>> +  </chapter>
>> +  <chapter id='iioresources'>
>> +    <title> Resources </title>
>> +      IIO core may change during time so the best documentation to
>read is the
>> +      source code. There are several locations where you should
>look:
>
>*The* IIO core.  So you say we're wasting our time with this file? :)
>
>> +      <itemizedlist>
>> +        <listitem>
>> +          <filename>drivers/iio/</filename>, contains the IIO core
>plus
>> +          and directories for each sensor type (e.g. accel,
>magnetometer,
>> +          etc.)
>> +        </listitem>
>> +        <listitem>
>> +          <filename>include/linux/iio/</filename>, contains the
>header
>> +          files, nice to read for the internal kernel interfaces.
>> +        </listitem>
>> +        <listitem>
>> +        <filename>include/uapi/linux/iio/</filename>, contains file
>to be
>
>file*s*
>
>> +          used by user space applications.
>
>Thanks,
>
>jon

-- 
Sent from my Android device with K-9 Mail. Please excuse my brevity.

Re: [PATCH] DocBook: Add initial documentation for IIO

[Daniel Baluta]

On Thu, Jul 16, 2015 at 1:24 PM, Jonathan Corbet <corbet@lwn.net> wrote:
> On Wed,  8 Jul 2015 15:04:48 +0300
> Daniel Baluta <daniel.baluta@intel.com> wrote:
>
>> This is intended to help developers faster find their way
>> inside the Industrial I/O core and reduce time spent on IIO
>> drivers development.
>
> Seems like good stuff to have, sorry it's taken me so long to have a look
> at it.  Any other IIO folks want to send comments or an ack?

Thanks a lot Jon for your time. I also missed to explicitly add you on the
Cc list. I will make use of get_maintainer.pl for v2.

>
> A few comments of mine below...

Will fix in v2. Few comments inline

<snip>

>> +
>> +      <para>
>> +        This program is distributed in the hope that it will be
>> +        useful, but WITHOUT ANY WARRANTY; without even the implied
>> +        warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
>> +        For more details see the file COPYING in the source
>> +        distribution of Linux.
>
> Do we really need this paragraph?  It's not even a "program" by some views,
> at least.

This paragraph is present in most of the already existing documentation.
E.g. First 6 docs from here: https://www.kernel.org/doc/htmldocs/ have it.

But you have a good point it doesn't make much sense here. I will
remove it in v2.

<snip>

>> +      Available standard attributes for IIO devices are described in the
>> +      <filename>Documentation/ABI/testing/sysfs-bus-iio </filename> file
>> +      in the Linux kernel sources.
>
> Should that move out of testing at some point?

This has been here for quite some time (4 years?), but IIO gets more and
more drivers with new features and new ABI attributes that are somehow
still in testing.

So, I think it should stay here for at least one more year. Or perhaps
we can split this file and move the stable part in ABI/stable and keep
the new ABI in testing.

Agree with all other comments will address them in v2.

thanks,
Daniel.

Re: [PATCH] DocBook: Add initial documentation for IIO

[Jonathan Cameron]

On 8 July 2015 13:04:48 BST, Daniel Baluta <daniel.baluta@intel.com> wrote:
>This is intended to help developers faster find their way
>inside the Industrial I/O core and reduce time spent on IIO
>drivers development.
>
>Signed-off-by: Daniel Baluta <daniel.baluta@intel.com>
>---
> Documentation/DocBook/Makefile |   2 +-
>Documentation/DocBook/iio.tmpl | 593
>+++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 594 insertions(+), 1 deletion(-)
> create mode 100644 Documentation/DocBook/iio.tmpl
>
>diff --git a/Documentation/DocBook/Makefile
>b/Documentation/DocBook/Makefile
>index b6a6a2e..9e08606 100644
>--- a/Documentation/DocBook/Makefile
>+++ b/Documentation/DocBook/Makefile
>@@ -15,7 +15,7 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
> 	    80211.xml debugobjects.xml sh.xml regulator.xml \
> 	    alsa-driver-api.xml writing-an-alsa-driver.xml \
> 	    tracepoint.xml drm.xml media_api.xml w1.xml \
>-	    writing_musb_glue_layer.xml crypto-API.xml
>+	    writing_musb_glue_layer.xml crypto-API.xml iio.xml
> 
> include Documentation/DocBook/media/Makefile
> 
>diff --git a/Documentation/DocBook/iio.tmpl
>b/Documentation/DocBook/iio.tmpl
>new file mode 100644
>index 0000000..417bb26
>--- /dev/null
>+++ b/Documentation/DocBook/iio.tmpl
>@@ -0,0 +1,593 @@
>+<?xml version="1.0" encoding="UTF-8"?>
>+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
>+	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
>+
>+<book id="iioid">
>+  <bookinfo>
>+    <title>Industrial I/O driver developer's guide </title>
>+
>+    <authorgroup>
>+      <author>
>+        <firstname>Daniel</firstname>
>+        <surname>Baluta</surname>
>+        <affiliation>
>+          <address>
>+            <email>daniel.baluta@intel.com</email>
>+          </address>
>+        </affiliation>
>+      </author>
>+    </authorgroup>
>+
>+    <copyright>
>+      <year>2015</year>
>+      <holder>Intel Corporation</holder>
>+    </copyright>
>+
>+    <legalnotice>
>+      <para>
>+        This documentation is free software; you can redistribute
>+        it and/or modify it under the terms of the GNU General Public
>+        License version 2.
>+      </para>
>+
>+      <para>
>+        This program is distributed in the hope that it will be
>+        useful, but WITHOUT ANY WARRANTY; without even the implied
>+        warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
>PURPOSE.
>+        For more details see the file COPYING in the source
>+        distribution of Linux.
>+      </para>
>+    </legalnotice>
>+  </bookinfo>
>+
>+  <toc></toc>
>+
>+  <chapter id="intro">
>+    <title>Introduction</title>
>+    <para>
>+      The main purpose of the Industrial I/O subsystem (IIO) is to
>provide
>+      support for devices that in some sense are analog to digital
>converts
>+      (ADCs). As many actual devices combine some ADCs with digital to
>analog
>+      converters (DACs), that functionality is also supported. 

I wonder if we now want to treat DACs at the same level in the docs as ADCs.  Right
 now our support is simpler but there are patches adding full buffered support to output devices as well (Lars?)

Mind you we can always change the emphasis whenever we like!
> The aim
>is to
>+      fill the gap between the somewhat similar hwmon and input
>subsystems.
>+      Hwmon is very much directed at low sample rate sensors used in
>+      applications such as fan speed control and temperature
>measurement. Input
>+      is, as its name suggests, focused on human interaction input
>devices
>+      (keyboard, mouse, touchscreen). In some cases there is
>considerable
>+      overlap between these and IIO.
>+  </para>
>+  <para>
>+    Devices that fall into this category are:
Include (keep it so we don't have to always remember to update this!)
>+
>+    <itemizedlist>
>+      <listitem>
>+        analog to digital converters (ADCs)
>+      </listitem>
>+      <listitem>
>+        accelerometers
>+      </listitem>
>+      <listitem>
>+        capacitance to digital converters (CDCs)
>+      </listitem>
>+      <listitem>
>+        digital to analog converters (DACs)
>+      </listitem>
>+      <listitem>
>+        gyroscopes
>+      </listitem>
>+      <listitem>
>+        inertial measurement units (IMUs)
>+      </listitem>
>+      <listitem>
>+        color and light sensors
>+      </listitem>
>+      <listitem>
>+        magnetometers
>+      </listitem>
>+      <listitem>
>+        pressure sensors
>+      </listitem>
>+      <listitem>
>+        proximity sensors
>+      </listitem>
>+      <listitem>
>+        temperature sensors
>+      </listitem>
>+    </itemizedlist>
>+    Usually these sensors are connected via SPI or I2C.
Maybe add something about SOC integrated parts as well?

> It is also a
>common
>+    use case to have combo functionality (e.g. light plus proximity
>sensor).
>+  </para>
>+  </chapter>
>+  <chapter id='iiosubsys'>
>+    <title>Industrial I/O core</title>
>+    <para>
>+      The Industrial I/O core offers:
>+      <itemizedlist>
>+        <listitem>
>+         a unified framework for writing drivers for many different
>types of
>+         embedded sensors.
>+        </listitem>
>+        <listitem>
>+         a standard interface to user space applications manipulating
>sensors.
>+        </listitem>
>+      </itemizedlist>
>+      The implementation can be found under <filename>
>+      drivers/iio/industrialio-*</filename>
>+  </para>
>+  <sect1 id="iiodevice">
>+    <title> Industrial I/O devices </title>
>+
>+!Finclude/linux/iio/iio.h iio_dev
>+!Fdrivers/iio/industrialio-core.c iio_device_alloc
>+!Fdrivers/iio/industrialio-core.c iio_device_free
>+!Fdrivers/iio/industrialio-core.c iio_device_register
>+!Fdrivers/iio/industrialio-core.c iio_device_unregister
>+
>+    <para>
>+      An IIO device usually corresponds to a single hardware sensor
>and it
>+      provides all the information needed by a driver handling a
>device.

Could clarify when it doesn't somewhere?  Maybe that is later...
>+      Let's first have a look at the functionality embedded in an IIO
>+      device then we will show how a device driver makes use of an IIO
>+      device.
>+    </para>
>+    <para>
>+        There are two ways for a user space application to interact
>+        with an IIO driver.
>+      <itemizedlist>
>+        <listitem>
>+          <filename>/sys/bus/iio/iio:deviceX/</filename>, this
>+          represents a hardware sensor and groups together the data
>+          channels of the same chip.
>+        </listitem>
>+        <listitem>
>+          <filename>/dev/iio:deviceX</filename>, character device node
>+          interface used for faster data transfer and for events
>information
>+          retrieval.
>+        </listitem>
>+      </itemizedlist>
>+    </para>
>+    A typical IIO driver will register itself as an I2C or SPI driver
>and will
>+    create two routines, <function> probe </function> and <function>
>remove
>+    </function>. At <function>probe</function>:
>+    <itemizedlist>
>+    <listitem>call <function>iio_device_alloc</function>, which
>allocates memory
>+      for an IIO device.
>+    </listitem>
>+    <listitem> initialize IIO device fields with driver specific
>information
>+              (e.g. device name, device channels).
>+    </listitem>
>+    <listitem>call <function> iio_device_register</function>, this
>registers the
>+      device with the IIO core. After this call the device is ready to
>accept
>+      requests from user space applications.
>+    </listitem>
>+    </itemizedlist>
>+      At <function>remove</function>, we free the resources allocated
>in
>+      <function>probe</function> in reverse order:
>+    <itemizedlist>
>+    <listitem><function>iio_device_unregister</function>, unregister
>the device
>+      from the IIO core.
>+    </listitem>
>+    <listitem><function>iio_device_free</function>, free the memory
>allocated
>+      for the IIO device.
>+    </listitem>
>+    </itemizedlist>
>+
>+    <sect2 id="iioattr"> <title> IIO device sysfs interface </title>
>+      <para>
>+        Attributes are sysfs files used to expose chip info and also
>allowing
>+        applications to set various configuration parameters. Common
>+        attributes are:
>+        <itemizedlist>
>+         
><listitem><filename>/sys/bus/iio/iio:deviceX/name</filename>,
>+          description of the physical chip for device X.
>+          </listitem>
>+          <listitem><filename>/sys/bus/iio/iio:deviceX/dev</filename>,
>+            shows the major:minor pair associated with
>+            /dev/iio:deviceX node.
>+          </listitem>
>+         
><listitem><filename>/sys/bus/iio:deviceX/sampling_frequency_available
>+          </filename> available discrete set of sampling frequency
>values
>+          for device X.
>+          </listitem>
>+      </itemizedlist>
>+      Available standard attributes for IIO devices are described in
>the
>+      <filename>Documentation/ABI/testing/sysfs-bus-iio </filename>
>file
>+      in the Linux kernel sources.
>+      </para>
>+    </sect2>
>+    <sect2 id="iiochannel"> <title> IIO device channels </title>
>+!Finclude/linux/iio/iio.h iio_chan_spec structure.
>+      <para>
>+        An IIO device channel is a representation of a data channel.
Maybe define data channel?

>An
>+        IIO device can have one or multiple channels. For example:
>+        <itemizedlist>
>+          <listitem>
>+          a thermometer sensor has one channel representing the
>+          temperature measurement.
>+          </listitem>
>+          <listitem>
>+          a light sensor has 
With instead of has (because its an example)
>two channels indicating the measurements
>in
>+          the visible and infrared spectrum.
>+          </listitem>
>+          <listitem>
>+          an accelerometer can have up two 
to
3 channels representing
>+          acceleration on X, Y and Z axes.
>+          </listitem>
>+        </itemizedlist>
>+      An IIO channel is described by the <type> struct iio_chan_spec
>+      </type>. A thermometer driver for the temperature sensor in the
>+      example above would have to describe its channel as follows:
>+      <programlisting>
>+      static const struct iio_chan_spec temp_channel[] = {
>+          {
>+              .type = IIO_TEMP,
>+              .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED),
>+          },
>+      };
>+      </programlisting>
>+
>+      When there are multiple channels per device we need to set the
><type>
>+      .modified </type> field of <type>iio_chan_spec</type> to 1. For
>example,
>+      a light sensor can have two channels one, for infrared light and
>one for
>+      both infrared and visible light.

Could also be indexed.  Perhaps something describing that modifiers are
 to indicate a physically unique characteristic of the channel such as its
 direction or spectral response. If the channel is simply another instance then
 indexed is more appropriate.
>+      <programlisting>
>+      static const struct iio_chan_spec light_channels[] = {
>+          {
>+              .type = IIO_INTENSITY,
>+              .modified = 1,
>+              .channel2 = IIO_MOD_LIGHT_IR,
>+              .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
>+              .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ),
>+          },
>+          {
>+              .type = IIO_INTENSITY,
>+              .modified = 1,
>+              .channel2 = IIO_MOD_LIGHT_BOTH,
>+              .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
>+              .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ),
>+          },
>+      }
>+      </programlisting>
>+
>+      This channel's definition will generate two separate sysfs files
>+      for raw data retrieval:
>+      <itemizedlist>
>+      <listitem>
>+     
><filename>/sys/bus/iio/iio:deviceX/in_intensity_ir_raw</filename>
>+      </listitem>
>+      <listitem>
>+     
><filename>/sys/bus/iio/iio:deviceX/in_intensity_both_raw</filename>
>+      </listitem>
>+      </itemizedlist>
>+      and one shared sysfs file for sampling frequency:
>+      <itemizedlist>
>+      <listitem>
>+     
><filename>/sys/bus/iio/iio:deviceX/in_intensity_sampling_frequency.
>+      </filename>
>+      </listitem>
>+      </itemizedlist>
>+      </para>
>+    </sect2>
>+  </sect1
I would slight expand the example to include a computed illuminance channel.

Another facet that should not over complicate the example.
>+
>+  <sect1 id="iiobuffer"> <title> Industrial I/O buffers </title>
>+!Finclude/linux/iio/buffer.h iio_buffer
>+!Edrivers/iio/industrialio-buffer.c
>+
>+    <para>
>+    The Industrial I/O core offers a way for continuous data capture
>+    based on a trigger source. Multiple data channels can be read at
>once
>+    from <filename>/dev/iio:deviceX</filename> character device node,
>+    thus reducing the CPU load.
>+    </para>
Why reduced load? Also perhaps mention pseudo scans? (Sort of all at the same time)
>+
>+    <sect2 id="iiobuffersysfs">
>+    <title>IIO buffer sysfs interface </title>
>+    <para>
>+      An IIO buffer has an associated attributes directory under
><filename>
>+      /sys/bus/iio/iio:deviceX/buffer/</filename>. Here are the
>existing
>+      attributes:
>+      <itemizedlist>
>+      <listitem>
>+      <emphasis>length</emphasis>, number of data samples contained by
>the
>+        buffer.
>+      </listitem>
>+      <listitem>
>+        <emphasis>enable</emphasis>, activate buffer capture.
>+      </listitem>
>+      </itemizedlist>
>+    </para>
>+    <para> In order to be useful, a buffer needs to have an associated
>+      trigger. Future chapters will add details about triggers and how
>+      drivers use triggers to start data capture, moving samples from
>device
>+      registers to buffer storage and then upward to user space
>applications.
>+    </para>
>+    </sect2>
>+    <sect2 id="iiobuffersetup"> <title> IIO buffer setup </title>
>+      <para>The important bits for selecting data channels
>+      configuration are exposed to userspace applications via the
><filename>
>+      /sys/bus/iio/iio:deviceX/scan_elements/</filename> directory.
>This
>+      file contains attributes of the following form:
>+      <itemizedlist>
>+      <listitem><emphasis>enable</emphasis>, used for enabling a
>channel.
>+        If and only if his attribute is non zero, thena
Then a 
> triggered
>capture
>+        will contain data sample for this channel.
>+      </listitem>
>+      <listitem><emphasis>type</emphasis>,  description of the scan
>element
>+        data storage within the buffer and hence the form in which it
>is
>+        read from user space. Format is <emphasis>
>+        [be|le]:[s|u]bits/storagebits[>>shift] </emphasis>.
>+        <itemizedlist>
>+        <listitem> <emphasis>be</emphasis> or <emphasis>le</emphasis>
>specifies
>+          big or little endian.
>+        </listitem>
>+        <listitem>
>+        <emphasis>s </emphasis>or <emphasis>u</emphasis> specifies if
>+        signed (2's complement) or unsigned.
>+        </listitem>
>+        <listitem>bits is the number of bits of data
>+        </listitem>
>+        <listitem>storagebits is the space (after padding) that it
>occupies in the
>+          buffer.
>+        </listitem>
>+        <listitem>
>+        <emphasis>shift</emphasis> if specified, is the shift that
>needs
>+          to be a applied prior to masking out unused bits
>+        </listitem>
>+        </itemizedlist>
>+      </listitem>
>+      </itemizedlist>
>+
>+      For implementing buffer support a driver should initialize the
>following
>+      fields in <type>iio_chan_spec</type> definition:
>+
>+      <programlisting>
>+      struct iio_chan_spec {
>+          /* other members */
>+          int scan_index
>+          struct {
>+              u8 realbits;
>+              u8 storagebits;
>+              u8 shift;
>+              enum iio_endian endianness;
>+          } scan_type;
>+      }
>+      </programlisting>
>+      Here is what a 3-axis, 12 bits accelerometer channels definition
>+      looks like with buffer support:
>+
>+      <programlisting>
>+      struct struct iio_chan_spec accel_channels[] = {
>+          {
>+            .type = IIO_ACCEL,
>+            .modified = 1,
>+            .channel2 = IIO_MOD_X,
>+            /* other stuff here */
>+            .scan_index = 0,
>+            .scan_type = {
>+              .sign = 's',
>+              .realbits = 12,
>+              .storgebits = 16,
>+              .shift = 4,
>+              .endianess = IIO_CPU,
>+            },
>+        }
>+        /* similar for Y and  Z axis */
>+    }
>+    </programlisting>
>+    Here <emphasis> scan_index </emphasis> is used for ordering data
>samples
>+    (scans) when read from buffer.
>+    </para>
>+    </sect2>
>+  </sect1>
>+
>+  <sect1 id="iiotrigger"> <title> Industrial I/O triggers  </title>
>+!Finclude/linux/iio/trigger.h iio_trigger
>+!Edrivers/iio/industrialio-trigger.c
>+    <para>
>+      In many situations it is useful for a driver to be able to
>+      capture data based on some external event (trigger) as opposed
>+      to periodically polling for data. An IIO trigger can be provided
>+      by a device driver that also has an IIO device based on hardware
>+      generated events (e.g. data ready or threshold exceeded) or
>+      provided by a separate driver from an independent interrupt
>+      source (e.g. GPIO line connected to some external system, timer
>+      interrupt or user space reading a specific file in sysfs). A
>+      trigger may initialize data capture for a number of sensors and
>+      also it may be completely unrelated to the sensor itself.
>+    </para>
>+
>+    <sect2 id="iiotrigsysfs"> <title> IIO trigger sysfs interface
></title>
>+      There are two locations in sysfs related to triggers:
>+      <itemizedlist>
>+        <listitem><filename>/sys/bus/iio/devices/triggerX</filename>,
>+          this file is created once an IIO triggered is registered
>with
>+          the IIO core and corresponds to trigger with index X.
>Because
>+          triggers can be very different depending on type there are
>few
>+          standard attributes that we can describe here:
>+          <itemizedlist>
>+            <listitem>
>+              <emphasis>name</emphasis>, trigger name that can be
>later
>+                used to for association with a device.
>+            </listitem>
>+            <listitem>
>+            <emphasis>sampling_frequency</emphasis>, some timer based
>+              triggers use this attribute to specify the frequency for
>+              trigger calls.
>+            </listitem>
>+          </itemizedlist>
>+        </listitem>
>+        <listitem>
>+         
><filename>/sys/bus/iio/devices/iio:deviceX/trigger/</filename>, this
>+          directory is created once the device supports a triggered
>+          buffer. We can associate a trigger with our device by
>writing
>+            trigger's name in the<filename>current_trigger</filename>
>file.
>+        </listitem>
>+      </itemizedlist>
>+    </sect2>
>+
>+    <sect2 id="iiotrigattr"> <title> IIO trigger setup</title>
>+
>+    <para>
>+      Let's see a simple example of how to setup a trigger to be used
>+      by a driver.
>+
>+      <programlisting>
>+      struct iio_trigger_ops trigger_ops = {
>+          .set_trigger_state = sample_trigger_state,
>+          .validate_device = sample_validate_device,
>+      }
>+
>+      struct iio_trigger *trig;
>+
>+      /* first, allocate memory for our trigger */
>+      trig = iio_trigger_alloc(dev, "trig-%s-%d", name, idx);
>+
>+      /* setup trigger operations field */
>+      trig->ops = &amp;trigger_ops;
>+
>+      /* now register the trigger with the IIO core */
>+      iio_trigger_register(trig);
>+      </programlisting>
>+    </para>
>+    </sect2>
>+
>+    <sect2 id="iiotrigsetup"> <title> IIO trigger ops</title>
>+!Finclude/linux/iio/trigger.h iio_trigger_ops
>+     <para>
>+        Notice that a trigger has a set of operations attached:
>+        <itemizedlist>
>+        <listitem>
>+          <function>set_trigger_state</function>, switch the trigger
>on/off
>+          on demand.
>+        </listitem>
>+        <listitem>
>+          <function>validate_device</function>, function to validate
>the
>+          device when the current trigger gets changed.
>+        </listitem>
>+        </itemizedlist>
>+      </para>
>+    </sect2>
>+  </sect1>
>+  <sect1 id="iiotriggered_buffer">
>+    <title> Industrial I/O triggered buffers </title>
>+    <para>
>+    Now that we know what buffers and triggers are let's see how they
>+    work together.
>+    </para>
>+    <sect2 id="iiotrigbufsetup"> <title> IIO triggered buffer
>setup</title>
>+!Edrivers/iio/industrialio-triggered-buffer.c
>+!Finclude/linux/iio/iio.h iio_buffer_setup_ops
>+
>+
>+    <para>
>+    A typical triggered buffer setup looks like this:
>+    <programlisting>
>+    const struct iio_buffer_setup_ops sensor_buffer_setup_ops = {
>+      .preenable    = sensor_buffer_preenable,
>+      .postenable   = sensor_buffer_postenable,
>+      .postdisable  = sensor_buffer_postdisable,
>+      .predisable   = sensor_buffer_predisable,
>+    };
>+
>+    irqreturn_t sensor_iio_pollfunc(int irq, void *p)
>+    {
>+        pf->timestamp = iio_get_time_ns();
>+        return IRQ_WAKE_THREAD;
>+    }
>+
>+    irqreturn_t sensor_trigger_handler(int irq, void *p)
>+    {
>+        u16 buf[8];
>+
>+        /* read data for each active channel */
>+        for_each_set_bit(bit, active_scan_mask, masklength)
>+            buf[i++] = sensor_get_data(bit)
>+
>+        iio_push_to_buffers_with_timestamp(indio_dev, buffer,
>timestamp);
>+
>+        iio_trigger_notify_done(trigger);
>+    }
>+
>+    /* setup triggered buffer, usually in probe function */
>+    iio_triggered_buffer_setup(indio_dev, sensor_iio_polfunc,
>+                               sensor_trigger_handler,
>+                               sensor_buffer_setup_ops);
>+    </programlisting>
>+    </para>
>+    The important things to notice here are:
>+    <itemizedlist>
>+    <listitem><function> iio_buffer_setup_ops</function>, buffer setup
>+    functions to be called at predefined points in buffer
>configuration
>+    sequence (e.g. before enable, after disable). If not specified,
>IIO
>+    core uses default <type>iio_triggered_buffer_setup_ops</type>.
>+    </listitem>
>+    <listitem><function>sensor_iio_pollfunc</function>, function that
>+    will be used as top half of poll function. It usually does little
>+    processing (as it runs in interrupt context). Most common
>operation
>+    is recording of the current timestamp and for this reason one can
>+    use the IIO core defined
><function>iio_pollfunc_store_time</function>
>+    function.
>+    </listitem>
>+    <listitem><function>sensor_trigger_handler</function>, function
>that
>+    will be used as bottom half of poll function. 
Maybe mention it is a thread? 

Here all the
>+    processing takes place. It usually reads data from the device and
>+    stores it in the internal buffer together with the timestamp
>+    recorded in the top half.
>+    </listitem>
>+    </itemizedlist>
>+    </sect2>
>+  </sect1>
>+  </chapter>
>+  <chapter id='iioresources'>
>+    <title> Resources </title>
>+      IIO core may change during time so the best documentation to
>read is the
>+      source code.

Hehe 
> There are several locations where you should look:
>+      <itemizedlist>
>+        <listitem>
>+          <filename>drivers/iio/</filename>, contains the IIO core
>plus
>+          and directories for each sensor type (e.g. accel,
>magnetometer,
>+          etc.)
>+        </listitem>
>+        <listitem>
>+          <filename>include/linux/iio/</filename>, contains the header
>+          files, nice to read for the internal kernel interfaces.
>+        </listitem>
>+        <listitem>
>+        <filename>include/uapi/linux/iio/</filename>, contains file to
>be
>+          used by user space applications.
>+        </listitem>
>+        <listitem>
>+         <filename>tools/iio/</filename>, contains tools for rapidly
>+          testing buffers, events and device creation.
>+        </listitem>
>+        <listitem>
>+          <filename>drivers/staging/iio/</filename>, contains code for
>some
>+          drivers or experimental features that are not yet mature
>enough
>+          to be moved out.
>+        </listitem>
>+      </itemizedlist>
>+    <para>
>+    Besides the code, there are some good online documentation
>sources:
>+    <itemizedlist>
>+    <listitem>
>+      <ulink url="http://marc.info/?l=linux-iio"> Industrial I/O
>mailing
>+      list </ulink>
>+    </listitem>
>+    <listitem>
>+      <ulink url="http://wiki.analog.com/software/linux/docs/iio/iio">
>+      Analog Device IIO wiki page </ulink>
>+    </listitem>
>+    <listitem>
>+      <ulink url="https://fosdem.org/2015/schedule/event/iiosdr/">
>+      Using the Linux IIO framework for SDR, Lars-Peter Clausen's
>+      presentation at FOSDEM </ulink>
Cool. I had missed this one :)
>+    </listitem>
>+    </itemizedlist>
>+    </para>
>+  </chapter>
>+</book>
>+
>+<!--
>+vim: softtabstop=2:shiftwidth=2:expandtab:textwidth=72
>+-->

Sorry for messy review. Ignoring my daughter down the park:)

Anyhow, a great basis to build on. I like the example driven approach.
Might have missed it but perhaps cross refer to the dummy driver?

J

I-- 
Sent from my Android device with K-9 Mail. Please excuse my brevity.

Re: [PATCH] DocBook: Add initial documentation for IIO

[Daniel Baluta]

On Thu, Jul 16, 2015 at 10:31 PM, Jonathan Cameron <jic23@kernel.org> wrote:

Thanks for your review Jonathan! I will try to address your
comments in v2.


>>+      The main purpose of the Industrial I/O subsystem (IIO) is to
>>provide
>>+      support for devices that in some sense are analog to digital
>>converts
>>+      (ADCs). As many actual devices combine some ADCs with digital to
>>analog
>>+      converters (DACs), that functionality is also supported.
>
> I wonder if we now want to treat DACs at the same level in the docs as ADCs.  Right
>  now our support is simpler but there are patches adding full buffered support to output devices as well (Lars?)

I have very few experience with DACs IIO drivers :) but I assume that
the basic part
is the same (e.g. set .output = 1) then triggers are independent of
device type :).

Anyhow, the above line only says that IIO also supports DACs and then
all the examples
are for ADCs :). Perhaps I can make the examples more clear.

<snip>

>
>>+    Usually these sensors are connected via SPI or I2C.
> Maybe add something about SOC integrated parts as well?

Like sensors hubs?  We can add this later.

>>+    <para>
>>+    The Industrial I/O core offers a way for continuous data capture
>>+    based on a trigger source. Multiple data channels can be read at
>>once
>>+    from <filename>/dev/iio:deviceX</filename> character device node,
>>+    thus reducing the CPU load.
>>+    </para>
> Why reduced load? Also perhaps mention pseudo scans? (Sort of all at the same time)

Because, the alternative would be to use "polling" on sysfs data
attributes. This means:
* 3 userspace read()'s instead of 1.
* 3 kernel separate register reads instead 1 bulk read.

Perhaps I can make this clearer. :)

<snip>

> Sorry for messy review. Ignoring my daughter down the park:)
>
> Anyhow, a great basis to build on. I like the example driven approach.
> Might have missed it but perhaps cross refer to the dummy driver?

Thanks again for your time Jonathan! We are really happy with your
per weekend review sessions, so you would better stay away from
your phone while in the park :D.

thanks,
Daniel.

Re: [PATCH] DocBook: Add initial documentation for IIO

[jic23]

Daniel Baluta writes: 

> On Thu, Jul 16, 2015 at 10:31 PM, Jonathan Cameron <jic23@kernel.org> wrote: 
> 
> Thanks for your review Jonathan! I will try to address your
> comments in v2. 
> 
> 
>>>+      The main purpose of the Industrial I/O subsystem (IIO) is to
>>>provide
>>>+      support for devices that in some sense are analog to digital
>>>converts
>>>+      (ADCs). As many actual devices combine some ADCs with digital to
>>>analog
>>>+      converters (DACs), that functionality is also supported.
>>
>> I wonder if we now want to treat DACs at the same level in the docs as ADCs.  Right
>>  now our support is simpler but there are patches adding full buffered support to output devices as well (Lars?)
> 
> I have very few experience with DACs IIO drivers :) but I assume that
> the basic part
> is the same (e.g. set .output = 1) then triggers are independent of
> device type :). 
> 
> Anyhow, the above line only says that IIO also supports DACs and then
> all the examples
> are for ADCs :). Perhaps I can make the examples more clear. 
> 
> <snip> 
> 
>>
>>>+    Usually these sensors are connected via SPI or I2C.
>> Maybe add something about SOC integrated parts as well?
> 
> Like sensors hubs?  We can add this later.
Not so much sensor hubs (though could mention those as well).
A lot of our ADCs are integrated in various (typically arm) SOCs.
These then provide services to other users (battery etc) as needed.
> 
>>>+    <para>
>>>+    The Industrial I/O core offers a way for continuous data capture
>>>+    based on a trigger source. Multiple data channels can be read at
>>>once
>>>+    from <filename>/dev/iio:deviceX</filename> character device node,
>>>+    thus reducing the CPU load.
>>>+    </para>
>> Why reduced load? Also perhaps mention pseudo scans? (Sort of all at the same time)
> 
> Because, the alternative would be to use "polling" on sysfs data
> attributes. This means:
> * 3 userspace read()'s instead of 1.
> * 3 kernel separate register reads instead 1 bulk read. 
> 
> Perhaps I can make this clearer. :)
Also make the point that the interface is binary and scaling / offsets
left to userspace.  Just wants some explanation I think!
> 
> <snip> 
> 
>> Sorry for messy review. Ignoring my daughter down the park:) 
>>
>> Anyhow, a great basis to build on. I like the example driven approach.
>> Might have missed it but perhaps cross refer to the dummy driver?
> 
> Thanks again for your time Jonathan! We are really happy with your
> per weekend review sessions, so you would better stay away from
> your phone while in the park :D.
*laughs*.  My daughter's 9.  She doesn't really need pushing on the swings 
any more. Just keeps coming over to see what I'm doing :) 

Busy with Ballet shows this weekend and holiday next so got to fit
the odd bit in mid week at the moment :)
> 
> thanks,
> Daniel.

Re: [PATCH] DocBook documentation for IIO

[Randy Dunlap]

On 07/08/15 05:04, Daniel Baluta wrote:
> In our effort to support vendors writing drivers for their own
> sensors we introduce IIO documentation in DocBook format.
> 
> It documents Industrial I/O core including IIO devices, buffers, triggers and
> triggered buffers. It also offers a short list of online resources
> for the IIO subsystem.
> 
> This is far from being complete any suggestions are welcomed. At a first
> glance we also need to add documentation for events. We are also working
> on auto-generating template drivers based on the type of the IIO sensors.

Hi Daniel,

This is a good start.  Might as well get it merged and keep improving it.

Here are a few nits:

Warning(..//drivers/iio/industrialio-buffer.c:1145): cannot understand function prototype: 'struct iio_demux_table '

>> drop the "()" in the first line:
 * struct iio_demux_table() - table describing demux memcpy ops


In iio_buffer_get() and iio_buffer_put(), change "may be NULL"
to "may be %NULL".

In linux/iio/iio.h, struct iio_chan_spec, the sub-fields of @scan_type confuse
scripts/kernel-doc.  There isn't really a good way to do what you are trying
to do (AFAIK).  The problem is that things like "realbits:" (ending with a colon)
cause kernel-doc to think that that is some special comment and it generates
a separate paragraph for it at the end of the struct.  I changed all of those
colons to hyphens, but then kernel-doc just runs all of those sub-field
comment descriptions together... so I added a ';' at the end of each one, but
it doesn't look nice.


> Generated html files should be available online here http://dbaluta.github.io/
> or you could run make htmldocs in the root of your kernel repo to get them.
> 
> Daniel Baluta (1):
>   DocBook: Add initial documentation for IIO
> 
>  Documentation/DocBook/Makefile |   2 +-
>  Documentation/DocBook/iio.tmpl | 588 +++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 589 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/DocBook/iio.tmpl
> 


-- 
~Randy

Re: [PATCH] DocBook documentation for IIO

[Daniel Baluta]

Hi Randy,

On Fri, Jul 10, 2015 at 10:13 PM, Randy Dunlap <rdunlap@infradead.org> wrote:
> On 07/08/15 05:04, Daniel Baluta wrote:
>> In our effort to support vendors writing drivers for their own
>> sensors we introduce IIO documentation in DocBook format.
>>
>> It documents Industrial I/O core including IIO devices, buffers, triggers and
>> triggered buffers. It also offers a short list of online resources
>> for the IIO subsystem.
>>
>> This is far from being complete any suggestions are welcomed. At a first
>> glance we also need to add documentation for events. We are also working
>> on auto-generating template drivers based on the type of the IIO sensors.
>
> Hi Daniel,
>
> This is a good start.  Might as well get it merged and keep improving it.

This sounds like a good plan.

>
> Here are a few nits:
>
> Warning(..//drivers/iio/industrialio-buffer.c:1145): cannot understand function prototype: 'struct iio_demux_table '
>
>>> drop the "()" in the first line:
>  * struct iio_demux_table() - table describing demux memcpy ops
>
>
> In iio_buffer_get() and iio_buffer_put(), change "may be NULL"
> to "may be %NULL".
>
> In linux/iio/iio.h, struct iio_chan_spec, the sub-fields of @scan_type confuse
> scripts/kernel-doc.  There isn't really a good way to do what you are trying
> to do (AFAIK).  The problem is that things like "realbits:" (ending with a colon)
> cause kernel-doc to think that that is some special comment and it generates
> a separate paragraph for it at the end of the struct.  I changed all of those
> colons to hyphens, but then kernel-doc just runs all of those sub-field
> comment descriptions together... so I added a ';' at the end of each one, but
> it doesn't look nice.

We now about the warnings. Cristina is already working on a patch series to fix
them.

thanks,
Daniel.