This file is indexed.

/usr/share/doc/libcomedi-dev/html/commandsstreaming.html is in libcomedi-dev 0.10.2-4build7.

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
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>4.5.  Commands for streaming acquisition</title><link rel="stylesheet" type="text/css" href="comedilib.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="Comedi"><link rel="up" href="acquisitionfunctions.html" title="4.  Acquisition and configuration functions"><link rel="prev" href="inttrigconfiguration.html" title="4.4.  Instruction for internal triggering"><link rel="next" href="slowlyvarying.html" title="4.6.  Slowly-varying inputs"></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">4.5. 
Commands for streaming acquisition
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="inttrigconfiguration.html">Prev</a> </td><th width="60%" align="center">4. 
Acquisition and configuration functions
</th><td width="20%" align="right"> <a accesskey="n" href="slowlyvarying.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="commandsstreaming"></a>4.5. 
Commands for streaming acquisition
</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="commandsstreaming.html#executingcommand">4.5.1. 
Executing a command
</a></span></dt><dt><span class="section"><a href="commandsstreaming.html#comedicmdstructure">4.5.2. 
The command data structure
</a></span></dt><dt><span class="section"><a href="commandsstreaming.html#comedicmdsources">4.5.3. 
The command trigger events

</a></span></dt><dt><span class="section"><a href="commandsstreaming.html#comedicmdflags">4.5.4. 
The command flags

</a></span></dt><dt><span class="section"><a href="commandsstreaming.html#idm1424">4.5.5. 
Anti-aliasing
</a></span></dt></dl></div><p>
The most powerful <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> acquisition primitive is the
<span class="emphasis"><em>command</em></span>. It's powerful because, with one single
command, the programmer launches:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
a possibly infinite <span class="emphasis"><em>sequence of acquisitions</em></span>,
</p></li><li class="listitem"><p>
accompanied with various <span class="emphasis"><em>callback</em></span> functionalities
(DMA, interrupts, driver-specific callback functions),
</p></li><li class="listitem"><p>
for <span class="emphasis"><em>any number of channels</em></span>,
</p></li><li class="listitem"><p>
with an <span class="emphasis"><em>arbitrary order</em></span> of channels in each scan
(possibly even with repeated channels per scan),
</p></li><li class="listitem"><p>
and with various scan <span class="emphasis"><em>triggering sources</em></span>,
external (i.e., hardware pulses) as well as internal (i.e., pulses
generated on the DAQ card itself, or generated by a
<a class="link" href="inttrigconfiguration.html" title="4.4.  Instruction for internal triggering">software trigger instruction</a>).
</p></li></ul></div><p>
This command functionality exists in the <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> API, because various
data acquisition devices have the capability to perform this kind of
complex acquisition, driven by either on-board or
off-board timers and triggers.
</p><p>
A command specifies a particular data
<a class="link" href="index.html#fig-acq-seq" title="Figure 1.  Asynchronous Acquisition Sequence">acquisition sequence</a>, which
consists of a number of <span class="emphasis"><em>scans</em></span>, and each scan is
comprised of a number of <span class="emphasis"><em>conversions</em></span>, which
usually corresponds to a single A/D or D/A conversion. So, for
example, a scan could consist of sampling channels 1, 2 and 3 of a
particular device, and this scan should be repeated 1000 times, at
intervals of 1 millisecond apart.
</p><p>
The command function is complementary to the
<a class="link" href="instructionsconfiguration.html" title="4.3.  Instructions for configuration">configuration instruction</a>
function: each channel in the command's
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-chanlist">chanlist</a></code></em>
should first be configured by an appropriate instruction.
</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="executingcommand"></a>4.5.1. 
Executing a command
</h4></div></div></div><p>
A command is executed by the function
<code class="function"><a class="link" href="func-ref-comedi-command.html" title="comedi_command">comedi_command</a></code>:

</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">comedi_command</b>(</code></td><td>comedi_t *<var class="pdparam">device</var>, </td></tr><tr><td> </td><td>comedi_cmd *<var class="pdparam">command</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>

The following sections explain the meaning of the
<span class="type"><a class="link" href="datatypesstructures.html#ref-type-comedi-cmd" title="5.3.7.  comedi_cmd">comedi_cmd</a></span> data structure.
Filling in this structure can be quite complicated, and
requires good knowledge about the exact functionalities of the DAQ
card.  So, before launching a command, the application programmer is
adviced to check whether this complex command data structure can be
successfully parsed. So, the typical sequence for executing a command is
to first send the command through
<code class="function"><a class="link" href="func-ref-comedi-command-test.html" title="comedi_command_test">comedi_command_test</a></code>
once or twice.  The test will check that the command is valid for the
particular device, and often makes some adjustments to the command
arguments, which can then be read back by the user to see the actual
values used.
</p><p>
A <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> program can find out on-line what the command capabilities
of a specific device are, by means of the
<code class="function"><a class="link" href="func-ref-comedi-get-cmd-src-mask.html" title="comedi_get_cmd_src_mask">comedi_get_cmd_src_mask</a></code>
function.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="comedicmdstructure"></a>4.5.2. 
The command data structure
</h4></div></div></div><p>
The command executes according to the information about the requested
acquisition, which is stored in the
<span class="type"><a class="link" href="datatypesstructures.html#ref-type-comedi-cmd" title="5.3.7.  comedi_cmd">comedi_cmd</a></span>
<a name="command-data-struct"></a>data structure:
</p><pre class="programlisting">
typedef struct comedi_cmd_struct comedi_cmd;

struct comedi_cmd_struct {
  unsigned int subdev;         // which subdevice to sample
  unsigned int <a name="command-data-struct-flags"></a>flags;          // encode some configuration possibilities
                               // of the command execution; e.g.,
                               // whether a callback routine is to be
                               // called at the end of the command

  unsigned int <a name="command-data-struct-start-src"></a>start_src;      // event to make the acquisition start
  unsigned int <a name="command-data-struct-start-arg"></a>start_arg;      // parameters that influence this start

  unsigned int <a name="command-data-struct-scan-begin-src"></a>scan_begin_src; // event to make a particular scan start
  unsigned int <a name="command-data-struct-scan-begin-arg"></a>scan_begin_arg; // parameters that influence this start`

  unsigned int <a name="command-data-struct-convert-src"></a>convert_src;    // event to make a particular conversion start
  unsigned int <a name="command-data-struct-convert-arg"></a>convert_arg;    // parameters that influence this start

  unsigned int <a name="command-data-struct-scan-end-src"></a>scan_end_src;   // event to make a particular scan terminate
  unsigned int <a name="command-data-struct-scan-end-arg"></a>scan_end_arg;   // parameters that influence this termination

  unsigned int <a name="command-data-struct-stop-src"></a>stop_src;       // what make the acquisition terminate
  unsigned int <a name="command-data-struct-stop-arg"></a>stop_arg;       // parameters that influence this termination

  unsigned int <a name="command-data-struct-chanlist"></a>*chanlist;      // pointer to list of channels to be sampled
  unsigned int <a name="command-data-struct-chanlist-len"></a>chanlist_len;   // number of channels to be sampled

  sampl_t *<a name="command-data-struct-data"></a>data;               // address of buffer
  unsigned int <a name="command-data-struct-data-len"></a>data_len;       // number of samples to acquire
};
</pre><p>
The start and end of the whole command acquisition sequence, and the
start and end of each scan and of each conversion, is triggered by a
so-called <span class="emphasis"><em>event</em></span>. More on these in
<a class="xref" href="commandsstreaming.html#comedicmdsources" title="4.5.3.  The command trigger events">Section 4.5.3</a>.
</p><p>
The <em class="parameter"><code>subdev</code></em> member of the
<span class="type"><a class="link" href="datatypesstructures.html#ref-type-comedi-cmd" title="5.3.7.  comedi_cmd">comedi_cmd</a></span> structure is
the index of the subdevice the command is intended for.  The
<code class="function"><a class="link" href="func-ref-comedi-find-subdevice-by-type.html" title="comedi_find_subdevice_by_type">comedi_find_subdevice_by_type</a></code>
function can be useful in discovering the index of your desired subdevice.
</p><p>
The <em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-chanlist">chanlist</a></code></em>
member of the
<span class="type"><a class="link" href="datatypesstructures.html#ref-type-comedi-cmd" title="5.3.7.  comedi_cmd">comedi_cmd</a></span> data
structure should point to an array whose number of elements is
specified by
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-chanlist-len">chanlist_len</a></code></em>
(this will generally be the same as the
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-scan-end-arg">scan_end_arg</a></code></em>).
The
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-chanlist">chanlist</a></code></em>
specifies the sequence of channels and gains (and analog references)
that should be stepped through for each scan.  The elements of the
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-chanlist">chanlist</a></code></em> array should be
initialized by <span class="quote"><span class="quote">packing</span></span> the channel, range and reference
information together with the
<code class="function"><a class="link" href="constantsmacros.html#ref-macro-CR-PACK" title="5.2.1.  CR_PACK">CR_PACK</a></code>
macro.
</p><p>
The <em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-data">data</a></code></em> and
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-data-len">data_len</a></code></em>
members can be safely ignored when issueing commands from a user-space
program.  They only have meaning when a command is sent from a
<span class="strong"><strong>kernel</strong></span> module using the
<code class="systemitem">kcomedilib</code> interface, in which case they specify
the buffer where the driver should write/read its data to/from.
</p><p>
The final member of the
<span class="type"><a class="link" href="commandsstreaming.html#command-data-struct">comedi_cmd</a></span> structure is the
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-flags">flags</a></code></em> field,
i.e., bits in a word that can be bitwise-or'd together. The meaning of
these bits are explained in
<a class="xref" href="commandsstreaming.html#comedicmdflags" title="4.5.4.  The command flags">Section 4.5.4</a>.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="comedicmdsources"></a>4.5.3. 
The command trigger events
<a name="source.trigger.anchor"></a>
</h4></div></div></div><p>
A command is a very versatile acquisition instruction, in the sense
that it offers lots of possibilities to let different hardware and
software sources determine when acquisitions are started, performed,
and stopped. More specifically, the command
<a class="link" href="commandsstreaming.html#command-data-struct">data structure</a>
has <span class="emphasis"><em>five</em></span> types of events: start the
<a class="link" href="index.html#acquisitionterminology" title="1.6.  Acquisition terminology">acquisition</a>,
start a <a class="link" href="index.html#scan">scan</a>, start a
<a class="link" href="index.html#conversion">conversion</a>, stop a scan, and stop
the acquisition.  Each event can be given its own
<span class="emphasis"><em><a class="link" href="commandsstreaming.html#source.trigger.anchor">source</a></em></span>
(the <em class="parameter"><code>…_src</code></em> members in the
<span class="type"><a class="link" href="datatypesstructures.html#ref-type-comedi-cmd" title="5.3.7.  comedi_cmd">comedi_cmd</a></span> data
structure). And each event source can have a corresponding
argument (the <em class="parameter"><code>…_arg</code></em> members of
the <span class="type"><a class="link" href="datatypesstructures.html#ref-type-comedi-cmd" title="5.3.7.  comedi_cmd">comedi_cmd</a></span> data
structure) whose meaning depends on the type of source trigger.
For example, to specify an external digital line <span class="quote"><span class="quote">3</span></span> as a
source (in general, <span class="emphasis"><em>any</em></span> of the five event
sources), you would use
<em class="parameter"><code>src</code></em>=<code class="constant"><a class="link" href="commandsstreaming.html#trig-ext">TRIG_EXT</a></code>
and <em class="parameter"><code>arg</code></em>=<code class="literal">3</code>.
</p><p>
The following paragraphs discuss in somewhat more detail the trigger
event sources(<em class="parameter"><code>…_src</code></em>), and the
corresponding arguments (<em class="parameter"><code>…_arg</code></em>).
</p><p>
The start of an acquisition is controlled by the
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-start-src">start_src</a></code></em> events.
The available options are:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<a name="trig-now-start-src"></a>
<code class="constant">TRIG_NOW</code>: the <span class="quote"><span class="quote">start</span></span> event occurs
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-start-arg">start_arg</a></code></em>
nanoseconds after the command is set up. Currently, only
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-start-arg">start_arg</a></code></em>=<code class="literal">0</code> is
supported.
</p></li><li class="listitem"><p>
<a name="trig-follow-start-src"></a>
<code class="constant">TRIG_FOLLOW</code>:  (For an output device.) The <span class="quote"><span class="quote">start</span></span>
event occurs when data is written to the buffer.
</p></li><li class="listitem"><p>
<a name="trig-ext-start-src"></a>
<code class="constant">TRIG_EXT</code>: the <span class="quote"><span class="quote">start</span></span> event occurs when an
external trigger signal occurs; e.g., a rising edge of a digital line.
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-start-arg">start_arg</a></code></em>
chooses the particular digital line.
</p></li><li class="listitem"><p>
<a name="trig-int-start-src"></a>
<code class="constant">TRIG_INT</code>: the <span class="quote"><span class="quote">start</span></span> event occurs on a <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a>
internal signal, which is typically caused by an
<code class="constant"><a class="link" href="inttrigconfiguration.html#insn-inttrig">INSN_INTTRIG</a></code>
instruction.
</p></li></ul></div><p>
The start of the beginning of each
<a class="link" href="index.html#scan">scan</a> is controlled by the
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-scan-begin-src">scan_begin_src</a></code></em> events.
The available options are:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<a name="trig-timer-start-scan"></a>
<code class="constant">TRIG_TIMER</code>: <span class="quote"><span class="quote">scan begin</span></span>
events occur periodically.  The time between <span class="quote"><span class="quote">scan begin</span></span>
events is
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-scan-begin-arg">scan_begin_arg</a></code></em>
nanoseconds.
</p></li><li class="listitem"><p>
<a name="trig-follow-start-scan"></a>
<code class="constant">TRIG_FOLLOW</code>:  The <span class="quote"><span class="quote">scan begin</span></span>
event occurs immediately after a <span class="quote"><span class="quote">scan end</span></span>
event occurs.
</p></li><li class="listitem"><p>
<a name="trig-ext-start-scan"></a>
<code class="constant">TRIG_EXT</code>: the <span class="quote"><span class="quote">scan begin</span></span>
event occurs when an external trigger signal
occurs; e.g., a rising edge of a digital line.
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-scan-begin-arg">scan_begin_arg</a></code></em>
chooses the particular digital line.
</p></li></ul></div><p>
The
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-scan-begin-arg">scan_begin_arg</a></code></em>
used here may not be supported exactly by the device, but it
will be adjusted to the nearest supported value by
<code class="function"><a class="link" href="func-ref-comedi-command-test.html" title="comedi_command_test">comedi_command_test</a></code>.
</p><p>
The timing between each sample in a
<a class="link" href="index.html#scan">scan</a> is controlled by the
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-convert-src">convert_src</a></code></em>
events.
The available options are:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<a name="convert-trig-timer"></a>
<a name="trig-timer"></a>
<code class="constant">TRIG_TIMER</code>: the conversion events occur periodically.
The time between <span class="quote"><span class="quote">convert</span></span> events is
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-convert-arg">convert_arg</a></code></em>
nanoseconds.
</p></li><li class="listitem"><p>
<a name="convert-trig-ext"></a>
<a name="trig-ext"></a>
<code class="constant">TRIG_EXT</code>: the conversion events occur when an
external trigger signal occurs, e.g., a rising edge of a digital line.
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-convert-arg">convert_arg</a></code></em>
chooses the particular digital line.
</p></li><li class="listitem"><p>
<a name="convert-trig-now"></a>
<a name="trig-now"></a>
<code class="constant">TRIG_NOW</code>: All conversion events in a
<a class="link" href="index.html#scan">scan</a> occur simultaneously.
</p></li></ul></div><p>
The <span class="emphasis"><em>end</em></span> of each scan is almost always specified
by setting the
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-scan-end-src">scan_end_src</a></code></em>
event to
<code class="constant"><a class="link" href="commandsstreaming.html#trig-count">TRIG_COUNT</a></code>,
with the argument being the same as the number of channels in the
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-chanlist">chanlist</a></code></em>.  You
could probably find a device that allows something else, but it would
be strange.
</p><p>
The end of an
<a class="link" href="index.html#acquisitionterminology" title="1.6.  Acquisition terminology">acquisition</a> is
controlled by
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-stop-src">stop_src</a></code></em> event.
The available options are:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<a name="acquisition-end-trig-count"></a>
<a name="trig-count"></a>
<code class="constant">TRIG_COUNT</code>: stop the acquisition after
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-stop-arg">stop_arg</a></code></em>
scans.
</p></li><li class="listitem"><p>
<a name="acquisition-end-trig-none"></a>
<a name="trig-none"></a>
<code class="constant">TRIG_NONE</code>: perform continuous acquisition,
until stopped using
<code class="function"><a class="link" href="func-ref-comedi-cancel.html" title="comedi_cancel">comedi_cancel</a></code>.
</p><p>
Its <em class="structfield"><code>stop_arg</code></em> argument is reserved and should be set to <code class="literal">0</code>.
(<span class="quote"><span class="quote">Reserved</span></span>
means that unspecified things could happen if it is set to something
else but <code class="literal">0</code>.)
</p></li></ul></div><p>
There are a couple of less usual or not yet implemented events:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<a name="trig-time"></a>
<code class="constant">TRIG_TIME</code>:
cause an event to occur at a particular time.
</p><p>
(This event source is reserved for future use.)
</p></li><li class="listitem"><p>
<a name="trigother-event"></a>
<code class="constant">TRIG_OTHER</code>: driver specific event trigger.
</p><p>
This event can be useful as any of the trigger sources.  Its exact
meaning is driver specific, because it implements a feature that
otherwise does not fit into the generic <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> command interface.
Configuration of <code class="constant">TRIG_OTHER</code> features are done by
<code class="constant"><a class="link" href="instructionsconfiguration.html" title="4.3.  Instructions for configuration">INSN_CONFIG</a></code>
instructions.
</p><p>
The argument is reserved and should be set to <code class="literal">0</code>.
</p></li></ul></div><p>
Not all event sources are applicable to all events.  Supported
trigger sources for specific events depend significantly on your
particular device, and even more on the current state of its device
driver. The
<code class="function"><a class="link" href="func-ref-comedi-get-cmd-src-mask.html" title="comedi_get_cmd_src_mask">comedi_get_cmd_src_mask</a></code>
function is useful for determining what trigger sources a subdevice
supports.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="comedicmdflags"></a>4.5.4. 
The command flags
<a name="source.flags.anchor"></a>
</h4></div></div></div><p>
The
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-flags">flags</a></code></em>
field in the
<a class="link" href="datatypesstructures.html#ref-type-comedi-cmd" title="5.3.7.  comedi_cmd">command data structure</a>
is used to specify some <span class="quote"><span class="quote">behaviour</span></span> of the acquisitions in
a command.
The meaning of the field is as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<a name="trig-rt"></a>
<code class="constant">TRIG_RT</code>: ask the driver to use a
<span class="strong"><strong>hard real-time</strong></span> interrupt handler.
This will reduce latency in handling interrupts from your data
aquisition
hardware.  It can be useful if you are sampling at high frequency, or
if your hardware has a small onboard data buffer.  You must have a
real-time kernel (<a class="ulink" href="http://www.rtai.org" target="_top">RTAI</a> or
<a class="ulink" href="http://www.rtlinux-gpl.org/" target="_top">RTLinux/GPL</a>)
and must compile <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> with real-time support, or this flag will do
nothing.
</p></li><li class="listitem"><p>
<a name="trig-wake-eos"></a>
<code class="constant">TRIG_WAKE_EOS</code>:
where <span class="quote"><span class="quote">EOS</span></span> stands for <span class="quote"><span class="quote">End of Scan</span></span>. Some
drivers will change their behaviour when this flag is set, trying to
transfer data at the end of every scan (instead of, for example,
passing data in chunks whenever the board's hardware data buffer is
half full).  This flag may degrade a driver's performance at high
frequencies, because the end of a scan is, in general, a much more
frequent event than the filling up of the data buffer.
</p></li><li class="listitem"><p>
<a name="trig-round-nearest"></a>
<code class="constant">TRIG_ROUND_NEAREST</code>:
round to nearest supported timing period, the default.
This flag (as well as the following three), indicates how timing
arguments should be rounded if the hardware cannot achieve the exact
timing requested.
</p></li><li class="listitem"><p>
<a name="trig-round-down"></a>
<code class="constant">TRIG_ROUND_DOWN</code>: round period down.
</p></li><li class="listitem"><p>
<a name="trig-round-up"></a>
<code class="constant">TRIG_ROUND_UP</code>: round period up.
</p></li><li class="listitem"><p>
<a name="trig-round-up-next"></a>
<code class="constant">TRIG_ROUND_UP_NEXT</code>:
this one doesn't do anything, and I don't know what it was intended
to do…?
</p></li><li class="listitem"><p>
<a name="trig-dither"></a>
<code class="constant">TRIG_DITHER</code>: enable dithering? Dithering is
a software technique to smooth the influence of discretization
<span class="quote"><span class="quote">noise</span></span>.
</p></li><li class="listitem"><p>
<a name="trig-deglitch"></a>
<code class="constant">TRIG_DEGLITCH</code>: enable deglitching?
Another <span class="quote"><span class="quote">noise</span></span> smoothing technique.
</p></li><li class="listitem"><p>
<a name="trig-write"></a>
<code class="constant">TRIG_WRITE</code>:
write to bidirectional devices.  Could be useful, in principle, if
someone wrote a driver that supported commands for a digital I/O
device that could do either input or output.
</p></li><li class="listitem"><p>
<a name="trig-bogus"></a>
<code class="constant">TRIG_BOGUS</code>: do the motions?
</p></li><li class="listitem"><p>
<a name="trig-other"></a>
<code class="constant">TRIG_CONFIG</code>: perform configuration, not triggering.
This is a legacy of the deprecated
<span class="type"><a class="link" href="datatypesstructures.html#ref-type-comedi-trig" title="5.3.5.  comedi_trig (deprecated)">comedi_trig_struct</a></span>
data structure, and has no function at present.
</p></li></ul></div><p>
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="idm1424"></a>4.5.5. 
Anti-aliasing
</h4></div></div></div><p>
If you wish to aquire accurate waveforms, it is vital that you use an
anti-alias filter.  An anti-alias filter is a low-pass filter used to
remove all    frequencies higher than the Nyquist frequency (half your sampling rate)
from your analog input signal
before you convert it to digital.  If you fail to filter your input signal,
any high frequency components in the original analog signal will create
artifacts in your recorded    digital waveform that cannot be corrected.
</p><p>
For example, suppose you are sampling an analog input channel at a rate of
1000 Hz.  If you were to apply a 900 Hz sine wave to the input, you
would find that your
sampling rate is not high enough to faithfully record the 900 Hz input,
since it is above your Nyquist frequency of 500 Hz.  Instead, what you
will see in your recorded digital waveform is a 100 Hz sine wave!  If you
don't use an anti-alias filter, it is impossible to tell whether the 100
Hz sine wave you see in your digital signal was really produced by a
100 Hz input signal, or a 900 Hz signal aliased to 100 Hz, or a 1100 Hz
signal, etc.
</p><p>
In practice, the cutoff frequency for the anti-alias filter is usually
set 10% to 20% below the Nyquist frequency due to fact that real filters
do not have infinitely sharp cutoffs.
</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="inttrigconfiguration.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="acquisitionfunctions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="slowlyvarying.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.4. 
Instruction for internal triggering
 </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 4.6. 
Slowly-varying inputs
</td></tr></table></div></body></html>