[linux-2.6-block.git] / Documentation / driver-api / iio / buffers.rst

=======
Buffers
=======

* struct 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 directory 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:`index`, the scan_index of the 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/storagebits[Xrepeat][>>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.
  * *repeat*, specifies the number of bits/storagebits repetitions. When the
    repeat element is 0 or 1, then the repeat value is omitted.
  * *shift*, if specified, is the shift that needs to be applied prior to
    masking out unused bits.

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 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:
Commit	Line	Data
49b2fd6e JC	1	=======
	2	Buffers
	3	=======
	4
9303c9d5	5	* struct iio_buffer — general buffer structure
49b2fd6e JC	6	* :c:func:`iio_validate_scan_mask_onehot` — Validates that exactly one channel
	7	is selected
	8	* :c:func:`iio_buffer_get` — Grab a reference to the buffer
	9	* :c:func:`iio_buffer_put` — Release the reference to the buffer
	10
	11	The Industrial I/O core offers a way for continuous data capture based on a
	12	trigger source. Multiple data channels can be read at once from
	13	:file:`/dev/iio:device{X}` character device node, thus reducing the CPU load.
	14
	15	IIO buffer sysfs interface
	16	==========================
	17	An IIO buffer has an associated attributes directory under
	18	:file:`/sys/bus/iio/iio:device{X}/buffer/*`. Here are some of the existing
	19	attributes:
	20
	21	* :file:`length`, the total number of data samples (capacity) that can be
	22	stored by the buffer.
	23	* :file:`enable`, activate buffer capture.
	24
	25	IIO buffer setup
	26	================
	27
	28	The meta information associated with a channel reading placed in a buffer is
8c56eebc	29	called a scan element. The important bits configuring scan elements are
49b2fd6e	30	exposed to userspace applications via the
f2163c1e	31	:file:`/sys/bus/iio/iio:device{X}/scan_elements/` directory. This directory contains
49b2fd6e JC	32	attributes of the following form:
	33
	34	* :file:`enable`, used for enabling a channel. If and only if its attribute
	35	is non zero, then a triggered capture will contain data samples for this
	36	channel.
bd9a013d	37	* :file:`index`, the scan_index of the channel.
49b2fd6e JC	38	* :file:`type`, description of the scan element data storage within the buffer
49b2fd6e JC	39	and hence the form in which it is read from user space.
6bc5ebe8	40	Format is [be\|le]:[s\|u]bits/storagebits[Xrepeat][>>shift] .
218977dc	41
49b2fd6e JC	42	* be or le, specifies big or little endian.
	43	* s or u, specifies if signed (2's complement) or unsigned.
	44	* bits, is the number of valid data bits.
	45	* storagebits, is the number of bits (after padding) that it occupies in the
218977dc	46	buffer.
49b2fd6e	47	* repeat, specifies the number of bits/storagebits repetitions. When the
218977dc LC	48	repeat element is 0 or 1, then the repeat value is omitted.
	49	* shift, if specified, is the shift that needs to be applied prior to
	50	masking out unused bits.
49b2fd6e JC	51
	52	For example, a driver for a 3-axis accelerometer with 12 bit resolution where
	53	data is stored in two 8-bits registers as follows::
	54
	55	7 6 5 4 3 2 1 0
	56	+---+---+---+---+---+---+---+---+
	57	\|D3 \|D2 \|D1 \|D0 \| X \| X \| X \| X \| (LOW byte, address 0x06)
	58	+---+---+---+---+---+---+---+---+
	59
	60	7 6 5 4 3 2 1 0
	61	+---+---+---+---+---+---+---+---+
	62	\|D11\|D10\|D9 \|D8 \|D7 \|D6 \|D5 \|D4 \| (HIGH byte, address 0x07)
	63	+---+---+---+---+---+---+---+---+
	64
	65	will have the following scan element type for each axis::
	66
	67	$ cat /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_y_type
	68	le:s12/16>>4
	69
	70	A user space application will interpret data samples read from the buffer as
	71	two byte little endian signed data, that needs a 4 bits right shift before
	72	masking out the 12 valid bits of data.
	73
	74	For implementing buffer support a driver should initialize the following
	75	fields in iio_chan_spec definition::
	76
	77	struct iio_chan_spec {
	78	/* other members */
	79	int scan_index
	80	struct {
	81	char sign;
	82	u8 realbits;
	83	u8 storagebits;
	84	u8 shift;
	85	u8 repeat;
	86	enum iio_endian endianness;
	87	} scan_type;
	88	};
	89
	90	The driver implementing the accelerometer described above will have the
	91	following channel definition::
	92
43354926	93	struct iio_chan_spec accel_channels[] = {
49b2fd6e JC	94	{
	95	.type = IIO_ACCEL,
	96	.modified = 1,
	97	.channel2 = IIO_MOD_X,
	98	/* other stuff here */
	99	.scan_index = 0,
	100	.scan_type = {
	101	.sign = 's',
	102	.realbits = 12,
	103	.storagebits = 16,
	104	.shift = 4,
	105	.endianness = IIO_LE,
	106	},
	107	}
	108	/* similar for Y (with channel2 = IIO_MOD_Y, scan_index = 1)
	109	* and Z (with channel2 = IIO_MOD_Z, scan_index = 2) axis
	110	*/
	111	}
	112
	113	Here scan_index defines the order in which the enabled channels are placed
	114	inside the buffer. Channels with a lower scan_index will be placed before
	115	channels with a higher index. Each channel needs to have a unique
	116	scan_index.
	117
	118	Setting scan_index to -1 can be used to indicate that the specific channel
	119	does not support buffered capture. In this case no entries will be created for
	120	the channel in the scan_elements directory.
	121
	122	More details
	123	============
	124	.. kernel-doc:: include/linux/iio/buffer.h
	125	.. kernel-doc:: drivers/iio/industrialio-buffer.c
	126	:export: