libiio0-doc 0.6.40-1 / usr / share / doc / libiio0-doc / html / index.html

This file is indexed.

/usr/share/doc/libiio0-doc/html/index.html is in libiio0-doc 0.6.40-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below. 

  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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>libiio: Main Page</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { init_search(); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">libiio
   &#160;<span id="projectnumber">0.6</span>
   </div>
   <div id="projectbrief">Library for interfacing with IIO devices</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.11 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="pages.html"><span>Related&#160;Pages</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">libiio Documentation</div>  </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#license">License</a></li>
<li class="level1"><a href="#code_model">Code Model</a></li>
<li class="level1"><a href="#creating_context">Creating a context</a><ul><li class="level2"><a href="#navigation">Navigation</a><ul><li class="level3"><a href="#device_obj">Device objects</a></li>
<li class="level3"><a href="#channel_obj">Channel objects</a></li>
</ul>
</li>
<li class="level2"><a href="#list_params">Parameters</a></li>
</ul>
</li>
<li class="level1"><a href="#reading_modify_params">Reading and modifying parameters</a><ul><li class="level2"><a href="#read_param">Reading a parameter</a></li>
<li class="level2"><a href="#write_param">Modifying a parameter</a></li>
</ul>
</li>
<li class="level1"><a href="#trigger">Triggers</a></li>
<li class="level1"><a href="#capture_upload">Capturing or uploading samples</a><ul><li class="level2"><a href="#create_buffer">Enabling channels and creating the Buffer object</a></li>
<li class="level2"><a href="#refill">Refilling the Buffer (input devices only)</a></li>
<li class="level2"><a href="#read_write">Reading or writing samples to the Buffer</a><ul><li class="level3"><a href="#memcpy">Direct copy</a></li>
<li class="level3"><a href="#iterating_cb">Iterating over the buffer with a callback</a></li>
<li class="level3"><a href="#iterating_for">Iterating on the samples with a for loop</a></li>
<li class="level3"><a href="#deinterleave">Extracting from/to a second buffer</a></li>
</ul>
</li>
<li class="level2"><a href="#convert">Convert the samples from/to hardware format</a></li>
<li class="level2"><a href="#push">Submitting the Buffer (output devices only)</a></li>
</ul>
</li>
<li class="level1"><a href="#advanced">Advanced options</a><ul><li class="level2"><a href="#userdata">Register and retrieve a pointer</a></li>
<li class="level2"><a href="#debug_attr">Debug attributes</a></li>
<li class="level2"><a href="#registers">Reading and writing registers</a></li>
</ul>
</li>
</ul>
</div>
<div class="textblock"><h1><a class="anchor" id="license"></a>
License</h1>
<p>Libiio has been developed and is released under the terms of the GNU Lesser General Public License, version 2. This open-source license allows anyone to use the library for proprietary or open-source, commercial or non-commercial applications. This choice was motivated by the fact that Analog Devices is a company that principally sells hardware, and this library provides the clients with a better and easier way of using this hardware.</p>
<p>The full terms of the license can be found here: <a href="http://opensource.org/licenses/LGPL-2.1">http://opensource.org/licenses/LGPL-2.1</a></p>
<h1><a class="anchor" id="code_model"></a>
Code Model</h1>
<p>The basic bricks of the libiio API are the <a class="el" href="structiio__context.html" title="Contains the representation of an IIO context. ">iio_context</a>, <a class="el" href="structiio__device.html" title="Represents a device in the IIO context. ">iio_device</a>, <a class="el" href="structiio__channel.html" title="Represents an input or output channel of a device. ">iio_channel</a> and <a class="el" href="structiio__buffer.html" title="An input or output buffer, used to read or write samples. ">iio_buffer</a> classes.</p>
<div class="image">
<img src="doc/codemodel.svg"  alt="Caption text"/>
</div>
<ul>
<li>A <a class="el" href="structiio__context.html" title="Contains the representation of an IIO context. ">iio_context</a> object may contain zero or more <a class="el" href="structiio__device.html" title="Represents a device in the IIO context. ">iio_device</a> objects. A <a class="el" href="structiio__device.html" title="Represents a device in the IIO context. ">iio_device</a> object is associated with only one <a class="el" href="structiio__context.html" title="Contains the representation of an IIO context. ">iio_context</a>. This object represents an instance of the library.</li>
<li>A <a class="el" href="structiio__device.html" title="Represents a device in the IIO context. ">iio_device</a> object may contain zero or more <a class="el" href="structiio__channel.html" title="Represents an input or output channel of a device. ">iio_channel</a> objects. A <a class="el" href="structiio__channel.html" title="Represents an input or output channel of a device. ">iio_channel</a> object is associated with only one <a class="el" href="structiio__device.html" title="Represents a device in the IIO context. ">iio_device</a>.</li>
<li>A <a class="el" href="structiio__device.html" title="Represents a device in the IIO context. ">iio_device</a> object may be associated with one <a class="el" href="structiio__buffer.html" title="An input or output buffer, used to read or write samples. ">iio_buffer</a> object, and a <a class="el" href="structiio__buffer.html" title="An input or output buffer, used to read or write samples. ">iio_buffer</a> object is associated with only one <a class="el" href="structiio__device.html" title="Represents a device in the IIO context. ">iio_device</a>.</li>
</ul>
<h1><a class="anchor" id="creating_context"></a>
Creating a context</h1>
<p>Different functions are available to create the <a class="el" href="structiio__context.html" title="Contains the representation of an IIO context. ">iio_context</a> object. Depending on what backends were enabled when compiling the library, some of them may not be available. Each function will result in a different backend being used.</p>
<p>Those functions are:</p><ul>
<li><a class="el" href="group__Context.html#ga4aafea4c127b872d5214d41ccb4ce8c1" title="Create a context from local IIO devices (Linux only) ">iio_create_local_context()</a>: Create a "local" context, to use the IIO devices connected to the system (typically for cross-compiled applications).</li>
<li><a class="el" href="group__Context.html#gabb89575442d19f28b6557eee97f8fafd" title="Create a context from the network. ">iio_create_network_context()</a>: Create a "network" context that will work with a remotely connected target.</li>
</ul>
<p>Note that every function that compose the API of libiio will work independently of the function that was used to create the <a class="el" href="structiio__context.html" title="Contains the representation of an IIO context. ">iio_context</a> object.</p>
<p>The <a class="el" href="structiio__context.html" title="Contains the representation of an IIO context. ">iio_context</a> object can later be destroyed with <a class="el" href="group__Context.html#ga75de8dae515c539818e52b408830d3ba" title="Destroy the given context. ">iio_context_destroy()</a>.</p>
<h2><a class="anchor" id="navigation"></a>
Navigation</h2>
<h3><a class="anchor" id="device_obj"></a>
Device objects</h3>
<ul>
<li>From the <a class="el" href="structiio__context.html" title="Contains the representation of an IIO context. ">iio_context</a> object, you can obtain the number of available devices with <a class="el" href="group__Context.html#ga2acae321e081d85d61b6960f11c99573" title="Enumerate the devices found in the given context. ">iio_context_get_devices_count()</a>.</li>
<li>Then, each <a class="el" href="structiio__device.html" title="Represents a device in the IIO context. ">iio_device</a> object can be accessed with <a class="el" href="group__Context.html#ga146121adb7288ba44174cf6466922212" title="Get the device present at the given index. ">iio_context_get_device()</a>.</li>
<li>Alternatively, it is possible to lookup for a device name or ID with <a class="el" href="group__Context.html#gae5807303b638869679ece67270e72e77" title="Try to find a device structure by its name of ID. ">iio_context_find_device()</a>.</li>
</ul>
<p>Each <a class="el" href="structiio__device.html" title="Represents a device in the IIO context. ">iio_device</a> object has an ID that can be used as identifier. This ID can be retrieved with <a class="el" href="group__Device.html#ga233b868380bca0578907bda28d3a5480" title="Retrieve the device ID (e.g. iio:device0) ">iio_device_get_id()</a>. It optionally also has a name, that can be retrieved with <a class="el" href="group__Device.html#gae7adad053ab5e2a5f447851f7d34dc04" title="Retrieve the device name (e.g. xadc) ">iio_device_get_name()</a>.</p>
<h3><a class="anchor" id="channel_obj"></a>
Channel objects</h3>
<ul>
<li>From the <a class="el" href="structiio__device.html" title="Represents a device in the IIO context. ">iio_device</a> object, you can obtain the number of available channels with <a class="el" href="group__Device.html#gab673fa9f0dd70dcc6dd756048593a0fa" title="Enumerate the channels of the given device. ">iio_device_get_channels_count()</a>.</li>
<li>Then, each <a class="el" href="structiio__channel.html" title="Represents an input or output channel of a device. ">iio_channel</a> object can be accessed with <a class="el" href="group__Device.html#ga853334a4cfa9a0b39e93ac78455b83fd" title="Get the channel present at the given index. ">iio_device_get_channel()</a>.</li>
<li>Alternatively, it is possible to lookup for a channel name or ID with <a class="el" href="group__Device.html#gacf9fe193b8183df86eab56df7da7361d" title="Try to find a channel structure by its name of ID. ">iio_device_find_channel()</a>.</li>
</ul>
<p>Each <a class="el" href="structiio__channel.html" title="Represents an input or output channel of a device. ">iio_channel</a> can be either input, or output. This information can be retrieved with <a class="el" href="group__Channel.html#gaee333f1061000b0b71298dff59104513" title="Return True if the given channel is an output channel. ">iio_channel_is_output()</a>. As for the Device objects, the <a class="el" href="structiio__channel.html" title="Represents an input or output channel of a device. ">iio_channel</a> object features an ID and optionally a name. The ID can be obtained with <a class="el" href="group__Channel.html#gaf4e082d88d0dfe4f078abfa633dc18a6" title="Retrieve the channel ID (e.g. voltage0) ">iio_channel_get_id()</a>, and the name can be obtained with <a class="el" href="group__Channel.html#ga49d2593f3bb7c3b0a618e65d34888d76" title="Retrieve the channel name (e.g. vccint) ">iio_channel_get_name()</a>. Important note: two <a class="el" href="structiio__channel.html" title="Represents an input or output channel of a device. ">iio_channel</a> can have the same ID, as long as one is input and the other is output.</p>
<h2><a class="anchor" id="list_params"></a>
Parameters</h2>
<p>Different kinds of parameters are available: parameters that apply to a <a class="el" href="structiio__device.html" title="Represents a device in the IIO context. ">iio_device</a>, and parameters that apply to one or more <a class="el" href="structiio__channel.html" title="Represents an input or output channel of a device. ">iio_channel</a>.</p><ul>
<li>The number of device-specific parameters can be obtained with <a class="el" href="group__Device.html#ga5cea41d7dd9babf48937e939aa0d3c5b" title="Enumerate the device-specific attributes of the given device. ">iio_device_get_attrs_count()</a>. Each attribute name can be obtained with <a class="el" href="group__Device.html#ga9f864d556e8089450a3062fd7f184041" title="Get the device-specific attribute present at the given index. ">iio_device_get_attr()</a>.</li>
<li>The number of channel-specific attributes can be obtained with <a class="el" href="group__Channel.html#ga0d9e98519d12fc02a17a3f47011321fb" title="Enumerate the channel-specific attributes of the given channel. ">iio_channel_get_attrs_count()</a>. Each attribute name can be obtained with <a class="el" href="group__Channel.html#gafd133e49a1a694e394939b4c5a073cb5" title="Get the channel-specific attribute present at the given index. ">iio_channel_get_attr()</a>.</li>
</ul>
<p>Alternatively, it is possible to lookup for the name of an attribute with <a class="el" href="group__Device.html#gac4b901fc37d404235e2b836d472cd3a4" title="Try to find a device-specific attribute by its name. ">iio_device_find_attr()</a> and <a class="el" href="group__Channel.html#ga64cd8c18fdc14a9a5fb21d955fa99b35" title="Try to find a channel-specific attribute by its name. ">iio_channel_find_attr()</a>.</p>
<h1><a class="anchor" id="reading_modify_params"></a>
Reading and modifying parameters</h1>
<h2><a class="anchor" id="read_param"></a>
Reading a parameter</h2>
<p>Read device-specific attributes with those functions:</p><ul>
<li><a class="el" href="group__Device.html#gacf36dfa2fc04a80ce93db3b131bae099" title="Read the content of the given device-specific attribute. ">iio_device_attr_read()</a></li>
<li><a class="el" href="group__Device.html#gaee1f1895db399936d29c5dff34eac21e" title="Read the content of all device-specific attributes. ">iio_device_attr_read_all()</a></li>
<li><a class="el" href="group__Device.html#ga81493a122a9da884af36d087cbc80614" title="Read the content of the given device-specific attribute. ">iio_device_attr_read_bool()</a></li>
<li><a class="el" href="group__Device.html#gace7a0de3e19a58c38f23e2a9b444dfff" title="Read the content of the given device-specific attribute. ">iio_device_attr_read_longlong()</a></li>
<li><a class="el" href="group__Device.html#gaeb192bd3730c8c65a4e5c29feca62257" title="Read the content of the given device-specific attribute. ">iio_device_attr_read_double()</a></li>
</ul>
<p>Read channel-specific attributes with those functions:</p><ul>
<li><a class="el" href="group__Channel.html#gacb37ef830dcc100a9908d0592d1ff190" title="Read the content of the given channel-specific attribute. ">iio_channel_attr_read()</a></li>
<li><a class="el" href="group__Channel.html#ga66bdc45f6b55cd28e76945ead18686ca" title="Read the content of all channel-specific attributes. ">iio_channel_attr_read_all()</a></li>
<li><a class="el" href="group__Channel.html#gabcd0cd25e203976bdc525790b6fe4e23" title="Read the content of the given channel-specific attribute. ">iio_channel_attr_read_bool()</a></li>
<li><a class="el" href="group__Channel.html#ga8c5fc6f7ccee7f9da338833822f799ec" title="Read the content of the given channel-specific attribute. ">iio_channel_attr_read_longlong()</a></li>
<li><a class="el" href="group__Channel.html#ga823b2e43e8d1bc0122266e83fe81fbc4" title="Read the content of the given channel-specific attribute. ">iio_channel_attr_read_double()</a></li>
</ul>
<p>Read debug attributes with those functions:</p><ul>
<li><a class="el" href="group__Debug.html#ga2ae0fe2e179de9f6de10900f72fc28be" title="Read the content of the given debug attribute. ">iio_device_debug_attr_read()</a></li>
<li><a class="el" href="group__Debug.html#ga4d8f3a846d5df8ee97c91789014dcb16" title="Read the content of all debug attributes. ">iio_device_debug_attr_read_all()</a></li>
<li><a class="el" href="group__Debug.html#gac2d887e2f77423596487302d2728c99e" title="Read the content of the given debug attribute. ">iio_device_debug_attr_read_bool()</a></li>
<li><a class="el" href="group__Debug.html#gac43421333d85b03e7aeb31eb60a676fe" title="Read the content of the given debug attribute. ">iio_device_debug_attr_read_longlong()</a></li>
<li><a class="el" href="group__Debug.html#ga01b435571a0bd034bc47987295821573" title="Read the content of the given debug attribute. ">iio_device_debug_attr_read_double()</a></li>
</ul>
<h2><a class="anchor" id="write_param"></a>
Modifying a parameter</h2>
<p>Write device-specific attributes with those functions:</p><ul>
<li><a class="el" href="group__Device.html#ga3baae3a4b76956f9a7bc31c2ebb5b682" title="Set the value of the given device-specific attribute. ">iio_device_attr_write()</a></li>
<li><a class="el" href="group__Device.html#ga81b3ad843d0e4b2e8857c0205e9fbb07" title="Set the values of all device-specific attributes. ">iio_device_attr_write_all()</a></li>
<li><a class="el" href="group__Device.html#gae3a265d5053a2cac254eb59a8eeda9da" title="Set the value of the given device-specific attribute. ">iio_device_attr_write_bool()</a></li>
<li><a class="el" href="group__Device.html#ga176d11776f916c8148c6dfa1368cea3c" title="Set the value of the given device-specific attribute. ">iio_device_attr_write_longlong()</a></li>
<li><a class="el" href="group__Device.html#ga638c2f54b187a1b137f9885f34fad338" title="Set the value of the given device-specific attribute. ">iio_device_attr_write_double()</a></li>
</ul>
<p>Write channel-specific attributes with those functions:</p><ul>
<li><a class="el" href="group__Channel.html#ga68c8e6c772dbf4bbec921c1dc050ab3e" title="Set the value of the given channel-specific attribute. ">iio_channel_attr_write()</a></li>
<li><a class="el" href="group__Channel.html#ga0430f53a97a6fe7474416d7e2b228421" title="Set the values of all channel-specific attributes. ">iio_channel_attr_write_all()</a></li>
<li><a class="el" href="group__Channel.html#gaa08ea63cf2ed45b5d47deb14019e12bf" title="Set the value of the given channel-specific attribute. ">iio_channel_attr_write_bool()</a></li>
<li><a class="el" href="group__Channel.html#ga3c86ab8607c4ae38e2a36fa8c6bedcfd" title="Set the value of the given channel-specific attribute. ">iio_channel_attr_write_longlong()</a></li>
<li><a class="el" href="group__Channel.html#ga8dd9233a125c95969dac270b4dd5e8b0" title="Set the value of the given channel-specific attribute. ">iio_channel_attr_write_double()</a></li>
</ul>
<p>Write debug attributes with those functions:</p><ul>
<li><a class="el" href="group__Device.html#ga3baae3a4b76956f9a7bc31c2ebb5b682" title="Set the value of the given device-specific attribute. ">iio_device_attr_write()</a></li>
<li><a class="el" href="group__Device.html#ga81b3ad843d0e4b2e8857c0205e9fbb07" title="Set the values of all device-specific attributes. ">iio_device_attr_write_all()</a></li>
<li><a class="el" href="group__Device.html#gae3a265d5053a2cac254eb59a8eeda9da" title="Set the value of the given device-specific attribute. ">iio_device_attr_write_bool()</a></li>
<li><a class="el" href="group__Device.html#ga176d11776f916c8148c6dfa1368cea3c" title="Set the value of the given device-specific attribute. ">iio_device_attr_write_longlong()</a></li>
<li><a class="el" href="group__Device.html#ga638c2f54b187a1b137f9885f34fad338" title="Set the value of the given device-specific attribute. ">iio_device_attr_write_double()</a></li>
</ul>
<h1><a class="anchor" id="trigger"></a>
Triggers</h1>
<p>Some devices, mostly low-speed ADCs and DACs, require a trigger to be set for the capture or upload process to work.</p>
<p>In libiio, triggers are just regular <a class="el" href="structiio__device.html" title="Represents a device in the IIO context. ">iio_device</a> objects. To check if a <a class="el" href="structiio__buffer.html" title="An input or output buffer, used to read or write samples. ">iio_buffer</a> can be used as a trigger, you can use <a class="el" href="group__Device.html#ga41582140b8e1fe98148e51ae1350b816" title="Return True if the given device is a trigger. ">iio_device_is_trigger()</a>.</p>
<p>To see if one device is associated with a trigger, use <a class="el" href="group__Device.html#ga9aa22c64b900bf6949a54816a04e7a87" title="Retrieve the trigger of a given device. ">iio_device_get_trigger()</a>.</p>
<p>To assign one trigger to a <a class="el" href="structiio__device.html" title="Represents a device in the IIO context. ">iio_device</a>, you can use <a class="el" href="group__Device.html#ga30151c105a19b3fc3ad6376046d60bf9" title="Associate a trigger to a given device. ">iio_device_set_trigger()</a>. If you want to disassociate a <a class="el" href="structiio__device.html" title="Represents a device in the IIO context. ">iio_device</a> from its trigger, pass NULL to the "trigger" parameter of this function.</p>
<h1><a class="anchor" id="capture_upload"></a>
Capturing or uploading samples</h1>
<p>The process of capturing samples from the hardware and uploading samples to the hardware is done using the functions that apply to the <a class="el" href="structiio__buffer.html" title="An input or output buffer, used to read or write samples. ">iio_buffer</a> object.</p>
<h2><a class="anchor" id="create_buffer"></a>
Enabling channels and creating the Buffer object</h2>
<p>The very first step is to enable the capture channels that we want to use, and disable those that we don't need. This is done with the functions <a class="el" href="group__Channel.html#ga2b787983683d37966b5e1e5c6c121d6a" title="Enable the given channel. ">iio_channel_enable()</a> and <a class="el" href="group__Channel.html#gad7c7c91c61b8a97187dc73cbcdb60c06" title="Disable the given channel. ">iio_channel_disable()</a>. Note that the channels will really be enabled or disabled when the <a class="el" href="structiio__buffer.html" title="An input or output buffer, used to read or write samples. ">iio_buffer</a> object is created.</p>
<p>Also, not all channels can be enabled. To know whether or not one channel can be enabled, use <a class="el" href="group__Channel.html#gad49fb1449e6ed6a42db71696676fd2d3" title="Return True if the given channel is a scan element. ">iio_channel_is_scan_element()</a>.</p>
<p>Once the channels have been enabled, the <a class="el" href="structiio__buffer.html" title="An input or output buffer, used to read or write samples. ">iio_buffer</a> object can be created from the <a class="el" href="structiio__device.html" title="Represents a device in the IIO context. ">iio_device</a> object that will be used, with the function <a class="el" href="group__Buffer.html#ga6caadf077c112ae55a64276aa24ef832" title="Create an input or output buffer associated to the given device. ">iio_device_create_buffer()</a>. This call will fail if no channels have been enabled.</p>
<p>When the object is no more needed, it can be destroyed with <a class="el" href="group__Buffer.html#gaba58dc2780be63fead6f09397ce90d10" title="Destroy the given buffer. ">iio_buffer_destroy()</a>.</p>
<h2><a class="anchor" id="refill"></a>
Refilling the Buffer (input devices only)</h2>
<p>If the Buffer object has been created from a device with input channels, then it must be updated first. This is done with the <a class="el" href="group__Buffer.html#ga1aaecd70bdb441c8faaf061672060516" title="Fetch more samples from the hardware. ">iio_buffer_refill()</a> function.</p>
<h2><a class="anchor" id="read_write"></a>
Reading or writing samples to the Buffer</h2>
<p>Libiio offers various ways to interact with the <a class="el" href="structiio__buffer.html" title="An input or output buffer, used to read or write samples. ">iio_buffer</a> object.</p>
<h3><a class="anchor" id="memcpy"></a>
Direct copy</h3>
<p>If you already have a buffer of samples, correctly interleaved and in the format that the hardware expects, it is possible to copy the samples directly into the <a class="el" href="structiio__buffer.html" title="An input or output buffer, used to read or write samples. ">iio_buffer</a> object using <code>memcpy</code>:</p>
<div class="fragment"><div class="line"><span class="keywordtype">size_t</span> iio_buf_size = <a class="code" href="group__Buffer.html#gab5300f917bbdfc5dafc093a60138f131">iio_buffer_end</a>(buffer) - <a class="code" href="group__Buffer.html#ga7fdacbfda79aa5120f34ea73ae2ea5ab">iio_buffer_start</a>(buffer);</div><div class="line"><span class="keywordtype">size_t</span> count = MAX(<span class="keyword">sizeof</span>(samples_buffer), iio_buf_size);</div><div class="line">memcpy(<a class="code" href="group__Buffer.html#ga7fdacbfda79aa5120f34ea73ae2ea5ab">iio_buffer_start</a>(buffer), samples_buffer, count);</div></div><!-- fragment --><p>Using <code>memcpy</code> to copy samples from the <a class="el" href="structiio__buffer.html" title="An input or output buffer, used to read or write samples. ">iio_buffer</a> is <b>not recommended</b>. When capturing samples from an input device, you cannot assume that the <a class="el" href="structiio__buffer.html" title="An input or output buffer, used to read or write samples. ">iio_buffer</a> object contains only the samples you're interested in.</p>
<h3><a class="anchor" id="iterating_cb"></a>
Iterating over the buffer with a callback</h3>
<p>Libiio provides a way to iterate over the buffer by registering a callback function, with the <a class="el" href="group__Buffer.html#ga8be1b9fa5383746ff8d76cedf1ff0156" title="Call the supplied callback for each sample found in a buffer. ">iio_buffer_foreach_sample()</a> function.</p>
<p>The callback function will be called for each "sample slot" of the buffer, which will contain a valid sample if the buffer has been refilled, or correspond to an area where a sample should be stored if using an output device.</p>
<div class="fragment"><div class="line">ssize_t sample_cb(<span class="keyword">const</span> <span class="keyword">struct</span> <a class="code" href="structiio__channel.html">iio_channel</a> *chn, <span class="keywordtype">void</span> *src, <span class="keywordtype">size_t</span> bytes, <span class="keywordtype">void</span> *d)</div><div class="line">{</div><div class="line">    <span class="comment">/* Use &quot;src&quot; to read or write a sample for this channel */</span></div><div class="line">}</div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">void</span>)</div><div class="line">{</div><div class="line">    ...</div><div class="line">    <a class="code" href="group__Buffer.html#ga8be1b9fa5383746ff8d76cedf1ff0156">iio_buffer_foreach_sample</a>(buffer, sample_cb, NULL);</div><div class="line">    ...</div><div class="line">}</div></div><!-- fragment --><p>Note that the callback will be called in the order that the samples appear in the buffer, and only for samples that correspond to channels that were enabled.</p>
<h3><a class="anchor" id="iterating_for"></a>
Iterating on the samples with a for loop</h3>
<p>This method allows you to iterate over the samples slots that correspond to one channel. As such, it is interesting if you want to process the data channel by channel.</p>
<p>It basically consists in a for loop that uses the functions <a class="el" href="group__Buffer.html#ga000d2f4c8b72060db1c38ec905bf4156" title="Find the first sample of a channel in a buffer. ">iio_buffer_first()</a>, <a class="el" href="group__Buffer.html#ga18d5cb8d912b5b888b9b54c6d0c7f92c" title="Get the step size between two samples of one channel. ">iio_buffer_step()</a> and <a class="el" href="group__Buffer.html#gab5300f917bbdfc5dafc093a60138f131" title="Get the address that follows the last sample in a buffer. ">iio_buffer_end()</a>:</p>
<div class="fragment"><div class="line"><span class="keywordflow">for</span> (<span class="keywordtype">void</span> *ptr = <a class="code" href="group__Buffer.html#ga000d2f4c8b72060db1c38ec905bf4156">iio_buffer_first</a>(buffer, channel);</div><div class="line">           ptr &lt; <a class="code" href="group__Buffer.html#gab5300f917bbdfc5dafc093a60138f131">iio_buffer_end</a>(buffer);</div><div class="line">           ptr += <a class="code" href="group__Buffer.html#ga18d5cb8d912b5b888b9b54c6d0c7f92c">iio_buffer_step</a>(buffer)) {</div><div class="line">    <span class="comment">/* Use &quot;ptr&quot; to read or write a sample for this channel */</span></div><div class="line">}</div></div><!-- fragment --><h3><a class="anchor" id="deinterleave"></a>
Extracting from/to a second buffer</h3>
<p>Finally, it is possible to use the <a class="el" href="group__Channel.html#gaa35f0bbf7f6be8f859adb3fc692c600e">iio_channel_read()</a> and <a class="el" href="group__Channel.html#gabf4e2755877dedae40a5fbeb54a3829e">iio_channel_read_raw()</a> functions to read samples from the <a class="el" href="structiio__buffer.html" title="An input or output buffer, used to read or write samples. ">iio_buffer</a> to a second byte array. The samples will be deinterleaved if needed. The "raw" variant will only deinterleave the samples, while the other variant will deinterleave and convert the samples.</p>
<p>For output devices, the <a class="el" href="group__Channel.html#ga343be1b2a9b4a23aa1ad6e22b5b334b3">iio_channel_write()</a> and <a class="el" href="group__Channel.html#ga0d06dce5819723c3b16c4588eb5f477a">iio_channel_write_raw()</a> functions are also available. The "raw" variant will only interleave the samples (if needed), while the other variant will interleave and convert the samples back to their hardware format.</p>
<h2><a class="anchor" id="convert"></a>
Convert the samples from/to hardware format</h2>
<p>The raw stream of samples generally isn't in a format that can be directly used in algorithms. Some operations, like endianness conversion and bit-shifting of the samples, have to be performed first.</p>
<p>Libiio offers two functions that can be used to convert samples:</p><ul>
<li><a class="el" href="group__Debug.html#gaf910dce06335badc1ba307526c4112a6" title="Convert the sample from hardware format to host format. ">iio_channel_convert()</a>, to convert from the hardware format</li>
<li><a class="el" href="group__Debug.html#gaf0a9a659af18b62ffa0520301402eabb" title="Convert the sample from host format to hardware format. ">iio_channel_convert_inverse()</a>, to convert to the hardware format.</li>
</ul>
<p>Those two functions should always be used when manipulating the samples of the <a class="el" href="structiio__buffer.html" title="An input or output buffer, used to read or write samples. ">iio_buffer</a>. The exception is when <a class="el" href="group__Channel.html#gaa35f0bbf7f6be8f859adb3fc692c600e">iio_channel_read()</a> or <a class="el" href="group__Channel.html#ga343be1b2a9b4a23aa1ad6e22b5b334b3">iio_channel_write()</a> are used, as the conversion is then done internally.</p>
<h2><a class="anchor" id="push"></a>
Submitting the Buffer (output devices only)</h2>
<p>When all the samples have been written to the <a class="el" href="structiio__buffer.html" title="An input or output buffer, used to read or write samples. ">iio_buffer</a> object, you can submit the buffer to the hardware with a call to <a class="el" href="group__Buffer.html#ga28c43d91ddaf8856f2d1a79562072280" title="Send the samples to the hardware. ">iio_buffer_push()</a>. As soon as the buffer has been submitted, it can be re-used to store new samples.</p>
<p>If the <a class="el" href="structiio__buffer.html" title="An input or output buffer, used to read or write samples. ">iio_buffer</a> object has been created with the "cyclic" parameter set, and the kernel driver supports cyclic buffers, the submitted buffer will be repeated until the <a class="el" href="structiio__buffer.html" title="An input or output buffer, used to read or write samples. ">iio_buffer</a> is destroyed, and no subsequent call to <a class="el" href="group__Buffer.html#ga28c43d91ddaf8856f2d1a79562072280" title="Send the samples to the hardware. ">iio_buffer_push()</a> will be allowed.</p>
<h1><a class="anchor" id="advanced"></a>
Advanced options</h1>
<h2><a class="anchor" id="userdata"></a>
Register and retrieve a pointer</h2>
<p>The <a class="el" href="structiio__device.html" title="Represents a device in the IIO context. ">iio_device</a> and <a class="el" href="structiio__channel.html" title="Represents an input or output channel of a device. ">iio_channel</a> allow you to register a pointer, that can then be retrieved at a later moment.</p><ul>
<li>A pointer can be registered with a <a class="el" href="structiio__device.html" title="Represents a device in the IIO context. ">iio_device</a> object using <a class="el" href="group__Device.html#gab566248f50503d8975cf258a1f218275" title="Associate a pointer to an iio_device structure. ">iio_device_set_data()</a>, and can be retrieved with <a class="el" href="group__Device.html#ga87cff8d90e1a68e73410e4a527cc5334" title="Retrieve a previously associated pointer of an iio_device structure. ">iio_device_get_data()</a>.</li>
<li>A pointer can be registered with a <a class="el" href="structiio__channel.html" title="Represents an input or output channel of a device. ">iio_channel</a> object using <a class="el" href="group__Channel.html#ga5150c9b73386d899460ebafbe614f338" title="Associate a pointer to an iio_channel structure. ">iio_channel_set_data()</a>, and can be retrieved with <a class="el" href="group__Channel.html#gacbce92eaefb8d61c1e4f0dc042b211e6" title="Retrieve a previously associated pointer of an iio_channel structure. ">iio_channel_get_data()</a>.</li>
</ul>
<h2><a class="anchor" id="debug_attr"></a>
Debug attributes</h2>
<p>Some IIO devices provide debug parameters, but their presence is optional. In a similar way than with regular device parameters, the number of debug parameters can be obtained with <a class="el" href="group__Debug.html#ga7b73b6fa484da3af7735cd80b90f3464" title="Enumerate the debug attributes of the given device. ">iio_device_get_debug_attrs_count()</a>. Each individual parameter can be retrieved with <a class="el" href="group__Debug.html#gaf64c20583fd66701afcc6c7ba3deb6ea" title="Get the debug attribute present at the given index. ">iio_device_get_debug_attr()</a>. Alternatively, it is possible to lookup for the name of a debug attribute with <a class="el" href="group__Debug.html#ga891aa6ffd6290fc3848e4f14a923d1fb" title="Try to find a debug attribute by its name. ">iio_device_find_debug_attr()</a>.</p>
<p>Those debug parameters can be read using the following functions:</p><ul>
<li><a class="el" href="group__Debug.html#ga2ae0fe2e179de9f6de10900f72fc28be" title="Read the content of the given debug attribute. ">iio_device_debug_attr_read()</a>,</li>
<li><a class="el" href="group__Debug.html#ga4d8f3a846d5df8ee97c91789014dcb16" title="Read the content of all debug attributes. ">iio_device_debug_attr_read_all()</a>,</li>
<li><a class="el" href="group__Debug.html#gac2d887e2f77423596487302d2728c99e" title="Read the content of the given debug attribute. ">iio_device_debug_attr_read_bool()</a>,</li>
<li><a class="el" href="group__Debug.html#gac43421333d85b03e7aeb31eb60a676fe" title="Read the content of the given debug attribute. ">iio_device_debug_attr_read_longlong()</a>,</li>
<li><a class="el" href="group__Debug.html#ga01b435571a0bd034bc47987295821573" title="Read the content of the given debug attribute. ">iio_device_debug_attr_read_double()</a>.</li>
</ul>
<p>Those debug parameters can be written using the following functions:</p><ul>
<li><a class="el" href="group__Debug.html#ga01151f264c7e22fcf8390b5303b51bb3" title="Set the value of the given debug attribute. ">iio_device_debug_attr_write()</a>,</li>
<li><a class="el" href="group__Debug.html#ga08b5346afb0498dc05b123097db1f364" title="Set the values of all debug attributes. ">iio_device_debug_attr_write_all()</a>,</li>
<li><a class="el" href="group__Debug.html#ga2013f7206e2dde3aedee31ba01945585" title="Set the value of the given debug attribute. ">iio_device_debug_attr_write_bool()</a>,</li>
<li><a class="el" href="group__Debug.html#ga83e2e2ef3c9fa91561b41dd32c59194e" title="Set the value of the given debug attribute. ">iio_device_debug_attr_write_longlong()</a>,</li>
<li><a class="el" href="group__Debug.html#ga1d105cd9079c1218c363db75cf504e0d" title="Set the value of the given debug attribute. ">iio_device_debug_attr_write_double()</a>.</li>
</ul>
<h2><a class="anchor" id="registers"></a>
Reading and writing registers</h2>
<p>As for debug attributes, some IIO devices also offer the possibility to read and write hardware registers directly. In libiio, this can be done with two functions, <a class="el" href="group__Debug.html#gaf549d2113214add88129493697cb3587" title="Get the value of a hardware register. ">iio_device_reg_read()</a> and <a class="el" href="group__Debug.html#ga821ace05c0f77bf4f87be7555ae84d52" title="Set the value of a hardware register. ">iio_device_reg_write()</a>. </p>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Sun Feb 7 2016 20:10:46 for libiio by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.11
</small></address>
</body>
</html>

APT Browse - Built by Thomas Orozco.