-
Notifications
You must be signed in to change notification settings - Fork 0
/
iiobuffer.html
122 lines (119 loc) · 8.91 KB
/
iiobuffer.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
<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"> —
general buffer structure
</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"> —
Validates that exactly one channel is selected
</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"> —
Grab a reference to the buffer
</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"> —
Release the reference to the buffer
</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>
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 <code class="filename">/dev/iio:deviceX</code> character device node,
thus reducing the CPU load.
</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>
An IIO buffer has an associated attributes directory under <code class="filename">
/sys/bus/iio/iio:deviceX/buffer/</code>. Here are the existing
attributes:
</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
(capacity) that can be stored by the buffer.
</li><li class="listitem"><span class="emphasis"><em>enable</em></span>, activate buffer capture.
</li></ul></div><p>
</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
placed in a buffer is called a <span class="emphasis"><em> scan element </em></span>.
The important bits configuring scan elements are exposed to
userspace applications via the <code class="filename">
/sys/bus/iio/iio:deviceX/scan_elements/</code> directory. This
file contains attributes of the following form:
</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.
If and only if its attribute is non zero, then a triggered capture
will contain data samples for this channel.
</li><li class="listitem"><span class="emphasis"><em>type</em></span>, description of the scan element
data storage within the buffer and hence the form in which it is
read from user space. Format is <span class="emphasis"><em>
[be|le]:[s|u]bits/storagebitsXrepeat[>>shift] </em></span>.
<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
big or little endian.
</li><li class="listitem"><span class="emphasis"><em>s </em></span>or <span class="emphasis"><em>u</em></span>, specifies if
signed (2's complement) or unsigned.
</li><li class="listitem"><span class="emphasis"><em>bits</em></span>, is the number of valid data
bits.
</li><li class="listitem"><span class="emphasis"><em>storagebits</em></span>, is the number of bits
(after padding) that it occupies in the buffer.
</li><li class="listitem"><span class="emphasis"><em>shift</em></span>, if specified, is the shift that needs
to be applied prior to masking out unused bits.
</li><li class="listitem"><span class="emphasis"><em>repeat</em></span>, specifies the number of bits/storagebits
repetitions. When the repeat element is 0 or 1, then the repeat
value is omitted.
</li></ul></div></li></ul></div><p>
For example, a driver for a 3-axis accelerometer with 12 bit
resolution where data is stored in two 8-bits registers as
follows:
</p><pre class="programlisting">
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)
+---+---+---+---+---+---+---+---+
</pre><p>
will have the following scan element type for each axis:
</p><pre class="programlisting">
$ cat /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_y_type
le:s12/16>>4
</pre><p>
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.
</p><p>
For implementing buffer support a driver should initialize the following
fields in <span class="type">iio_chan_spec</span> definition:
</p><pre class="programlisting">
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;
};
</pre><p>
The driver implementing the accelerometer described above will
have the following channel definition:
</p><pre class="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,
.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
*/
}
</pre><p>
</p><p>
Here <span class="emphasis"><em> scan_index </em></span> 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.
</p><p>
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.
</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>