docs: IIO documentation sphinx conversion

	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \

	    genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \

	    sh.xml regulator.xml w1.xml \

	    writing_musb_glue_layer.xml iio.xml

	    writing_musb_glue_layer.xml

ifeq ($(DOCBOOKS),)

=======

Buffers

=======

* struct :c:type:`iio_buffer` — general buffer structure

* :c:func:`iio_validate_scan_mask_onehot` — Validates that exactly one channel

  is selected

* :c:func:`iio_buffer_get` — Grab a reference to the buffer

* :c:func:`iio_buffer_put` — Release the reference to the buffer

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

:file:`/dev/iio:device{X}` character device node, thus reducing the CPU load.

IIO buffer sysfs interface

==========================

An IIO buffer has an associated attributes directory under

:file:`/sys/bus/iio/iio:device{X}/buffer/*`. Here are some of the existing

attributes:

* :file:`length`, the total number of data samples (capacity) that can be

  stored by the buffer.

* :file:`enable`, activate buffer capture.

IIO buffer setup

================

The meta information associated with a channel reading placed in a buffer is

called a scan element . The important bits configuring scan elements are

exposed to userspace applications via the

:file:`/sys/bus/iio/iio:device{X}/scan_elements/*` directory. This file contains

attributes of the following form:

* :file:`enable`, used for enabling a channel. If and only if its attribute

  is non *zero*, then a triggered capture will contain data samples for this

  channel.

* :file:`type`, description of the scan element data storage within the buffer

  and hence the form in which it is read from user space.

  Format is [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] .

  * *be* or *le*, specifies big or little endian.

  * *s* or *u*, specifies if signed (2's complement) or unsigned.

  * *bits*, is the number of valid data bits.

  * *storagebits*, is the number of bits (after padding) that it occupies in the

  buffer.

  * *shift*, if specified, is the shift that needs to be applied prior to

  masking out unused bits.

  * *repeat*, specifies the number of bits/storagebits repetitions. When the

  repeat element is 0 or 1, then the repeat value is omitted.

For example, a driver for a 3-axis accelerometer with 12 bit resolution where

data is stored in two 8-bits registers as follows::

        7   6   5   4   3   2   1   0

      +---+---+---+---+---+---+---+---+

      |D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06)

      +---+---+---+---+---+---+---+---+

        7   6   5   4   3   2   1   0

      +---+---+---+---+---+---+---+---+

      |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07)

      +---+---+---+---+---+---+---+---+

will have the following scan element type for each axis::

      $ cat /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_y_type

      le:s12/16>>4

A user space application will interpret data samples read from the buffer as

two byte little endian signed data, that needs a 4 bits right shift before

masking out the 12 valid bits of data.

For implementing buffer support a driver should initialize the following

fields in iio_chan_spec definition::

   struct iio_chan_spec {

   /* other members */

           int scan_index

           struct {

                   char sign;

                   u8 realbits;

                   u8 storagebits;

                   u8 shift;

                   u8 repeat;

                   enum iio_endian endianness;

                  } scan_type;

          };

The driver implementing the accelerometer described above will have the

following channel definition::

   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,

			   .storagebits = 16,

			   .shift = 4,

			   .endianness = IIO_LE,

		   },

           }

           /* similar for Y (with channel2 = IIO_MOD_Y, scan_index = 1)

            * and Z (with channel2 = IIO_MOD_Z, scan_index = 2) axis

            */

    }

Here **scan_index** defines the order in which the enabled channels are placed

inside the buffer. Channels with a lower **scan_index** will be placed before

channels with a higher index. Each channel needs to have a unique

**scan_index**.

Setting **scan_index** to -1 can be used to indicate that the specific channel

does not support buffered capture. In this case no entries will be created for

the channel in the scan_elements directory.

More details

============

.. kernel-doc:: include/linux/iio/buffer.h

.. kernel-doc:: drivers/iio/industrialio-buffer.c

   :export:

=============

Core elements

=============

The Industrial I/O core offers a unified framework for writing drivers for

many different types of embedded sensors. a standard interface to user space

applications manipulating sensors. The implementation can be found under

:file:`drivers/iio/industrialio-*`

Industrial I/O Devices

----------------------

* struct :c:type:`iio_dev` - industrial I/O device

* :c:func:`iio_device_alloc()` - alocate an :c:type:`iio_dev` from a driver

* :c:func:`iio_device_free()` - free an :c:type:`iio_dev` from a driver

* :c:func:`iio_device_register()` - register a device with the IIO subsystem

* :c:func:`iio_device_unregister()` - unregister a device from the IIO

  subsystem

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.

There are two ways for a user space application to interact with an IIO driver.

1. :file:`/sys/bus/iio/iio:device{X}/`, this represents a hardware sensor

   and groups together the data channels of the same chip.

2. :file:`/dev/iio:device{X}`, character device node interface used for

   buffered data transfer and for events information retrieval.

A typical IIO driver will register itself as an :doc:`I2C <../i2c>` or

:doc:`SPI <../spi>` driver and will create two routines, probe and remove.

At probe:

1. Call :c:func:`iio_device_alloc()`, which allocates memory for an IIO device.

2. Initialize IIO device fields with driver specific information (e.g.

   device name, device channels).

3. Call :c:func:`iio_device_register()`, this registers the device with the

   IIO core. After this call the device is ready to accept requests from user

   space applications.

At remove, we free the resources allocated in probe in reverse order:

1. :c:func:`iio_device_unregister()`, unregister the device from the IIO core.

2. :c:func:`iio_device_free()`, free the memory allocated for the IIO device.

IIO device sysfs interface

==========================

Attributes are sysfs files used to expose chip info and also allowing

applications to set various configuration parameters. For device with

index X, attributes can be found under /sys/bus/iio/iio:deviceX/ directory.

Common attributes are:

* :file:`name`, description of the physical chip.

* :file:`dev`, shows the major:minor pair associated with

  :file:`/dev/iio:deviceX` node.

* :file:`sampling_frequency_available`, available discrete set of sampling

  frequency values for device.

* Available standard attributes for IIO devices are described in the

  :file:`Documentation/ABI/testing/sysfs-bus-iio` file in the Linux kernel

  sources.

IIO device channels

===================

struct :c:type:`iio_chan_spec` - specification of a single channel

An IIO device channel is a representation of a data channel. An IIO device can

have one or multiple channels. For example:

* a thermometer sensor has one channel representing the temperature measurement.

* a light sensor with two channels indicating the measurements in the visible

  and infrared spectrum.

* an accelerometer can have up to 3 channels representing acceleration on X, Y

  and Z axes.

An IIO channel is described by the struct :c:type:`iio_chan_spec`.

A thermometer driver for the temperature sensor in the example above would

have to describe its channel as follows::

   static const struct iio_chan_spec temp_channel[] = {

        {

            .type = IIO_TEMP,

            .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED),

        },

   };

Channel sysfs attributes exposed to userspace are specified in the form of

bitmasks. Depending on their shared info, attributes can be set in one of the

following masks:

* **info_mask_separate**, attributes will be specific to

  this channel

* **info_mask_shared_by_type**, attributes are shared by all channels of the

  same type

* **info_mask_shared_by_dir**, attributes are shared by all channels of the same

  direction

* **info_mask_shared_by_all**, attributes are shared by all channels

When there are multiple data channels per channel type we have two ways to

distinguish between them:

* set **.modified** field of :c:type:`iio_chan_spec` to 1. Modifiers are

  specified using **.channel2** field of the same :c:type:`iio_chan_spec`

  structure and are used to indicate a physically unique characteristic of the

  channel such as its direction or spectral response. For example, a light

  sensor can have two channels, one for infrared light and one for both

  infrared and visible light.

* set **.indexed** field of :c:type:`iio_chan_spec` to 1. In this case the

  channel is simply another instance with an index specified by the **.channel**

  field.

Here is how we can make use of the channel's modifiers::

   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),

           },

           {

                   .type = IIO_LIGHT,

                   .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED),

                   .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ),

           },

      }

This channel's definition will generate two separate sysfs files for raw data

retrieval:

* :file:`/sys/bus/iio/iio:device{X}/in_intensity_ir_raw`

* :file:`/sys/bus/iio/iio:device{X}/in_intensity_both_raw`

one file for processed data:

* :file:`/sys/bus/iio/iio:device{X}/in_illuminance_input`

and one shared sysfs file for sampling frequency:

* :file:`/sys/bus/iio/iio:device{X}/sampling_frequency`.

Here is how we can make use of the channel's indexing::

   static const struct iio_chan_spec light_channels[] = {

           {

                   .type = IIO_VOLTAGE,

		   .indexed = 1,

		   .channel = 0,

		   .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),

	   },

           {

	           .type = IIO_VOLTAGE,

                   .indexed = 1,

                   .channel = 1,

                   .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),

           },

   }

This will generate two separate attributes files for raw data retrieval:

* :file:`/sys/bus/iio/devices/iio:device{X}/in_voltage0_raw`, representing

  voltage measurement for channel 0.

* :file:`/sys/bus/iio/devices/iio:device{X}/in_voltage1_raw`, representing

  voltage measurement for channel 1.

More details

============

.. kernel-doc:: include/linux/iio/iio.h

.. kernel-doc:: drivers/iio/industrialio-core.c

   :export:

.. include:: <isonum.txt>

Industrial I/O

==============

**Copyright** |copy| 2015 Intel Corporation

Contents:

.. toctree::

   :maxdepth: 2

   intro

   core

   buffers

   triggers

   triggered-buffers