1<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Industrial I/O buffers</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="Industrial I/O driver developer's guide"><link rel="up" href="iiosubsys.html" title="Chapter 2. Industrial I/O core"><link rel="prev" href="API-struct-iio-chan-spec.html" title="struct iio_chan_spec"><link rel="next" href="API-struct-iio-buffer.html" title="struct iio_buffer"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"> Industrial I/O buffers </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="API-struct-iio-chan-spec.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Industrial I/O core</th><td width="20%" align="right"> <a accesskey="n" href="API-struct-iio-buffer.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="iiobuffer"></a> Industrial I/O buffers </h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="refentrytitle"><a href="API-struct-iio-buffer.html"><span class="phrase">struct iio_buffer</span></a></span><span class="refpurpose"> — 2 general buffer structure 3 </span></dt><dt><span class="refentrytitle"><a href="API-iio-validate-scan-mask-onehot.html"><span class="phrase">iio_validate_scan_mask_onehot</span></a></span><span class="refpurpose"> — 4 Validates that exactly one channel is selected 5 </span></dt><dt><span class="refentrytitle"><a href="API-iio-buffer-get.html"><span class="phrase">iio_buffer_get</span></a></span><span class="refpurpose"> — 6 Grab a reference to the buffer 7 </span></dt><dt><span class="refentrytitle"><a href="API-iio-buffer-put.html"><span class="phrase">iio_buffer_put</span></a></span><span class="refpurpose"> — 8 Release the reference to the buffer 9 </span></dt><dt><span class="sect2"><a href="iiobuffer.html#iiobuffersysfs">IIO buffer sysfs interface </a></span></dt><dt><span class="sect2"><a href="iiobuffer.html#iiobuffersetup"> IIO buffer setup </a></span></dt></dl></div><p> 10 The Industrial I/O core offers a way for continuous data capture 11 based on a trigger source. Multiple data channels can be read at once 12 from <code class="filename">/dev/iio:deviceX</code> character device node, 13 thus reducing the CPU load. 14 </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="iiobuffersysfs"></a>IIO buffer sysfs interface </h3></div></div></div><p> 15 An IIO buffer has an associated attributes directory under <code class="filename"> 16 /sys/bus/iio/iio:deviceX/buffer/</code>. Here are the existing 17 attributes: 18 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="emphasis"><em>length</em></span>, the total number of data samples 19 (capacity) that can be stored by the buffer. 20 </li><li class="listitem"><span class="emphasis"><em>enable</em></span>, activate buffer capture. 21 </li></ul></div><p> 22 23 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="iiobuffersetup"></a> IIO buffer setup </h3></div></div></div><p>The meta information associated with a channel reading 24 placed in a buffer is called a <span class="emphasis"><em> scan element </em></span>. 25 The important bits configuring scan elements are exposed to 26 userspace applications via the <code class="filename"> 27 /sys/bus/iio/iio:deviceX/scan_elements/</code> directory. This 28 file contains attributes of the following form: 29 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="emphasis"><em>enable</em></span>, used for enabling a channel. 30 If and only if its attribute is non zero, then a triggered capture 31 will contain data samples for this channel. 32 </li><li class="listitem"><span class="emphasis"><em>type</em></span>, description of the scan element 33 data storage within the buffer and hence the form in which it is 34 read from user space. Format is <span class="emphasis"><em> 35 [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] </em></span>. 36 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><span class="emphasis"><em>be</em></span> or <span class="emphasis"><em>le</em></span>, specifies 37 big or little endian. 38 </li><li class="listitem"><span class="emphasis"><em>s </em></span>or <span class="emphasis"><em>u</em></span>, specifies if 39 signed (2's complement) or unsigned. 40 </li><li class="listitem"><span class="emphasis"><em>bits</em></span>, is the number of valid data 41 bits. 42 </li><li class="listitem"><span class="emphasis"><em>storagebits</em></span>, is the number of bits 43 (after padding) that it occupies in the buffer. 44 </li><li class="listitem"><span class="emphasis"><em>shift</em></span>, if specified, is the shift that needs 45 to be applied prior to masking out unused bits. 46 </li><li class="listitem"><span class="emphasis"><em>repeat</em></span>, specifies the number of bits/storagebits 47 repetitions. When the repeat element is 0 or 1, then the repeat 48 value is omitted. 49 </li></ul></div></li></ul></div><p> 50 For example, a driver for a 3-axis accelerometer with 12 bit 51 resolution where data is stored in two 8-bits registers as 52 follows: 53 </p><pre class="programlisting"> 54 7 6 5 4 3 2 1 0 55 +---+---+---+---+---+---+---+---+ 56 |D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06) 57 +---+---+---+---+---+---+---+---+ 58 59 7 6 5 4 3 2 1 0 60 +---+---+---+---+---+---+---+---+ 61 |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07) 62 +---+---+---+---+---+---+---+---+ 63 </pre><p> 64 65 will have the following scan element type for each axis: 66 </p><pre class="programlisting"> 67 $ cat /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_y_type 68 le:s12/16>>4 69 </pre><p> 70 A user space application will interpret data samples read from the 71 buffer as two byte little endian signed data, that needs a 4 bits 72 right shift before masking out the 12 valid bits of data. 73 </p><p> 74 For implementing buffer support a driver should initialize the following 75 fields in <span class="type">iio_chan_spec</span> definition: 76 </p><pre class="programlisting"> 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 </pre><p> 90 The driver implementing the accelerometer described above will 91 have the following channel definition: 92 </p><pre class="programlisting"> 93 struct struct iio_chan_spec accel_channels[] = { 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 .storgebits = 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 </pre><p> 113 </p><p> 114 Here <span class="emphasis"><em> scan_index </em></span> defines the order in which 115 the enabled channels are placed inside the buffer. Channels with a lower 116 scan_index will be placed before channels with a higher index. Each 117 channel needs to have a unique scan_index. 118 </p><p> 119 Setting scan_index to -1 can be used to indicate that the specific 120 channel does not support buffered capture. In this case no entries will 121 be created for the channel in the scan_elements directory. 122 </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="API-struct-iio-chan-spec.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="iiosubsys.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="API-struct-iio-buffer.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="phrase">struct iio_chan_spec</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> <span class="phrase">struct iio_buffer</span></td></tr></table></div></body></html> 123