« back to all changes in this revision
Viewing changes to doc/doc_html/x621.html
- browse files at revision 3
- compare with another revision
- download diff
- download tarball
- view history from revision 3
- Committer: Bazaar Package Importer
- Author(s): David Schleef
- Date: 2004-11-04 11:43:51 UTC
- mfrom: (1.1.1 upstream)
- Revision ID: james.westby@ubuntu.com-20041104114351-a50kaei5yamka8r6
Tags: 0.7.22-2
It helps if the shared library is actually in the package.
- files added:
- autogen.sh
- doc/doc_html
- etc/hotplug
- etc/hotplug/usb
- etc/hotplug/usb/usbdux
- scxi
- swig
- swig/python
- swig/ruby
- swig/ruby/demo
- swig/ruby/ext
- swig/ruby/lib
- files removed:
- debian/ChangeLog
- doc/html
- python
- files modified:
- INSTALL
added
removed
doc/doc_html/x621.html
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
<HTML
3
><HEAD
4
><TITLE
5
>Acquisition and configuration functions</TITLE
6
><META
7
NAME="GENERATOR"
8
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
9
REL="HOME"
10
TITLE=" Comedi
11
"
12
HREF="index.html"><LINK
13
REL="PREVIOUS"
14
TITLE="Writing Comedi programs"
15
HREF="x403.html"><LINK
16
REL="NEXT"
17
TITLE="Writing a Comedi driver"
18
HREF="x1283.html"></HEAD
19
><BODY
20
CLASS="SECTION"
21
BGCOLOR="#FFFFFF"
22
TEXT="#000000"
23
LINK="#0000FF"
24
VLINK="#840084"
25
ALINK="#0000FF"
26
><DIV
27
CLASS="NAVHEADER"
28
><TABLE
29
SUMMARY="Header navigation table"
30
WIDTH="100%"
31
BORDER="0"
32
CELLPADDING="0"
33
CELLSPACING="0"
34
><TR
35
><TH
36
COLSPAN="3"
37
ALIGN="center"
38
>Comedi: The <SPAN
39
CLASS="emphasis"
40
><I
41
CLASS="EMPHASIS"
42
>Control and Measurement Device Interface</I
43
></SPAN
44
>
45
handbook
46
</TH
47
></TR
48
><TR
49
><TD
50
WIDTH="10%"
51
ALIGN="left"
52
VALIGN="bottom"
53
><A
54
HREF="x403.html"
55
ACCESSKEY="P"
56
>Prev</A
57
></TD
58
><TD
59
WIDTH="80%"
60
ALIGN="center"
61
VALIGN="bottom"
62
></TD
63
><TD
64
WIDTH="10%"
65
ALIGN="right"
66
VALIGN="bottom"
67
><A
68
HREF="x1283.html"
69
ACCESSKEY="N"
70
>Next</A
71
></TD
72
></TR
73
></TABLE
74
><HR
75
ALIGN="LEFT"
76
WIDTH="100%"></DIV
77
><DIV
78
CLASS="SECTION"
79
><H1
80
CLASS="SECTION"
81
><A
82
NAME="ACQUISITIONFUNCTIONS"
83
>4. Acquisition and configuration functions</A
84
></H1
85
><P
86
>This Section gives an overview of all <ACRONYM
87
CLASS="ACRONYM"
88
>Comedi</ACRONYM
89
> functions with which
90
application programmers can implement their data acquisition. (With
91
<SPAN
92
CLASS="QUOTE"
93
>"acquisition"</SPAN
94
> we mean all possible kinds of interfacing
95
with the cards: input, output, configuration, streaming, etc.)
96
<A
97
HREF="x3563.html"
98
>Section 7</A
99
> explains the function calls in full
100
detail.</P
101
><DIV
102
CLASS="SECTION"
103
><H2
104
CLASS="SECTION"
105
><A
106
NAME="SINGLEACQUISITION"
107
>4.1. Functions for single acquisition</A
108
></H2
109
><P
110
>The simplest form of using <ACRONYM
111
CLASS="ACRONYM"
112
>Comedi</ACRONYM
113
> is to get one single sample to or
114
from an interface card. This sections explains how to do such simple
115
<A
116
HREF="x621.html#DIO"
117
>digital</A
118
> and
119
<A
120
HREF="x621.html#SINGLEANALOG"
121
>analog</A
122
> acquisitions.</P
123
><DIV
124
CLASS="SECTION"
125
><H3
126
CLASS="SECTION"
127
><A
128
NAME="DIO"
129
>4.1.1. Single digital acquisition</A
130
></H3
131
><P
132
>Many boards supported by <ACRONYM
133
CLASS="ACRONYM"
134
>Comedi</ACRONYM
135
> have digital input and output
136
channels; i.e., channels that can only produce a <VAR
137
CLASS="LITERAL"
138
>0</VAR
139
>
140
or a <VAR
141
CLASS="LITERAL"
142
>1</VAR
143
>.
144
Some boards allow the <SPAN
145
CLASS="emphasis"
146
><I
147
CLASS="EMPHASIS"
148
>direction</I
149
></SPAN
150
> (input or output)
151
of each channel to be specified independently in software.</P
152
><P
153
><ACRONYM
154
CLASS="ACRONYM"
155
>Comedi</ACRONYM
156
> groups digital channels into a
157
<SPAN
158
CLASS="emphasis"
159
><I
160
CLASS="EMPHASIS"
161
>subdevice</I
162
></SPAN
163
>, which is a group of digital channels
164
that have the same characteristics. For example, digital output lines
165
will be grouped into a digital
166
output subdevice, bidirectional digital lines will be grouped
167
into a digital I/O subdevice. Thus, there can be multiple
168
digital subdevices on a particular board.</P
169
><P
170
>Individual bits on a digital I/O device can be read and written using
171
the functions
172
<PRE
173
CLASS="PROGRAMLISTING"
174
> int <A
175
HREF="r4644.html"
176
>comedi_dio_read</A
177
>(device,subdevice,channel,unsigned int *bit);
178
int <A
179
HREF="r4670.html"
180
>comedi_dio_write</A
181
>(device,subdevice,channel,unsigned int bit);</PRE
182
>
183
The <VAR
184
CLASS="PARAMETER"
185
>device</VAR
186
> parameter is a
187
<A
188
HREF="x3563.html#REF-TYPE-COMEDI-T"
189
>pointer</A
190
>
191
to a successfully opened <ACRONYM
192
CLASS="ACRONYM"
193
>Comedi</ACRONYM
194
> device.
195
The <VAR
196
CLASS="PARAMETER"
197
>subdevice</VAR
198
> and
199
<VAR
200
CLASS="PARAMETER"
201
>channel</VAR
202
> parameters are positive
203
integers that indicate which subdevice and channel is used in the
204
acquisition. The integer <VAR
205
CLASS="PARAMETER"
206
>bit</VAR
207
>
208
contains the value of the acquired bit.</P
209
><P
210
>The direction of bidirectional lines can be configured using
211
the function
212
<PRE
213
CLASS="PROGRAMLISTING"
214
> <A
215
HREF="r4617.html"
216
>comedi_dio_config</A
217
>(device,subdevice,channel,unsigned int dir);</PRE
218
>
219
The parameter <VAR
220
CLASS="PARAMETER"
221
>dir</VAR
222
> should be
223
either <VAR
224
CLASS="LITERAL"
225
>COMEDI_INPUT</VAR
226
> or
227
<VAR
228
CLASS="LITERAL"
229
>COMEDI_OUTPUT</VAR
230
>.
231
Many digital I/O subdevices group channels into blocks for
232
configuring direction. Changing one channel in a block changes
233
the entire block.</P
234
><P
235
>Multiple channels can be read and written simultaneously using the
236
function
237
<PRE
238
CLASS="PROGRAMLISTING"
239
> <A
240
HREF="r4696.html"
241
>comedi_dio_bitfield</A
242
>(device,subdevice,unsigned int write_mask,unsigned int *bits);</PRE
243
>
244
Each channel is assigned to a bit in the
245
<VAR
246
CLASS="PARAMETER"
247
>write_mask</VAR
248
> and
249
<VAR
250
CLASS="PARAMETER"
251
>bits</VAR
252
>
253
bitfield. If a bit in
254
<VAR
255
CLASS="PARAMETER"
256
>write_mask</VAR
257
> is set, the
258
corresponding bit in <VAR
259
CLASS="PARAMETER"
260
>*bits</VAR
261
> will
262
be written to the corresponding digital output line.
263
Each digital line is then read and placed into
264
<VAR
265
CLASS="PARAMETER"
266
>*bits</VAR
267
>. The value
268
of bits in <VAR
269
CLASS="PARAMETER"
270
>*bits</VAR
271
> corresponding
272
to digital output lines is undefined and device-specific. Channel
273
<VAR
274
CLASS="LITERAL"
275
>0</VAR
276
> is the least significant bit in the bitfield;
277
channel <VAR
278
CLASS="LITERAL"
279
>31</VAR
280
> is the most significant bit. Channels
281
higher than <VAR
282
CLASS="LITERAL"
283
>31</VAR
284
> cannot be accessed using this method.</P
285
><P
286
>The digital acquisition functions seem to be very simple, but, behind
287
the implementation screens of the <ACRONYM
288
CLASS="ACRONYM"
289
>Comedi</ACRONYM
290
> kernel module, they are
291
executed as special cases of the general
292
<A
293
HREF="x621.html#INSTRUCTIONS"
294
>instruction</A
295
> command.</P
296
></DIV
297
><DIV
298
CLASS="SECTION"
299
><H3
300
CLASS="SECTION"
301
><A
302
NAME="SINGLEANALOG"
303
>4.1.2. Single analog acquisition</A
304
></H3
305
><P
306
>Analog <ACRONYM
307
CLASS="ACRONYM"
308
>Comedi</ACRONYM
309
> channels can produce data values that are
310
<SPAN
311
CLASS="emphasis"
312
><I
313
CLASS="EMPHASIS"
314
>samples</I
315
></SPAN
316
> from continuous analog signals.
317
These samples are integers with a significant content in
318
the range of, typically, <VAR
319
CLASS="LITERAL"
320
>8</VAR
321
>, <VAR
322
CLASS="LITERAL"
323
>10</VAR
324
>,
325
<VAR
326
CLASS="LITERAL"
327
>12</VAR
328
>, or <VAR
329
CLASS="LITERAL"
330
>16</VAR
331
> bits.</P
332
><P
333
>The
334
<PRE
335
CLASS="PROGRAMLISTING"
336
> int <A
337
HREF="r4493.html"
338
>comedi_data_read</A
339
>(<A
340
HREF="x3563.html#REF-TYPE-COMEDI-T"
341
>comedi_t</A
342
> * device, unsigned int subdevice, unsigned int channel,
343
unsigned int range, unsigned int aref, <A
344
HREF="x3563.html#REF-TYPE-LSAMPL-T"
345
>lsampl_t</A
346
> * data);</PRE
347
>
348
function reads one such data value from a <ACRONYM
349
CLASS="ACRONYM"
350
>Comedi</ACRONYM
351
> channel, and puts it in
352
the user-specified <VAR
353
CLASS="PARAMETER"
354
>data</VAR
355
> buffer. The
356
<PRE
357
CLASS="PROGRAMLISTING"
358
> int <A
359
HREF="r4586.html"
360
>comedi_data_write</A
361
>(<A
362
HREF="x3563.html#REF-TYPE-COMEDI-T"
363
>comedi_t</A
364
> * device, unsigned int subdevice, unsigned int channel,
365
unsigned int range, unsigned int aref, <A
366
HREF="x3563.html#REF-TYPE-LSAMPL-T"
367
>lsampl_t</A
368
> data);</PRE
369
>
370
works in the opposite direction. Data values returned by this function
371
are unsigned integers less than, or equal to, the maximum sample value
372
of the channel, which can be determined using the function
373
<PRE
374
CLASS="PROGRAMLISTING"
375
> <A
376
HREF="x3563.html#REF-TYPE-LSAMPL-T"
377
>lsampl_t</A
378
> <A
379
HREF="r4166.html"
380
>comedi_get_maxdata</A
381
>(<A
382
HREF="x3563.html#REF-TYPE-COMEDI-T"
383
>comedi_t</A
384
> * device, unsigned int subdevice, unsigned int channel);</PRE
385
>
386
Conversion of data values to physical units can be performed by the
387
function
388
<PRE
389
CLASS="PROGRAMLISTING"
390
> double <A
391
HREF="r4444.html"
392
>comedi_to_phys</A
393
>(<A
394
HREF="x3563.html#REF-TYPE-LSAMPL-T"
395
>lsampl_t</A
396
> data, comedi_range * range, <A
397
HREF="x3563.html#REF-TYPE-LSAMPL-T"
398
>lsampl_t</A
399
> maxdata);</PRE
400
>
401
There are two data structures in these commands that are not fully
402
self-explanatory:
403
<P
404
></P
405
><UL
406
><LI
407
><P
408
><A
409
HREF="x3563.html#REF-TYPE-COMEDI-T"
410
>comedi_t</A
411
>: this data structure
412
contains all information that a user program has to know about an
413
<SPAN
414
CLASS="emphasis"
415
><I
416
CLASS="EMPHASIS"
417
>open</I
418
></SPAN
419
> <ACRONYM
420
CLASS="ACRONYM"
421
>Comedi</ACRONYM
422
> device. The programmer doesn't have
423
to fill in this data structure manually: it gets filled in by opening
424
the device.</P
425
></LI
426
><LI
427
><P
428
><A
429
HREF="x3563.html#REF-TYPE-LSAMPL-T"
430
>lsampl_t</A
431
>: this
432
<SPAN
433
CLASS="QUOTE"
434
>"data structure"</SPAN
435
> represents one single sample. On most
436
architectures, it's nothing more than a 32 bits value. Internally,
437
<ACRONYM
438
CLASS="ACRONYM"
439
>Comedi</ACRONYM
440
> does some conversion from raw sample data to
441
<SPAN
442
CLASS="QUOTE"
443
>"correct"</SPAN
444
> integers. This is called <SPAN
445
CLASS="QUOTE"
446
>"data
447
munging"</SPAN
448
>.</P
449
></LI
450
></UL
451
></P
452
><P
453
>Each single acquisition by, for example,
454
<CODE
455
CLASS="FUNCTION"
456
> <A
457
HREF="r4493.html"
458
>comedi_data_read()</A
459
></CODE
460
>
461
requires quite some overhead, because all the arguments of the
462
function call are checked. If multiple acquisitions must be done on
463
the same channel, this overhead can be avoided by using a function
464
that can read more than one sample:
465
<PRE
466
CLASS="PROGRAMLISTING"
467
> int <A
468
HREF="r4644.html"
469
>comedi_data_read_n</A
470
>(<A
471
HREF="x3563.html#REF-TYPE-COMEDI-T"
472
>comedi_t</A
473
> *it, unsigned int subdev, unsigned int chan, unsigned int range,
474
unsigned int aref, <A
475
HREF="x3563.html#REF-TYPE-LSAMPL-T"
476
>lsampl_t</A
477
> *data, unsigned int n)</PRE
478
>
479
The number of samples, <VAR
480
CLASS="PARAMETER"
481
>n</VAR
482
>, is
483
limited by the <ACRONYM
484
CLASS="ACRONYM"
485
>Comedi</ACRONYM
486
> implementation (to a maximum of 100 samples),
487
because the call is blocking.</P
488
><P
489
>The start of the data acquisition can also be delayed by a specified
490
number of nano-seconds:
491
<PRE
492
CLASS="PROGRAMLISTING"
493
>int <A
494
HREF="r4526.html"
495
>comedi_data_read_delayed</A
496
>(<A
497
HREF="x3563.html#REF-TYPE-COMEDI-T"
498
>comedi_t</A
499
> *it, unsigned int subdev, unsigned int chan, unsigned int range,
500
unsigned int aref, <A
501
HREF="x3563.html#REF-TYPE-LSAMPL-T"
502
>lsampl_t</A
503
> *data, unsigned int nano_sec)</PRE
504
>
505
All these read and write acquisition functions are implemented on top
506
of the generic <A
507
HREF="x621.html#INSTRUCTIONS"
508
>instruction</A
509
>
510
command.</P
511
></DIV
512
></DIV
513
><DIV
514
CLASS="SECTION"
515
><H2
516
CLASS="SECTION"
517
><A
518
NAME="INSTRUCTIONS"
519
>4.2. Instructions for multiple acquisitions</A
520
></H2
521
><P
522
>The <SPAN
523
CLASS="emphasis"
524
><I
525
CLASS="EMPHASIS"
526
>instruction</I
527
></SPAN
528
> is one of the most generic,
529
overloaden and flexible functions in the <ACRONYM
530
CLASS="ACRONYM"
531
>Comedi</ACRONYM
532
> API. It is used to
533
execute a multiple of identical acquisitions on the same channel, but
534
also to perform a
535
<A
536
HREF="x621.html#INSTRUCTIONSCONFIGURATION"
537
>configuration</A
538
> of a
539
channel.
540
<A
541
NAME="ANCHOR.INSTRUCTION.LIST"
542
></A
543
>
544
An <SPAN
545
CLASS="emphasis"
546
><I
547
CLASS="EMPHASIS"
548
>instruction list</I
549
></SPAN
550
> is a list of instructions,
551
possibly on different channels. Both instructions and instructions
552
lists are executed <SPAN
553
CLASS="emphasis"
554
><I
555
CLASS="EMPHASIS"
556
>synchronously</I
557
></SPAN
558
>, i.e., while
559
<SPAN
560
CLASS="strong"
561
><B
562
CLASS="EMPHASIS"
563
>blocking</B
564
></SPAN
565
> the calling process.
566
This is one of the limitations of instructions; the other one is that
567
they cannot code an acquisition involving timers or external events.
568
These limits are eliminated by the
569
<A
570
HREF="x621.html#COMMANDSSTREAMING"
571
>command</A
572
> acquisition
573
primitive.</P
574
><DIV
575
CLASS="SECTION"
576
><H3
577
CLASS="SECTION"
578
><A
579
NAME="COMEDIINSNSTRUCTURE"
580
>4.2.1. The instruction data structure</A
581
></H3
582
><P
583
>All the information needed to execute an instruction is stored in the
584
<A
585
HREF="x3563.html#REF-TYPE-COMEDI-INSN"
586
>comedi_insn</A
587
>
588
data structure:
589
<PRE
590
CLASS="PROGRAMLISTING"
591
>struct <A
592
NAME="INSN-DATA-STRUCTURE"
593
></A
594
>comedi_insn_struct{
595
<A
596
NAME="INSN-DATA-STRUCTURE-INSN"
597
></A
598
>unsigned int insn; // integer encoding the type of acquisition
599
// (or configuration)
600
unsigned int n; // number of samples
601
<A
602
HREF="x3563.html#REF-TYPE-LSAMPL-T"
603
>lsampl_t</A
604
> <A
605
NAME="INSN-DATA-STRUCTURE-DATA"
606
></A
607
>*data; // pointer to data buffer
608
unsigned int subdev; // subdevice
609
unsigned int <A
610
NAME="INSN-DATA-STRUCTURE-CHANSPEC"
611
></A
612
><A
613
HREF="x3563.html#REF-MACRO-CR-PACK"
614
>chanspec</A
615
>; // encoded channel specification
616
unsigned int unused[3];
617
} comedi_insn;</PRE
618
>
619
Because of the large flexibility of the instruction function, many
620
types of instruction do not need to fill in all fields, or attach
621
different meanings to the same field. But the current implementation
622
of <ACRONYM
623
CLASS="ACRONYM"
624
>Comedi</ACRONYM
625
> requires the
626
<A
627
HREF="x621.html#INSN-DATA-STRUCTURE-DATA"
628
>data</A
629
> field to be at
630
least one byte long.</P
631
><P
632
>The <A
633
HREF="x621.html#INSN-DATA-STRUCTURE-INSN"
634
>insn</A
635
> flag of the
636
<A
637
HREF="x621.html#INSN-DATA-STRUCTURE"
638
>instruction data structure</A
639
>
640
determines the type of acquisition executed in the corresponding
641
instruction:
642
<P
643
></P
644
><UL
645
><LI
646
><P
647
>INSN_READ: the instruction executes a read on an analog channel.</P
648
></LI
649
><LI
650
><P
651
>INSN_WRITE: the instruction executes a write on an analog channel. </P
652
></LI
653
><LI
654
><P
655
>INSN_BITS: indicates that the instruction must
656
read or write values on multiple digital I/O channels.</P
657
></LI
658
><LI
659
><P
660
>INSN_GTOD: the instruction performs a <SPAN
661
CLASS="QUOTE"
662
>"Get Time Of Day"</SPAN
663
>
664
acquisition.</P
665
></LI
666
><LI
667
><P
668
>INSN_WAIT: the instruction blocks for a specified number of
669
nanoseconds.</P
670
></LI
671
></UL
672
></P
673
></DIV
674
><DIV
675
CLASS="SECTION"
676
><H3
677
CLASS="SECTION"
678
><A
679
NAME="INSTRUCTIONEXECUTION"
680
>4.2.2. Instruction execution</A
681
></H3
682
><P
683
>Once an instruction data structure has been filled in, the
684
corresponding instruction is executed as follows:
685
<PRE
686
CLASS="PROGRAMLISTING"
687
> int <A
688
HREF="r4381.html"
689
>comedi_do_insn</A
690
>(<A
691
HREF="x3563.html#REF-TYPE-COMEDI-T"
692
>comedi_t</A
693
> *it, <A
694
HREF="x3563.html#REF-TYPE-COMEDI-INSN"
695
>comedi_insn</A
696
> * instruction);</PRE
697
>
698
Many <ACRONYM
699
CLASS="ACRONYM"
700
>Comedi</ACRONYM
701
> instructions are shortcuts that relieve the programmer
702
from explicitly filling in the data structure and calling the
703
<A
704
HREF="r4381.html"
705
>comedi_do_insn</A
706
>
707
function.</P
708
><P
709
>The
710
<PRE
711
CLASS="PROGRAMLISTING"
712
> int <A
713
HREF="r4356.html"
714
>comedi_do_insnlist</A
715
><A
716
HREF="x3563.html#REF-TYPE-COMEDI-T"
717
>comedi_t</A
718
> *it, <A
719
HREF="x3563.html#REF-TYPE-COMEDI-INSNLIST"
720
>comedi_insnlist</A
721
> * list)</PRE
722
>
723
instruction allows to perform a list of instructions in one function
724
call. The number of instructions in the list is limited in the
725
implementation, because instructions are executed
726
<SPAN
727
CLASS="emphasis"
728
><I
729
CLASS="EMPHASIS"
730
>synchronously</I
731
></SPAN
732
>, i.e., the call blocks until the
733
whole instruction (list) has finished.</P
734
></DIV
735
></DIV
736
><DIV
737
CLASS="SECTION"
738
><H2
739
CLASS="SECTION"
740
><A
741
NAME="INSTRUCTIONSCONFIGURATION"
742
>4.3. Instructions for configuration</A
743
></H2
744
><P
745
><A
746
HREF="x621.html#INSTRUCTIONS"
747
>Section 4.2</A
748
> explains how instructions are used to do
749
<SPAN
750
CLASS="emphasis"
751
><I
752
CLASS="EMPHASIS"
753
>acquisition</I
754
></SPAN
755
> on channels. This section explains
756
how they are used to <SPAN
757
CLASS="emphasis"
758
><I
759
CLASS="EMPHASIS"
760
>configure</I
761
></SPAN
762
> a device.
763
There are various sorts of configurations, and the
764
specific information for each different configuration possibility is
765
to be specified via the
766
<A
767
HREF="x621.html#INSN-DATA-STRUCTURE-DATA"
768
>data</A
769
> buffer of the
770
<A
771
HREF="x621.html#INSN-DATA-STRUCTURE"
772
>instruction data structure</A
773
>.
774
(So, the pointer to a
775
<A
776
HREF="x3563.html#REF-TYPE-LSAMPL-T"
777
>lsampl_t</A
778
>
779
is misused as a pointer to an array with board-specific information.)</P
780
><P
781
>Using INSN_CONFIG as the
782
<A
783
HREF="x621.html#INSN-DATA-STRUCTURE-INSN"
784
>insn</A
785
> flag in an
786
<A
787
HREF="x621.html#INSN-DATA-STRUCTURE"
788
>instruction data structure</A
789
>
790
indicates that the instruction will
791
<SPAN
792
CLASS="emphasis"
793
><I
794
CLASS="EMPHASIS"
795
>not perform acquisition</I
796
></SPAN
797
> on a
798
channel, but will <SPAN
799
CLASS="emphasis"
800
><I
801
CLASS="EMPHASIS"
802
>configure</I
803
></SPAN
804
> that channel.
805
For example, the configuration of digital I/O channels is done as
806
follows. The
807
<A
808
HREF="x3563.html#REF-MACRO-CR-PACK"
809
>chanspec</A
810
> field in the
811
<A
812
HREF="x621.html#INSN-DATA-STRUCTURE-CHANSPEC"
813
>comedi_insn</A
814
>
815
data structure, contains the channel to be configured. And
816
<A
817
HREF="x621.html#INSN-DATA-STRUCTURE-DATA"
818
>data</A
819
>[0] contains
820
either COMEDI_INPUT or COMEDI_OUTPUT, depending on the desired
821
direction of the digital I/O lines.
822
On typical devices, multiple channels are grouped together in blocks
823
for determining their direction. And configuring one channel in a
824
block configures the entire block.</P
825
><P
826
>Another example of an INSN_CONFIG instruction is the configuration of
827
the <A
828
HREF="x621.html#TRIGOTHER-EVENT"
829
>TRIG_OTHER</A
830
> event source.</P
831
></DIV
832
><DIV
833
CLASS="SECTION"
834
><H2
835
CLASS="SECTION"
836
><A
837
NAME="INTTRIGCONFIGURATION"
838
>4.4. Instruction for internal triggering</A
839
></H2
840
><P
841
>This special instruction has
842
<A
843
NAME="INSN-INTTRIG"
844
></A
845
>INSN_INTTRIG as the
846
<A
847
HREF="x621.html#INSN-DATA-STRUCTURE-INSN"
848
>insn</A
849
> flag in its
850
<A
851
HREF="x621.html#INSN-DATA-STRUCTURE"
852
>instruction data structure</A
853
>.
854
Its execution causes an
855
<A
856
HREF="x621.html#TRIG-INT-START-SRC"
857
>internal triggering event</A
858
>. This
859
event can, for example, cause the device driver to start a conversion,
860
or to stop an ongoing acquisition. The exact meaning of the triggering
861
depends on the card and its particular driver.</P
862
><P
863
>The
864
<A
865
HREF="x621.html#INSN-DATA-STRUCTURE-DATA"
866
>data</A
867
>[0] field of the
868
INSN_INTTRIG instruction is reserved for future use, and should be set
869
to <SPAN
870
CLASS="QUOTE"
871
>"0"</SPAN
872
>.</P
873
></DIV
874
><DIV
875
CLASS="SECTION"
876
><H2
877
CLASS="SECTION"
878
><A
879
NAME="COMMANDSSTREAMING"
880
>4.5. Commands for streaming acquisition</A
881
></H2
882
><P
883
>The most powerful <ACRONYM
884
CLASS="ACRONYM"
885
>Comedi</ACRONYM
886
> acquisition primitive is the
887
<SPAN
888
CLASS="emphasis"
889
><I
890
CLASS="EMPHASIS"
891
>command</I
892
></SPAN
893
>. It's powerful because, with one single
894
command, the programmer launches:
895
<P
896
></P
897
><UL
898
><LI
899
><P
900
>a possibly infinite <SPAN
901
CLASS="emphasis"
902
><I
903
CLASS="EMPHASIS"
904
>sequence of acquisitions</I
905
></SPAN
906
>,</P
907
></LI
908
><LI
909
><P
910
>accompanied with various <SPAN
911
CLASS="emphasis"
912
><I
913
CLASS="EMPHASIS"
914
>callback</I
915
></SPAN
916
> functionalities
917
(DMA, interrupts, driver-specific callback functions), </P
918
></LI
919
><LI
920
><P
921
>for <SPAN
922
CLASS="emphasis"
923
><I
924
CLASS="EMPHASIS"
925
>any number of channels</I
926
></SPAN
927
>, </P
928
></LI
929
><LI
930
><P
931
>with an <SPAN
932
CLASS="emphasis"
933
><I
934
CLASS="EMPHASIS"
935
>arbitrary order</I
936
></SPAN
937
> of channels in each scan
938
(possibly even with repeated channels per scan), </P
939
></LI
940
><LI
941
><P
942
>and with various scan <SPAN
943
CLASS="emphasis"
944
><I
945
CLASS="EMPHASIS"
946
>triggering sources</I
947
></SPAN
948
>,
949
external (i.e., hardware pulses) as well as internal (i.e., pulses
950
generated on the DAQ card itself, or generated by a
951
<A
952
HREF="x621.html#INTTRIGCONFIGURATION"
953
>software trigger instruction</A
954
>).</P
955
></LI
956
></UL
957
>
958
This command functionality exists in the <ACRONYM
959
CLASS="ACRONYM"
960
>Comedi</ACRONYM
961
> API, because various
962
data acquisition devices have the capability to perform this kind of
963
complex acquisition, driven by either on-board or
964
off-board timers and triggers.</P
965
><P
966
>A command specifies a particular data
967
<A
968
HREF="index.html#FIG-ACQ-SEQ"
969
>acquisition sequence</A
970
>, which
971
consists of a number of <SPAN
972
CLASS="emphasis"
973
><I
974
CLASS="EMPHASIS"
975
>scans</I
976
></SPAN
977
>, and each scan is
978
comprised of a number of <SPAN
979
CLASS="emphasis"
980
><I
981
CLASS="EMPHASIS"
982
>conversions</I
983
></SPAN
984
>, which
985
usually corresponds to a single A/D or D/A conversion. So, for
986
example, a scan could consist of sampling channels 1, 2 and 3 of a
987
particular device, and this scan should be repeated 1000 times, at
988
intervals of 1 millisecond apart.</P
989
><P
990
>The command function is complementary to the
991
<A
992
HREF="x621.html#INSTRUCTIONSCONFIGURATION"
993
>configuration instruction</A
994
>
995
function: each channel in the command's
996
<A
997
HREF="x621.html#COMMAND-DATA-STRUCT-CHANLIST"
998
>chanlist</A
999
>
1000
should first be configured by an appropriate instruction.</P
1001
><DIV
1002
CLASS="SECTION"
1003
><H3
1004
CLASS="SECTION"
1005
><A
1006
NAME="EXECUTINGCOMMAND"
1007
>4.5.1. Executing a command</A
1008
></H3
1009
><P
1010
>A commands is executed by the following <ACRONYM
1011
CLASS="ACRONYM"
1012
>Comedi</ACRONYM
1013
> function:
1014
<PRE
1015
CLASS="PROGRAMLISTING"
1016
> int <A
1017
HREF="r4865.html"
1018
>comedi_command</A
1019
>(<A
1020
HREF="x3563.html#REF-TYPE-COMEDI-T"
1021
>comedi_t</A
1022
> * device, <A
1023
HREF="x3563.html#REF-TYPE-COMEDI-CMD"
1024
>comedi_cmd</A
1025
> * command);</PRE
1026
>
1027
The following sections explain the meaning of the
1028
<A
1029
HREF="x3563.html#REF-TYPE-COMEDI-CMD"
1030
>comedi_cmd</A
1031
> data structure.
1032
Filling in this structure can be quite complicated, and
1033
requires good knowledge about the exact functionalities of the DAQ
1034
card. So, before launching a command, the application programmer is
1035
adviced to check whether this complex command data structure can be
1036
successfully parsed. So, the typical sequence for executing a command is
1037
to first send the command through
1038
<A
1039
HREF="r4887.html"
1040
>comedi_command_test()</A
1041
>
1042
once or twice. The test will check that the command is valid for the
1043
particular device, and often makes some adjustments to the command
1044
arguments, which can then be read back by the user to see the actual
1045
values used.</P
1046
><P
1047
>A <ACRONYM
1048
CLASS="ACRONYM"
1049
>Comedi</ACRONYM
1050
> program can find out on-line what the command capabilities
1051
of a specific device are, by means of the
1052
<A
1053
HREF="r4795.html"
1054
>comedi_get_cmd_src_mask()</A
1055
>
1056
function.</P
1057
></DIV
1058
><DIV
1059
CLASS="SECTION"
1060
><H3
1061
CLASS="SECTION"
1062
><A
1063
NAME="COMEDICMDSTRUCTURE"
1064
>4.5.2. The command data structure</A
1065
></H3
1066
><P
1067
>The command executes according to the information about the requested
1068
acquisition, which is stored in the
1069
<A
1070
HREF="x3563.html#REF-TYPE-COMEDI-CMD"
1071
>comedi_cmd</A
1072
>
1073
<A
1074
NAME="COMMAND-DATA-STRUCT"
1075
></A
1076
>data structure:
1077
<PRE
1078
CLASS="PROGRAMLISTING"
1079
>typedef struct comedi_cmd_struct comedi_cmd;
1080
1081
struct comedi_cmd_struct{
1082
unsigned int subdev; // which subdevice to sample
1083
unsigned int <A
1084
NAME="COMMAND-DATA-STRUCT-FLAGS"
1085
></A
1086
>flags; // encode some configuration possibilities
1087
// of the command execution; e.g.,
1088
// whether a callback routine is to be
1089
// called at the end of the command
1090
1091
unsigned int <A
1092
NAME="COMMAND-DATA-STRUCT-START-SRC"
1093
></A
1094
>start_src; // event to make the acquisition start
1095
unsigned int <A
1096
NAME="COMMAND-DATA-STRUCT-START-ARG"
1097
></A
1098
>start_arg; // parameters that influence this start
1099
1100
unsigned int <A
1101
NAME="COMMAND-DATA-STRUCT-SCAN-BEGIN-SRC"
1102
></A
1103
>scan_begin_src; // event to make a particular scan start
1104
unsigned int <A
1105
NAME="COMMAND-DATA-STRUCT-SCAN-BEGIN-ARG"
1106
></A
1107
>scan_begin_arg; // parameters that influence this start`
1108
1109
unsigned int <A
1110
NAME="COMMAND-DATA-STRUCT-CONVERT-SRC"
1111
></A
1112
>convert_src; // event to make a particular conversion start
1113
unsigned int <A
1114
NAME="COMMAND-DATA-STRUCT-CONVERT-ARG"
1115
></A
1116
>convert_arg; // parameters that influence this start
1117
1118
unsigned int <A
1119
NAME="COMMAND-DATA-STRUCT-SCAN-END-SRC"
1120
></A
1121
>scan_end_src; // event to make a particular scan terminate
1122
unsigned int <A
1123
NAME="COMMAND-DATA-STRUCT-SCAN-END-ARG"
1124
></A
1125
>scan_end_arg; // parameters that influence this termination
1126
1127
unsigned int <A
1128
NAME="COMMAND-DATA-STRUCT-STOP-SRC"
1129
></A
1130
>stop_src; // what make the acquisition terminate
1131
unsigned int <A
1132
NAME="COMMAND-DATA-STRUCT-STOP-ARG"
1133
></A
1134
>stop_arg; // parameters that influence this termination
1135
1136
unsigned int <A
1137
NAME="COMMAND-DATA-STRUCT-CHANLIST"
1138
></A
1139
>*chanlist; // pointer to list of channels to be sampled
1140
unsigned int <A
1141
NAME="COMMAND-DATA-STRUCT-CHANLIST-LEN"
1142
></A
1143
>chanlist_len; // number of channels to be sampled
1144
1145
sampl_t *<A
1146
NAME="COMMAND-DATA-STRUCT-DATA"
1147
></A
1148
>data; // address of buffer
1149
unsigned int <A
1150
NAME="COMMAND-DATA-STRUCT-DATA-LEN"
1151
></A
1152
>data_len; // number of samples to acquire
1153
};</PRE
1154
>
1155
The start and end of the whole command acquisition sequence, and the
1156
start and end of each scan and of each conversion, is triggered by a
1157
so-called <SPAN
1158
CLASS="emphasis"
1159
><I
1160
CLASS="EMPHASIS"
1161
>event</I
1162
></SPAN
1163
>. More on these in
1164
<A
1165
HREF="x621.html#COMEDICMDSOURCES"
1166
>Section 4.5.3</A
1167
>.</P
1168
><P
1169
>The <VAR
1170
CLASS="PARAMETER"
1171
>subdev</VAR
1172
> member of the
1173
<A
1174
HREF="x3563.html#REF-TYPE-COMEDI-CMD"
1175
>comedi_cmd</A
1176
> structure is
1177
the index of the subdevice the command is intended for. The
1178
<A
1179
HREF="r4020.html"
1180
>comedi_find_subdevice_by_type()</A
1181
>
1182
function can be useful in discovering the index of your desired subdevice.</P
1183
><P
1184
>The <A
1185
HREF="x621.html#COMMAND-DATA-STRUCT-CHANLIST"
1186
>chanlist</A
1187
>
1188
member of the
1189
<A
1190
HREF="x3563.html#REF-TYPE-COMEDI-CMD"
1191
>comedi_cmd</A
1192
> data
1193
structure should point to an array whose number of elements is
1194
specificed by
1195
<A
1196
HREF="x621.html#COMMAND-DATA-STRUCT-CHANLIST-LEN"
1197
>chanlist_len</A
1198
>
1199
(this will generally be the same as the
1200
<A
1201
HREF="x621.html#COMMAND-DATA-STRUCT-SCAN-END-ARG"
1202
>scan_end_arg</A
1203
>).
1204
The
1205
<A
1206
HREF="x621.html#COMMAND-DATA-STRUCT-CHANLIST"
1207
>chanlist</A
1208
>
1209
specifies the sequence of channels and gains (and analog references)
1210
that should be stepped through for each scan. The elements of the
1211
<A
1212
HREF="x621.html#COMMAND-DATA-STRUCT-CHANLIST"
1213
>chanlist</A
1214
> array should be
1215
initialized by <SPAN
1216
CLASS="QUOTE"
1217
>"packing"</SPAN
1218
> the channel, range and reference
1219
information together with the
1220
<VAR
1221
CLASS="PARAMETER"
1222
> <A
1223
HREF="x3563.html#REF-MACRO-CR-PACK"
1224
>CR_PACK()</A
1225
></VAR
1226
>
1227
macro.</P
1228
><P
1229
>The <A
1230
HREF="x621.html#COMMAND-DATA-STRUCT-DATA"
1231
>data</A
1232
> and
1233
<A
1234
HREF="x621.html#COMMAND-DATA-STRUCT-DATA-LEN"
1235
>data_len</A
1236
>
1237
members can be safely ignored when issueing commands from a user-space
1238
program. They only have meaning when a command is sent from a
1239
<SPAN
1240
CLASS="strong"
1241
><B
1242
CLASS="EMPHASIS"
1243
>kernel</B
1244
></SPAN
1245
> module using the
1246
<CODE
1247
CLASS="FUNCTION"
1248
>kcomedilib</CODE
1249
> interface, in which case they specify
1250
the buffer where the driver should write/read its data to/from.</P
1251
><P
1252
>The final member of the
1253
<A
1254
HREF="x621.html#COMMAND-DATA-STRUCT"
1255
>comedi_cmd</A
1256
> structure is the
1257
<A
1258
HREF="x621.html#COMMAND-DATA-STRUCT-FLAGS"
1259
>flags</A
1260
> field,
1261
i.e., bits in a word that can be bitwise-or'd together. The meaning of
1262
these bits are explained in a
1263
<A
1264
HREF="x621.html#SOURCE.FLAGS.ANCHOR"
1265
>later section</A
1266
>.</P
1267
></DIV
1268
><DIV
1269
CLASS="SECTION"
1270
><H3
1271
CLASS="SECTION"
1272
><A
1273
NAME="COMEDICMDSOURCES"
1274
>4.5.3. The command trigger events
1275
<A
1276
NAME="SOURCE.TRIGGER.ANCHOR"
1277
></A
1278
></A
1279
></H3
1280
><P
1281
>A command is a very versatile acquisition instruction, in the sense
1282
that it offers lots of possibilities to let different hardware and
1283
software sources determine when acquisitions are started, performed,
1284
and stopped. More specifically, the command
1285
<A
1286
HREF="x621.html#COMMAND-DATA-STRUCT"
1287
>data structure</A
1288
>
1289
has <SPAN
1290
CLASS="emphasis"
1291
><I
1292
CLASS="EMPHASIS"
1293
>five</I
1294
></SPAN
1295
> types of events: start the
1296
<A
1297
HREF="index.html#ACQUISITIONTERMINOLOGY"
1298
>acquisition</A
1299
>,
1300
start a <A
1301
HREF="index.html#SCAN"
1302
>scan</A
1303
>, start a
1304
<A
1305
HREF="index.html#CONVERSION"
1306
>conversion</A
1307
>, stop a scan, and stop
1308
the acquisition. Each event can be given its own
1309
<SPAN
1310
CLASS="emphasis"
1311
><I
1312
CLASS="EMPHASIS"
1313
><A
1314
HREF="x621.html#SOURCE.TRIGGER.ANCHOR"
1315
>source</A
1316
></I
1317
></SPAN
1318
>
1319
(the <VAR
1320
CLASS="PARAMETER"
1321
>*_src</VAR
1322
> members in the
1323
<A
1324
HREF="x3563.html#REF-TYPE-COMEDI-CMD"
1325
>comedi_cmd</A
1326
> data
1327
structure). And each event source can have a corresponding
1328
argument (the <VAR
1329
CLASS="PARAMETER"
1330
>*_arg</VAR
1331
> members of
1332
the <A
1333
HREF="x3563.html#REF-TYPE-COMEDI-CMD"
1334
>comedi_cmd</A
1335
> data
1336
structure) whose meaning depends on the type of source trigger.
1337
For example, to specify an external digital line <SPAN
1338
CLASS="QUOTE"
1339
>"3"</SPAN
1340
> as a
1341
source (in general, <SPAN
1342
CLASS="emphasis"
1343
><I
1344
CLASS="EMPHASIS"
1345
>any</I
1346
></SPAN
1347
> of the five event
1348
sources), you would use
1349
<VAR
1350
CLASS="PARAMETER"
1351
>src</VAR
1352
>=<A
1353
HREF="x621.html#TRIG-EXT"
1354
>TRIG_EXT</A
1355
> and
1356
<VAR
1357
CLASS="PARAMETER"
1358
>arg</VAR
1359
>=3.</P
1360
><P
1361
>The following paragraphs discuss in somewhat more detail the trigger
1362
event sources(<VAR
1363
CLASS="PARAMETER"
1364
>*_src</VAR
1365
>), and the
1366
corresponding arguments (<VAR
1367
CLASS="PARAMETER"
1368
>*_arg</VAR
1369
>).</P
1370
><P
1371
>The start of an acquisition is controlled by the
1372
<A
1373
HREF="x621.html#COMMAND-DATA-STRUCT-START-SRC"
1374
>start_src</A
1375
> events.
1376
The available options are:
1377
<P
1378
></P
1379
><UL
1380
><LI
1381
><P
1382
><A
1383
NAME="TRIG-NOW-START-SRC"
1384
></A
1385
>
1386
TRIG_NOW: the
1387
<A
1388
HREF="x621.html#COMMAND-DATA-STRUCT-START-SRC"
1389
>start_src</A
1390
>
1391
event occurs
1392
<A
1393
HREF="x621.html#COMMAND-DATA-STRUCT-START-ARG"
1394
>start_arg</A
1395
>
1396
nanoseconds after the
1397
<A
1398
HREF="x3563.html#REF-TYPE-COMEDI-CMD"
1399
>comedi_cmd</A
1400
>
1401
is called. Currently, only
1402
<A
1403
HREF="x621.html#COMMAND-DATA-STRUCT-START-ARG"
1404
>start_arg</A
1405
>=0 is
1406
supported.</P
1407
></LI
1408
><LI
1409
><P
1410
><A
1411
NAME="TRIG-FOLLOW-START-SRC"
1412
></A
1413
>
1414
TRIG_FOLLOW: (For an output device.) The
1415
<A
1416
HREF="x621.html#COMMAND-DATA-STRUCT-START-SRC"
1417
>start_src</A
1418
>
1419
event occurs when data is written to the buffer.</P
1420
></LI
1421
><LI
1422
><P
1423
><A
1424
NAME="TRIG-EXT-START-SRC"
1425
></A
1426
>
1427
TRIG_EXT: the start event occurs when an external trigger signal
1428
occurs; e.g., a rising edge of a digital line.
1429
<A
1430
HREF="x621.html#COMMAND-DATA-STRUCT-START-ARG"
1431
>start_arg</A
1432
>
1433
chooses the particular digital line.</P
1434
></LI
1435
><LI
1436
><P
1437
><A
1438
NAME="TRIG-INT-START-SRC"
1439
></A
1440
>
1441
TRIG_INT: the start event occurs on a <ACRONYM
1442
CLASS="ACRONYM"
1443
>Comedi</ACRONYM
1444
> internal signal, which
1445
is typically caused by an
1446
<A
1447
HREF="x621.html#INSN-INTTRIG"
1448
>INSN_INTTRIG instruction</A
1449
>.</P
1450
></LI
1451
></UL
1452
>
1453
The start of the beginning of each
1454
<A
1455
HREF="index.html#SCAN"
1456
>scan</A
1457
> is controlled by the
1458
<A
1459
HREF="x621.html#COMMAND-DATA-STRUCT-SCAN-BEGIN-SRC"
1460
>scan_begin</A
1461
> events.
1462
The available options are:
1463
<P
1464
></P
1465
><UL
1466
><LI
1467
><P
1468
><A
1469
NAME="TRIG-TIMER-START-SCAN"
1470
></A
1471
>
1472
TRIG_TIMER:
1473
<A
1474
HREF="x621.html#COMMAND-DATA-STRUCT-SCAN-BEGIN-SRC"
1475
>scan_begin</A
1476
>
1477
events occur periodically. The time between
1478
<A
1479
HREF="x621.html#COMMAND-DATA-STRUCT-SCAN-BEGIN-SRC"
1480
>scan_begin</A
1481
>
1482
events is
1483
<A
1484
HREF="x621.html#COMMAND-DATA-STRUCT-CONVERT-ARG"
1485
>convert_arg</A
1486
>
1487
nanoseconds.</P
1488
></LI
1489
><LI
1490
><P
1491
><A
1492
NAME="TRIG-FOLLOW-START-SCAN"
1493
></A
1494
>
1495
TRIG_FOLLOW: The
1496
<A
1497
HREF="x621.html#COMMAND-DATA-STRUCT-SCAN-BEGIN-SRC"
1498
>scan_begin</A
1499
>
1500
event occurs immediately after a
1501
<A
1502
HREF="x621.html#COMMAND-DATA-STRUCT-SCAN-END-SRC"
1503
>scan_end</A
1504
>
1505
event occurs.</P
1506
></LI
1507
><LI
1508
><P
1509
><A
1510
NAME="TRIG-EXT-START-SCAN"
1511
></A
1512
>
1513
TRIG_EXT: the
1514
<A
1515
HREF="x621.html#COMMAND-DATA-STRUCT-SCAN-BEGIN-SRC"
1516
>scan_begin</A
1517
>
1518
event occurs when an external trigger signal
1519
occurs; e.g., a rising edge of a digital line.
1520
<A
1521
HREF="x621.html#COMMAND-DATA-STRUCT-SCAN-BEGIN-ARG"
1522
>scan_begin_arg</A
1523
>
1524
chooses the particular digital line.</P
1525
></LI
1526
></UL
1527
>
1528
The
1529
<A
1530
HREF="x621.html#COMMAND-DATA-STRUCT-SCAN-BEGIN-ARG"
1531
>scan_begin_arg</A
1532
>
1533
used here may not be supported exactly by the device, but it
1534
will be adjusted to the nearest supported value by
1535
<A
1536
HREF="r4887.html"
1537
>comedi_command_test()</A
1538
>.</P
1539
><P
1540
>The timing between each sample in a
1541
<A
1542
HREF="index.html#SCAN"
1543
>scan</A
1544
> is controlled by the
1545
<A
1546
HREF="x621.html#COMMAND-DATA-STRUCT-CONVERT-SRC"
1547
>convert_*</A
1548
>
1549
fields:
1550
<P
1551
></P
1552
><UL
1553
><LI
1554
><P
1555
><A
1556
NAME="CONVERT-TRIG-TIMER"
1557
></A
1558
>
1559
<A
1560
NAME="TRIG-TIMER"
1561
></A
1562
>
1563
TRIG_TIMER: the conversion events occur periodically. The time
1564
between convert events is
1565
<A
1566
HREF="x621.html#COMMAND-DATA-STRUCT-CONVERT-ARG"
1567
>convert_arg</A
1568
>
1569
nanoseconds.</P
1570
></LI
1571
><LI
1572
><P
1573
><A
1574
NAME="CONVERT-TRIG-EXT"
1575
></A
1576
>
1577
<A
1578
NAME="TRIG-EXT"
1579
></A
1580
>
1581
TRIG_EXT: the conversion events occur when an external trigger signal
1582
occurs, e.g., a rising edge of a digital line.
1583
<A
1584
HREF="x621.html#COMMAND-DATA-STRUCT-CONVERT-ARG"
1585
>convert_arg</A
1586
>
1587
chooses the particular digital line.</P
1588
></LI
1589
><LI
1590
><P
1591
><A
1592
NAME="CONVERT-TRIG-NOW"
1593
></A
1594
>
1595
<A
1596
NAME="TRIG-NOW"
1597
></A
1598
>
1599
TRIG_NOW: All conversion events in a
1600
<A
1601
HREF="index.html#SCAN"
1602
>scan</A
1603
> occur simultaneously.</P
1604
></LI
1605
></UL
1606
>
1607
The <SPAN
1608
CLASS="emphasis"
1609
><I
1610
CLASS="EMPHASIS"
1611
>end</I
1612
></SPAN
1613
> of each scan is almost always specified
1614
using
1615
<A
1616
HREF="x621.html#TRIG-COUNT"
1617
>TRIG_COUNT</A
1618
>, with the argument being
1619
the same as the number of channels in the
1620
<A
1621
HREF="x621.html#COMMAND-DATA-STRUCT-CHANLIST"
1622
>chanlist</A
1623
>. You
1624
could probably find a device that allows something else, but it would
1625
be strange. </P
1626
><P
1627
>The end of an
1628
<A
1629
HREF="index.html#ACQUISITIONTERMINOLOGY"
1630
>acquisition</A
1631
> is
1632
controlled by
1633
<A
1634
HREF="x621.html#COMMAND-DATA-STRUCT-STOP-SRC"
1635
>stop_src</A
1636
>
1637
and <A
1638
HREF="x621.html#COMMAND-DATA-STRUCT-STOP-ARG"
1639
>stop_arg</A
1640
>:
1641
<P
1642
></P
1643
><UL
1644
><LI
1645
><P
1646
><A
1647
NAME="ACQUISITION-END-TRIG-COUNT"
1648
></A
1649
>
1650
<A
1651
NAME="TRIG-COUNT"
1652
></A
1653
>
1654
TRIG_COUNT: stop the acquisition after
1655
<A
1656
HREF="x621.html#COMMAND-DATA-STRUCT-STOP-ARG"
1657
>stop_arg</A
1658
>
1659
scans.</P
1660
></LI
1661
><LI
1662
><P
1663
><A
1664
NAME="ACQUISITION-END-TRIG-NONE"
1665
></A
1666
>
1667
<A
1668
NAME="TRIG-NONE"
1669
></A
1670
>
1671
TRIG_NONE: perform continuous acquisition, until stopped using
1672
<A
1673
HREF="r4843.html"
1674
>comedi_cancel()</A
1675
>.</P
1676
><P
1677
>Its argument is reserved and should be set to 0.
1678
(<SPAN
1679
CLASS="QUOTE"
1680
>"Reserved"</SPAN
1681
>
1682
means that unspecified things could happen if it is set to something
1683
else but 0.)</P
1684
></LI
1685
></UL
1686
>
1687
There are a couple of less usual or not yet implemented events:
1688
<P
1689
></P
1690
><UL
1691
><LI
1692
><P
1693
><A
1694
NAME="TRIG-TIME"
1695
></A
1696
>
1697
TRIG_TIME:
1698
cause an event to occur at a particular time.</P
1699
><P
1700
>(This event source is reserved for future use.)</P
1701
></LI
1702
><LI
1703
><P
1704
><A
1705
NAME="TRIGOTHER-EVENT"
1706
></A
1707
>
1708
TRIG_OTHER: driver specific event trigger.</P
1709
><P
1710
>This event can be useful as any of the trigger sources. Its exact
1711
meaning is driver specific, because it implements a feature that
1712
otherwise does not fit into the generic <ACRONYM
1713
CLASS="ACRONYM"
1714
>Comedi</ACRONYM
1715
> command interface.
1716
Configuration of TRIG_OTHER features are done by
1717
<A
1718
HREF="x621.html#INSTRUCTIONSCONFIGURATION"
1719
>INSN_CONFIG</A
1720
>
1721
instructions.</P
1722
><P
1723
>The argument is reserved and should be set to 0.</P
1724
></LI
1725
></UL
1726
>
1727
Not all event sources are applicable to all events. Supported
1728
trigger sources for specific events depend significantly on your
1729
particular device, and even more on the current state of its device
1730
driver. The
1731
<A
1732
HREF="r4795.html"
1733
>comedi_get_cmd_src_mask()</A
1734
>
1735
function is useful for determining what trigger sources a subdevice
1736
supports.</P
1737
></DIV
1738
><DIV
1739
CLASS="SECTION"
1740
><H3
1741
CLASS="SECTION"
1742
><A
1743
NAME="COMEDICMDFLAGS"
1744
>4.5.4. The command flags
1745
<A
1746
NAME="SOURCE.FLAGS.ANCHOR"
1747
></A
1748
></A
1749
></H3
1750
><P
1751
>The
1752
<A
1753
HREF="x621.html#COMMAND-DATA-STRUCT-FLAGS"
1754
>flags</A
1755
> field in the
1756
<A
1757
HREF="x3563.html#REF-TYPE-COMEDI-CMD"
1758
>command data structure</A
1759
>
1760
is used to specify some <SPAN
1761
CLASS="QUOTE"
1762
>"behaviour"</SPAN
1763
> of the acquisitions in
1764
a command.
1765
The meaning of the field is as follows:
1766
<P
1767
></P
1768
><UL
1769
><LI
1770
><P
1771
><A
1772
NAME="TRIG-RT"
1773
></A
1774
>
1775
TRIG_RT: ask the driver to use a
1776
<SPAN
1777
CLASS="strong"
1778
><B
1779
CLASS="EMPHASIS"
1780
>hard real-time</B
1781
></SPAN
1782
> interrupt handler.
1783
This will reduce latency in handling interrupts from your data
1784
aquisition
1785
hardware. It can be useful if you are sampling at high frequency, or
1786
if your hardware has a small onboard data buffer. You must have a
1787
real-time kernel (<A
1788
HREF="http://www.rtai.org"
1789
TARGET="_top"
1790
>RTAI</A
1791
> or
1792
<A
1793
HREF="http://fsmlabs.com/community/"
1794
TARGET="_top"
1795
>RTLinux/Free</A
1796
>)
1797
and must compile <ACRONYM
1798
CLASS="ACRONYM"
1799
>Comedi</ACRONYM
1800
> with real-time support, or this flag will do
1801
nothing.</P
1802
></LI
1803
><LI
1804
><P
1805
><A
1806
NAME="TRIG-WAKE-EOS"
1807
></A
1808
>
1809
TRIG_WAKE_EOS:
1810
where <SPAN
1811
CLASS="QUOTE"
1812
>"EOS"</SPAN
1813
> stands for <SPAN
1814
CLASS="QUOTE"
1815
>"End of Scan"</SPAN
1816
>. Some
1817
drivers will change their behaviour when this flag is set, trying to
1818
transfer data at the end of every scan (instead of, for example,
1819
passing data in chunks whenever the board's hardware data buffer is
1820
half full). This flag may degrade a driver's performance at high
1821
frequencies, because the end of a scan is, in general, a much more
1822
frequent event than the filling up of the data buffer.</P
1823
></LI
1824
><LI
1825
><P
1826
><A
1827
NAME="TRIG-ROUND-NEAREST"
1828
></A
1829
>
1830
TRIG_ROUND_NEAREST:
1831
round to nearest supported timing period, the default.
1832
This flag (as well as the following three), indicates how timing
1833
arguments should be rounded if the hardware cannot achieve the exact
1834
timing requested.</P
1835
></LI
1836
><LI
1837
><P
1838
><A
1839
NAME="TRIG-ROUND-DOWN"
1840
></A
1841
>
1842
TRIG_ROUND_DOWN: round period down.</P
1843
></LI
1844
><LI
1845
><P
1846
><A
1847
NAME="TRIG-ROUND-UP"
1848
></A
1849
>
1850
TRIG_ROUND_UP: round period up.</P
1851
></LI
1852
><LI
1853
><P
1854
><A
1855
NAME="TRIG-ROUND-UP-NEXT"
1856
></A
1857
>
1858
TRIG_ROUND_UP_NEXT:
1859
this one doesn't do anything, and I don't know what it was intended
1860
to do...?</P
1861
></LI
1862
><LI
1863
><P
1864
><A
1865
NAME="TRIG-DITHER"
1866
></A
1867
>
1868
TRIG_DITHER: enable dithering? Dithering is a software technique to
1869
smooth the influence of discretization <SPAN
1870
CLASS="QUOTE"
1871
>"noise"</SPAN
1872
>.</P
1873
></LI
1874
><LI
1875
><P
1876
><A
1877
NAME="TRIG-DEGLITCH"
1878
></A
1879
>
1880
TRIG_DEGLITCH: enable deglitching? Another <SPAN
1881
CLASS="QUOTE"
1882
>"noise"</SPAN
1883
>
1884
smoothing technique.</P
1885
></LI
1886
><LI
1887
><P
1888
><A
1889
NAME="TRIG-WRITE"
1890
></A
1891
>
1892
TRIG_WRITE:
1893
write to bidirectional devices. Could be useful, in principle, if
1894
someone wrote a driver that supported commands for a digital I/O
1895
device that could do either input or output.</P
1896
></LI
1897
><LI
1898
><P
1899
><A
1900
NAME="TRIG-BOGUS"
1901
></A
1902
>
1903
TRIG_BOGUS: do the motions?</P
1904
></LI
1905
><LI
1906
><P
1907
><A
1908
NAME="TRIG-OTHER"
1909
></A
1910
>
1911
TRIG_CONFIG: perform configuration, not triggering. This is a legacy
1912
of the deprecated
1913
<A
1914
HREF="x3563.html#REF-TYPE-COMEDI-CMD"
1915
>comedi_trig_struct</A
1916
>
1917
data structure, and has no function at present.</P
1918
></LI
1919
></UL
1920
></P
1921
></DIV
1922
><DIV
1923
CLASS="SECTION"
1924
><H3
1925
CLASS="SECTION"
1926
><A
1927
NAME="AEN1071"
1928
>4.5.5. Anti-aliasing</A
1929
></H3
1930
><P
1931
>If you wish to aquire accurate waveforms, it is vital that you use an
1932
anti-alias filter. An anti-alias filter is a low-pass filter used to
1933
remove all frequencies higher than the Nyquist frequency (half your sampling rate)
1934
from your analog input signal
1935
before you convert it to digital. If you fail to filter your input signal,
1936
any high frequency components in the original analog signal will create
1937
artifacts in your recorded digital waveform that cannot be corrected.</P
1938
><P
1939
>For example, suppose you are sampling an analog input channel at a rate of
1940
1000 Hz. If you were to apply a 900 Hz sine wave to the input, you
1941
would find that your
1942
sampling rate is not high enough to faithfully record the 900 Hz input,
1943
since it is above your Nyquist frequency of 500 Hz. Instead, what you
1944
will see in your recorded digital waveform is a 100 Hz sine wave! If you
1945
don't use an anti-alias filter, it is impossible to tell whether the 100
1946
Hz sine wave you see in your digital signal was really produced by a
1947
100 Hz input signal, or a 900 Hz signal aliased to 100 Hz, or a 1100 Hz
1948
signal, etc.</P
1949
><P
1950
>In practice, the cutoff frequency for the anti-alias filter is usually
1951
set 10% to 20% below the Nyquist frequency due to fact that real filters
1952
do not have infinitely sharp cutoffs.</P
1953
></DIV
1954
></DIV
1955
><DIV
1956
CLASS="SECTION"
1957
><H2
1958
CLASS="SECTION"
1959
><A
1960
NAME="SLOWLYVARYING"
1961
>4.6. Slowly-varying inputs</A
1962
></H2
1963
><P
1964
>Sometimes, your input channels change slowly enough that
1965
you are able to average many successive input values to get a
1966
more accurate measurement of the actual value. In general,
1967
the more samples you average, the better your estimate
1968
gets, roughly by a factor of sqrt(number_of_samples).
1969
Obviously, there are limitations to this:</P
1970
><P
1971
></P
1972
><UL
1973
><LI
1974
><P
1975
>you are ultimately limited by <SPAN
1976
CLASS="QUOTE"
1977
>"Spurious Free Dynamic
1978
Range"</SPAN
1979
>. This SFDR is one of the popular measures to quantify how
1980
much noise a signal carries. If you take a Fourier transform of your
1981
signal, you will see several <SPAN
1982
CLASS="QUOTE"
1983
>"peaks"</SPAN
1984
> in the transform: one
1985
or more of the fundamental harmonics of the measured signal, and lots
1986
of little <SPAN
1987
CLASS="QUOTE"
1988
>"peaks"</SPAN
1989
> (called <SPAN
1990
CLASS="QUOTE"
1991
>"spurs"</SPAN
1992
>) caused by
1993
noise. The SFDR is then the difference between the amplitude of the
1994
fundamental harmonic and of the largest spur (at frequencies below
1995
half of the Nyquist frequency of the DAQ sampler!).</P
1996
></LI
1997
><LI
1998
><P
1999
>you need to have <SPAN
2000
CLASS="emphasis"
2001
><I
2002
CLASS="EMPHASIS"
2003
>some</I
2004
></SPAN
2005
> noise on the input channel,
2006
otherwise you will be averaging the same number <VAR
2007
CLASS="LITERAL"
2008
>N</VAR
2009
>
2010
times. (Of course, this only holds if the noise is large enough to
2011
cause at least a one-bit discretization.)</P
2012
></LI
2013
><LI
2014
><P
2015
>the more noise you have, the greater your SFDR, but it
2016
takes many more samples to compensate for the increased
2017
noise.</P
2018
></LI
2019
><LI
2020
><P
2021
>if you feel the need to average samples for, for example, two seconds,
2022
your signal will need to be <SPAN
2023
CLASS="emphasis"
2024
><I
2025
CLASS="EMPHASIS"
2026
>very</I
2027
></SPAN
2028
> slowly-varying,
2029
i.e., not varying more than your target uncertainty for the entire two
2030
seconds.</P
2031
></LI
2032
></UL
2033
><P
2034
>As you might have guessed, the <ACRONYM
2035
CLASS="ACRONYM"
2036
>Comedi</ACRONYM
2037
> library has functions
2038
to help you in your quest to accurately measure slowly varying
2039
inputs:
2040
<PRE
2041
CLASS="PROGRAMLISTING"
2042
> int <A
2043
HREF="r4721.html"
2044
>comedi_sv_init</A
2045
>(<A
2046
HREF="x3563.html#REF-TYPE-COMEDI-SV-T"
2047
>comedi_sv_t</A
2048
> * sv, <A
2049
HREF="x3563.html#REF-TYPE-COMEDI-T"
2050
>comedi_t</A
2051
> * device, unsigned int subdevice, unsigned int channel);</PRE
2052
>
2053
This function initializes the
2054
<A
2055
HREF="x3563.html#REF-TYPE-COMEDI-SV-T"
2056
>comedi_sv_t</A
2057
> data structure, used
2058
to do the averaging acquisition:
2059
<PRE
2060
CLASS="PROGRAMLISTING"
2061
>struct comedi_sv_struct{
2062
<A
2063
HREF="x3563.html#REF-TYPE-COMEDI-T"
2064
>comedi_t</A
2065
> *dev;
2066
unsigned int subdevice;
2067
unsigned int chan;
2068
2069
/* range policy */
2070
int range;
2071
int aref;
2072
2073
/* number of measurements to average (for analog inputs) */
2074
int n;
2075
2076
lsampl_t maxdata;
2077
};</PRE
2078
>
2079
The actual acquisition is done with:
2080
<PRE
2081
CLASS="PROGRAMLISTING"
2082
> int <A
2083
HREF="r4771.html"
2084
>comedi_sv_measure</A
2085
>(<A
2086
HREF="x3563.html#REF-TYPE-COMEDI-SV-T"
2087
>comedi_sv_t</A
2088
> * sv, double * data);</PRE
2089
>
2090
The number of samples over which the
2091
<CODE
2092
CLASS="FUNCTION"
2093
>comedi_sv_measure()</CODE
2094
> averages is limited by the
2095
implementation (currently the limit is 100 samples). </P
2096
><P
2097
>One typical use for this function is the measurement of thermocouple
2098
voltages.
2099
And the <ACRONYM
2100
CLASS="ACRONYM"
2101
>Comedi</ACRONYM
2102
> self-calibration utility also uses these functions.
2103
On some hardware, it is possible to tell it to measure an
2104
internal stable voltage reference, which is typically going
2105
to be very slowly varying; on the kilosecond time scale
2106
or more. So, it is reasonable to measure millions of samples,
2107
to get a very accurate measurement of the A/D converter output
2108
value that corresponds to the voltage reference. Sometimes,
2109
however, this is overkill, since there is no need to
2110
perform a part-per-million calibration to a standard that
2111
is only accurate to a part-per-thousand.</P
2112
></DIV
2113
><DIV
2114
CLASS="SECTION"
2115
><H2
2116
CLASS="SECTION"
2117
><A
2118
NAME="EXPERIMENTALFUNCTIONALITY"
2119
>4.7. Experimental functionality</A
2120
></H2
2121
><P
2122
>The following subsections document functionality that has not yet
2123
matured. Most of this functionality has even not been implemented yet
2124
in any single device driver. This information is included here, in
2125
order to stimulate discussion about their API, and to encourage
2126
pioneering implementations.</P
2127
><DIV
2128
CLASS="SECTION"
2129
><H3
2130
CLASS="SECTION"
2131
><A
2132
NAME="DIGITALINPUTCOMBINING"
2133
>4.7.1. Digital input combining machines</A
2134
></H3
2135
><P
2136
>(<SPAN
2137
CLASS="strong"
2138
><B
2139
CLASS="EMPHASIS"
2140
>Status: experimental (i.e., no driver implements
2141
this yet)</B
2142
></SPAN
2143
>)</P
2144
><P
2145
>When one or several digital inputs are used to modify an output
2146
value, either an accumulator or a single digital line or bit,
2147
a bitfield structure is typically used in the <ACRONYM
2148
CLASS="ACRONYM"
2149
>Comedi</ACRONYM
2150
> interface.
2151
The digital inputs have two properties, <SPAN
2152
CLASS="QUOTE"
2153
>"sensitive"</SPAN
2154
> inputs
2155
and <SPAN
2156
CLASS="QUOTE"
2157
>"modifier"</SPAN
2158
> inputs. Edge transitions on sensitive
2159
inputs cause changes in the output signal, whereas modifier inputs
2160
change the effect of edge transitions on sensitive inputs. Note that
2161
inputs can be both modifier inputs and sensitive inputs.</P
2162
><P
2163
>For simplification purposes, it is assumed that multiple digital
2164
inputs do not change simultaneously.</P
2165
><P
2166
>The combined state of the modifier inputs determine a modifier
2167
state. For each combination of modifier state and sensitive
2168
input, there is a set of bits that determine the effect on the
2169
output value due to positive or negative transitions of the
2170
sensitive input. For each transition direction, there are two
2171
bits defined as follows:
2172
<P
2173
></P
2174
><TABLE
2175
BORDER="0"
2176
><TBODY
2177
><TR
2178
><TD
2179
>00: transition is ignored.</TD
2180
></TR
2181
><TR
2182
><TD
2183
>01: accumulator is incremented, or output is set.</TD
2184
></TR
2185
><TR
2186
><TD
2187
>10: accumulator is decremented, or output is cleared.</TD
2188
></TR
2189
><TR
2190
><TD
2191
>11: reserved.</TD
2192
></TR
2193
></TBODY
2194
></TABLE
2195
><P
2196
></P
2197
>
2198
For example, a simple digital follower is specified by the bit
2199
pattern 01 10, because it sets the output on positive transitions
2200
of the input, and clears the output on negative transitions. A
2201
digital inverter is similarily 10 01. These systems have only
2202
one sensitive input.</P
2203
><P
2204
>As another example, a simple up counter, which increments on
2205
positive transitions of one input, is specified by 01 00. This
2206
system has only one sensitive input.</P
2207
><P
2208
>When multiple digital inputs are used, the inputs are divided
2209
into two types, inputs which cause changes in the accumulator, and
2210
those that only modify the meaning of transitions on other inputs.
2211
Modifier inputs do not require bitfields, but there needs to be
2212
a bitfield of length 4*(2^(N-1)) for each edge sensitive input,
2213
where N is the total number of inputs. Since N is usually 2 or
2214
3, with only one edge sensitive input, the scaling issues are
2215
not significant.</P
2216
></DIV
2217
><DIV
2218
CLASS="SECTION"
2219
><H3
2220
CLASS="SECTION"
2221
><A
2222
NAME="ANALOGCONVERSION"
2223
>4.7.2. Analog filtering configuration</A
2224
></H3
2225
><P
2226
><SPAN
2227
CLASS="strong"
2228
><B
2229
CLASS="EMPHASIS"
2230
>(Status: design (i.e., no driver implements
2231
this yet).)</B
2232
></SPAN
2233
></P
2234
><P
2235
>The <A
2236
HREF="x621.html#INSN-DATA-STRUCTURE-INSN"
2237
>insn</A
2238
> field of the
2239
<A
2240
HREF="x621.html#INSN-DATA-STRUCTURE"
2241
>instruction data structure</A
2242
>
2243
has not been assigned yet.</P
2244
><P
2245
>The <A
2246
HREF="x621.html#INSN-DATA-STRUCTURE-CHANSPEC"
2247
>chanspec</A
2248
> field
2249
of the <A
2250
HREF="x621.html#INSN-DATA-STRUCTURE"
2251
>instruction data
2252
structure</A
2253
> is ignored.</P
2254
><P
2255
>Some devices have the capability to add white noise (dithering) to
2256
analog input measurement. This additional noise can then be averaged
2257
out, to get a more accurate measurement of the input signal. It
2258
should not be assumed that channels can be separately configured.
2259
A simple design can use 1 bit to turn this feature on/off.</P
2260
><P
2261
>Some devices have the capability of changing the glitch characteristics
2262
of analog output subsytems. The default (off) case should be where
2263
the average settling time is lowest. A simple design can use 1 bit
2264
to turn this feature on/off.</P
2265
><P
2266
>Some devices have a configurable analog filters as part of the analog
2267
input stage. A simple design can use 1 bit to enable/disable the
2268
filter. Default is disabled, i.e., the filter being bypassed, or if
2269
the choice is between two filters, the filter with the largest
2270
bandwidth.</P
2271
></DIV
2272
><DIV
2273
CLASS="SECTION"
2274
><H3
2275
CLASS="SECTION"
2276
><A
2277
NAME="WAVEFORMGENERATION"
2278
>4.7.3. Analog Output Waveform Generation</A
2279
></H3
2280
><P
2281
><SPAN
2282
CLASS="strong"
2283
><B
2284
CLASS="EMPHASIS"
2285
>(Status: design (i.e., no driver implements
2286
this yet).)</B
2287
></SPAN
2288
></P
2289
><P
2290
>The <A
2291
HREF="x621.html#INSN-DATA-STRUCTURE-INSN"
2292
>insn</A
2293
> field of the
2294
<A
2295
HREF="x621.html#INSN-DATA-STRUCTURE"
2296
>instruction data structure</A
2297
>
2298
has not been assigned yet.</P
2299
><P
2300
>The <A
2301
HREF="x621.html#INSN-DATA-STRUCTURE-CHANSPEC"
2302
>chanspec</A
2303
> field
2304
of the <A
2305
HREF="x621.html#INSN-DATA-STRUCTURE"
2306
>instruction data
2307
structure</A
2308
> is ignored.</P
2309
><P
2310
>Some devices have the ability to cyclicly loop through samples kept in
2311
an on-board analog output FIFO. This config should allow the user to
2312
enable/disable this mode.</P
2313
><P
2314
>This config should allow the user to configure the number of samples
2315
to loop through. It may be necessary to configure the channels used.</P
2316
></DIV
2317
><DIV
2318
CLASS="SECTION"
2319
><H3
2320
CLASS="SECTION"
2321
><A
2322
NAME="EXTENDEDTRIGGERING"
2323
>4.7.4. Extended Triggering</A
2324
></H3
2325
><P
2326
><SPAN
2327
CLASS="strong"
2328
><B
2329
CLASS="EMPHASIS"
2330
>(Status: alpha.)</B
2331
></SPAN
2332
></P
2333
><P
2334
>The <A
2335
HREF="x621.html#INSN-DATA-STRUCTURE-INSN"
2336
>insn</A
2337
> field of the
2338
<A
2339
HREF="x621.html#INSN-DATA-STRUCTURE"
2340
>instruction data structure</A
2341
>
2342
has not been assigned yet.</P
2343
><P
2344
>The <A
2345
HREF="x621.html#INSN-DATA-STRUCTURE-CHANSPEC"
2346
>chanspec</A
2347
> field
2348
of the <A
2349
HREF="x621.html#INSN-DATA-STRUCTURE"
2350
>instruction data
2351
structure</A
2352
> is ignored.</P
2353
><P
2354
>This section covers common information for all extended
2355
triggering configuration, and doesn't describe a particular
2356
type of extended trigger.</P
2357
><P
2358
>Extended triggering is used to configure triggering engines that
2359
do not fit into commands. In a typical programming sequence, the
2360
application will use
2361
<A
2362
HREF="x621.html#INSTRUCTIONSCONFIGURATION"
2363
>configuration instructions</A
2364
>
2365
to configure an extended trigger, and a
2366
<A
2367
HREF="x621.html#COMMANDSSTREAMING"
2368
>command</A
2369
>,
2370
specifying
2371
<A
2372
HREF="x621.html#TRIG-OTHER"
2373
>TRIG_OTHER</A
2374
> as one of the trigger
2375
sources.</P
2376
><P
2377
>Extended trigger configuration should be designed in such a way
2378
that the user can probe for valid parameters, similar to how
2379
command testing works. An extended trigger configuration instruction
2380
should not configure the hardware directly, rather, the configuration
2381
should be saved until the subsequent command is issued. This
2382
allows more flexibility for future interface changes.</P
2383
><P
2384
>It has not been decided whether the configuration stage should return a
2385
token that is then used as the trigger argument in the command.
2386
Using tokens is one method to satisfy the problem that extended
2387
trigger configurations may have subtle compatiblity issues with
2388
other trigger sources/arguments that can only be determined at
2389
command test time. Passing all stages of a command test should
2390
only be allowed with a properly configured extended trigger.</P
2391
><P
2392
>Extended triggers must use
2393
<A
2394
HREF="x621.html#INSN-DATA-STRUCTURE-DATA"
2395
>data[1]</A
2396
> as flags. The
2397
upper 16 bits are reserved and used only for flags that are common to
2398
all extended triggers. The lower 16 bits may be defined by the
2399
particular type of extended trigger.</P
2400
><P
2401
>Various types of extended triggers must use
2402
<A
2403
HREF="x621.html#INSN-DATA-STRUCTURE-DATA"
2404
>data[1]</A
2405
> to know which
2406
event the extended trigger will be assigned to in the command
2407
structure. The possible values are an OR'd mask of the following:</P
2408
><P
2409
></P
2410
><UL
2411
><LI
2412
><P
2413
>COMEDI_EV_START
2414
</P
2415
></LI
2416
><LI
2417
><P
2418
>COMEDI_EV_SCAN_BEGIN
2419
</P
2420
></LI
2421
><LI
2422
><P
2423
>COMEDI_EV_CONVERT
2424
</P
2425
></LI
2426
><LI
2427
><P
2428
>COMEDI_EV_SCAN_END
2429
</P
2430
></LI
2431
><LI
2432
><P
2433
>COMEDI_EV_STOP
2434
</P
2435
></LI
2436
></UL
2437
></DIV
2438
><DIV
2439
CLASS="SECTION"
2440
><H3
2441
CLASS="SECTION"
2442
><A
2443
NAME="ANALOGTRIGGERING"
2444
>4.7.5. Analog Triggering</A
2445
></H3
2446
><P
2447
><SPAN
2448
CLASS="strong"
2449
><B
2450
CLASS="EMPHASIS"
2451
>(Status: alpha. The <CODE
2452
CLASS="FUNCTION"
2453
>ni_mio_common.c</CODE
2454
> driver
2455
implements this feature.)</B
2456
></SPAN
2457
></P
2458
><P
2459
>The <A
2460
HREF="x621.html#INSN-DATA-STRUCTURE-INSN"
2461
>insn</A
2462
> field of the
2463
<A
2464
HREF="x621.html#INSN-DATA-STRUCTURE"
2465
>instruction data structure</A
2466
>
2467
has not been assigned yet.</P
2468
><P
2469
>The <A
2470
HREF="x621.html#INSN-DATA-STRUCTURE-CHANSPEC"
2471
>chanspec</A
2472
> field
2473
of the <A
2474
HREF="x621.html#INSN-DATA-STRUCTURE"
2475
>instruction data
2476
structure</A
2477
> is ignored.</P
2478
><P
2479
>The <A
2480
HREF="x621.html#INSN-DATA-STRUCTURE-DATA"
2481
>data</A
2482
> field
2483
of the <A
2484
HREF="x621.html#INSN-DATA-STRUCTURE"
2485
>instruction data
2486
structure</A
2487
> is used as follows:
2488
<P
2489
></P
2490
><TABLE
2491
BORDER="0"
2492
><TBODY
2493
><TR
2494
><TD
2495
>data[1]: trigger and combining machine configuration.
2496
</TD
2497
></TR
2498
><TR
2499
><TD
2500
>data[2]: analog triggering signal chanspec.
2501
</TD
2502
></TR
2503
><TR
2504
><TD
2505
>data[3]: primary analog level.
2506
</TD
2507
></TR
2508
><TR
2509
><TD
2510
>data[4]: secondary analog level.
2511
</TD
2512
></TR
2513
></TBODY
2514
></TABLE
2515
><P
2516
></P
2517
></P
2518
><P
2519
>Analog triggering is described by a digital combining machine that
2520
has two sensitive digital inputs. The sensitive digital inputs are
2521
generated by configurable analog comparators. The analog comparators
2522
generate a digital 1 when the analog triggering signal is greater
2523
than the comparator level. The digital inputs are not modifier
2524
inputs. Note, however, there is an effective modifier due to the
2525
restriction that the primary analog comparator level must be less
2526
than the secondary analog comparator level.</P
2527
><P
2528
>If only one analog comparator signal is used, the combining machine
2529
for the secondary input should be set to ignored, and the secondary
2530
analog level should be set to 0.</P
2531
><P
2532
>The interpretation of the chanspec and voltage levels is device
2533
dependent, but should correspond to similar values of the analog
2534
input subdevice, if possible.</P
2535
><P
2536
>Notes: Reading range information is not addressed. This makes it
2537
difficult to convert comparator voltages to data values.</P
2538
><P
2539
>Possible extensions: A parameter that specifies the necessary time
2540
that the set condition has to be true before the trigger is generated.
2541
A parameter that specifies the necessary time that the reset condition
2542
has to be true before the state machine is reset.</P
2543
></DIV
2544
><DIV
2545
CLASS="SECTION"
2546
><H3
2547
CLASS="SECTION"
2548
><A
2549
NAME="BITFIELDMATCHING"
2550
>4.7.6. Bitfield Pattern Matching Extended Trigger</A
2551
></H3
2552
><P
2553
><SPAN
2554
CLASS="strong"
2555
><B
2556
CLASS="EMPHASIS"
2557
>(Status: design. No driver implements this feature yet.)</B
2558
></SPAN
2559
></P
2560
><P
2561
>The <A
2562
HREF="x621.html#INSN-DATA-STRUCTURE-INSN"
2563
>insn</A
2564
> field of the
2565
<A
2566
HREF="x621.html#INSN-DATA-STRUCTURE"
2567
>instruction data structure</A
2568
>
2569
has not been assigned yet.</P
2570
><P
2571
>The <A
2572
HREF="x621.html#INSN-DATA-STRUCTURE-CHANSPEC"
2573
>chanspec</A
2574
> field
2575
of the <A
2576
HREF="x621.html#INSN-DATA-STRUCTURE"
2577
>instruction data
2578
structure</A
2579
> is ignored.</P
2580
><P
2581
>The <A
2582
HREF="x621.html#INSN-DATA-STRUCTURE-DATA"
2583
>data</A
2584
> field
2585
of the <A
2586
HREF="x621.html#INSN-DATA-STRUCTURE"
2587
>instruction data
2588
structure</A
2589
> is used as follows:</P
2590
><P
2591
></P
2592
><TABLE
2593
BORDER="0"
2594
><TBODY
2595
><TR
2596
><TD
2597
>data[1]: trigger flags.
2598
</TD
2599
></TR
2600
><TR
2601
><TD
2602
>data[2]: mask.
2603
</TD
2604
></TR
2605
><TR
2606
><TD
2607
>data[3]: pattern.
2608
</TD
2609
></TR
2610
></TBODY
2611
></TABLE
2612
><P
2613
></P
2614
><P
2615
>The pattern matching trigger issues a trigger when all of a specifed
2616
set of input lines match a specified pattern. If the device allows,
2617
the input lines should correspond to the input lines of a digital input
2618
subdevice, however, this will necessarily be device dependent. Each
2619
possible digital line that can be matched is assigned a bit in the
2620
mask and pattern. A bit set in the mask indicates that the
2621
input line must match the corresponding bit in the pattern.
2622
A bit cleared in the mask indicates that the input line is ignored.</P
2623
><P
2624
>Notes: This only allows 32 bits in the pattern/mask, which may be
2625
too few. Devices may support selecting different sets of lines from
2626
which to match a pattern.</P
2627
><P
2628
>Discovery: The number of bits can be discovered by setting the mask
2629
to all 1's. The driver must modify this value and return -EAGAIN.</P
2630
></DIV
2631
><DIV
2632
CLASS="SECTION"
2633
><H3
2634
CLASS="SECTION"
2635
><A
2636
NAME="COUNTERTIMER"
2637
>4.7.7. Counter configuration</A
2638
></H3
2639
><P
2640
><SPAN
2641
CLASS="strong"
2642
><B
2643
CLASS="EMPHASIS"
2644
>(Status: design. No driver implements this feature yet.)</B
2645
></SPAN
2646
></P
2647
><P
2648
>The <A
2649
HREF="x621.html#INSN-DATA-STRUCTURE-INSN"
2650
>insn</A
2651
> field of the
2652
<A
2653
HREF="x621.html#INSN-DATA-STRUCTURE"
2654
>instruction data structure</A
2655
>
2656
has not been assigned yet.</P
2657
><P
2658
>The <A
2659
HREF="x621.html#INSN-DATA-STRUCTURE-CHANSPEC"
2660
>chanspec</A
2661
> field
2662
of the <A
2663
HREF="x621.html#INSN-DATA-STRUCTURE"
2664
>instruction data
2665
structure</A
2666
> is used to specify which counter to use. (I.e., the
2667
counter is a <ACRONYM
2668
CLASS="ACRONYM"
2669
>Comedi</ACRONYM
2670
> channel.)</P
2671
><P
2672
>The <A
2673
HREF="x621.html#INSN-DATA-STRUCTURE-DATA"
2674
>data</A
2675
> field
2676
of the <A
2677
HREF="x621.html#INSN-DATA-STRUCTURE"
2678
>instruction data
2679
structure</A
2680
> is used as follows:</P
2681
><P
2682
></P
2683
><TABLE
2684
BORDER="0"
2685
><TBODY
2686
><TR
2687
><TD
2688
>data[1]: trigger configuration.
2689
</TD
2690
></TR
2691
><TR
2692
><TD
2693
>data[2]: primary input chanspec.
2694
</TD
2695
></TR
2696
><TR
2697
><TD
2698
>data[3]: primary combining machine configuration.
2699
</TD
2700
></TR
2701
><TR
2702
><TD
2703
>data[4]: secondary input chanspec.
2704
</TD
2705
></TR
2706
><TR
2707
><TD
2708
>data[5]: secondary combining machine configuration.
2709
</TD
2710
></TR
2711
><TR
2712
><TD
2713
>data[6]: latch configuration.
2714
</TD
2715
></TR
2716
></TBODY
2717
></TABLE
2718
><P
2719
></P
2720
><P
2721
>Note that this configuration is only useful if the counting has to be
2722
done in <SPAN
2723
CLASS="emphasis"
2724
><I
2725
CLASS="EMPHASIS"
2726
>software</I
2727
></SPAN
2728
>. Many cards offer configurable
2729
counters in hardware; e.g., general purpose timer cards can be
2730
configured to act as pulse generators, frequency counters, timers,
2731
encoders, etc.</P
2732
><P
2733
>Counters can be operated either in synchronous mode (using
2734
<A
2735
HREF="x621.html#COMEDIINSNSTRUCTURE"
2736
>INSN_READ</A
2737
>)
2738
or asynchronous mode (using
2739
<A
2740
HREF="x621.html#COMMANDSSTREAMING"
2741
>commands</A
2742
>), similar to analog
2743
input subdevices.
2744
The input signal for both modes is the accumulator.
2745
Commands on counter subdevices are almost always specified using
2746
<A
2747
HREF="x621.html#COMMAND-DATA-STRUCT-SCAN-BEGIN-SRC"
2748
>scan_begin_src</A
2749
>
2750
= <A
2751
HREF="x621.html#TRIGOTHER-EVENT"
2752
>TRIG_OTHER</A
2753
>, with the
2754
counter configuration also serving as the extended configuration for
2755
the scan begin source.</P
2756
><P
2757
>Counters are made up of an accumulator and a combining machine that
2758
determines when the accumulator should be incremented or decremented
2759
based on the values of the input signals. The combining machine
2760
optionally determines when the accumulator should be latched and
2761
put into a buffer. This feature is used in asynchronous mode.</P
2762
><P
2763
>Note: How to access multiple pieces of data acquired at each event?</P
2764
></DIV
2765
><DIV
2766
CLASS="SECTION"
2767
><H3
2768
CLASS="SECTION"
2769
><A
2770
NAME="AUXCOUNTER"
2771
>4.7.8. One source plus auxiliary counter configuration</A
2772
></H3
2773
><P
2774
><SPAN
2775
CLASS="strong"
2776
><B
2777
CLASS="EMPHASIS"
2778
>(Status: design. No driver implements this feature yet.)</B
2779
></SPAN
2780
></P
2781
><P
2782
>The <A
2783
HREF="x621.html#INSN-DATA-STRUCTURE-INSN"
2784
>insn</A
2785
> field of the
2786
<A
2787
HREF="x621.html#INSN-DATA-STRUCTURE"
2788
>instruction data structure</A
2789
>
2790
has not been assigned yet.</P
2791
><P
2792
>The <A
2793
HREF="x621.html#INSN-DATA-STRUCTURE-CHANSPEC"
2794
>chanspec</A
2795
> field
2796
of the <A
2797
HREF="x621.html#INSN-DATA-STRUCTURE"
2798
>instruction data
2799
structure</A
2800
> is used to ...</P
2801
><P
2802
>The <A
2803
HREF="x621.html#INSN-DATA-STRUCTURE-DATA"
2804
>data</A
2805
> field
2806
of the <A
2807
HREF="x621.html#INSN-DATA-STRUCTURE"
2808
>instruction data
2809
structure</A
2810
> is used as follows:</P
2811
><P
2812
><P
2813
></P
2814
><TABLE
2815
BORDER="0"
2816
><TBODY
2817
><TR
2818
><TD
2819
>data[1]: is flags, including the flags for the command triggering
2820
configuration. If a command is not subsequently issued on the
2821
subdevice, the command triggering portion of the flags are ignored.
2822
</TD
2823
></TR
2824
><TR
2825
><TD
2826
>data[2]: determines the mode of operation. The mode of operation
2827
is actually a bitfield that encodes what to do for various
2828
transitions of the source signals.</TD
2829
></TR
2830
><TR
2831
><TD
2832
>data[3], data[4]: determine the primary source for the counter,
2833
similar to the
2834
<A
2835
HREF="x621.html#COMMAND-DATA-STRUCT-SCAN-BEGIN-SRC"
2836
>_src</A
2837
> and the
2838
<A
2839
HREF="x621.html#COMMAND-DATA-STRUCT-SCAN-BEGIN-ARG"
2840
>_arg</A
2841
> fields
2842
used in the
2843
<A
2844
HREF="x621.html#COMMAND-DATA-STRUCT"
2845
>command data structure</A
2846
>.</TD
2847
></TR
2848
></TBODY
2849
></TABLE
2850
><P
2851
></P
2852
></P
2853
><P
2854
>Notes: How to specify which events cause a latch and push, and what
2855
should get latched?</P
2856
></DIV
2857
></DIV
2858
></DIV
2859
><DIV
2860
CLASS="NAVFOOTER"
2861
><HR
2862
ALIGN="LEFT"
2863
WIDTH="100%"><TABLE
2864
SUMMARY="Footer navigation table"
2865
WIDTH="100%"
2866
BORDER="0"
2867
CELLPADDING="0"
2868
CELLSPACING="0"
2869
><TR
2870
><TD
2871
WIDTH="33%"
2872
ALIGN="left"
2873
VALIGN="top"
2874
><A
2875
HREF="x403.html"
2876
ACCESSKEY="P"
2877
>Prev</A
2878
></TD
2879
><TD
2880
WIDTH="34%"
2881
ALIGN="center"
2882
VALIGN="top"
2883
><A
2884
HREF="index.html"
2885
ACCESSKEY="H"
2886
>Home</A
2887
></TD
2888
><TD
2889
WIDTH="33%"
2890
ALIGN="right"
2891
VALIGN="top"
2892
><A
2893
HREF="x1283.html"
2894
ACCESSKEY="N"
2895
>Next</A
2896
></TD
2897
></TR
2898
><TR
2899
><TD
2900
WIDTH="33%"
2901
ALIGN="left"
2902
VALIGN="top"
2903
>Writing <ACRONYM
2904
CLASS="ACRONYM"
2905
>Comedi</ACRONYM
2906
> programs</TD
2907
><TD
2908
WIDTH="34%"
2909
ALIGN="center"
2910
VALIGN="top"
2911
> </TD
2912
><TD
2913
WIDTH="33%"
2914
ALIGN="right"
2915
VALIGN="top"
2916
>Writing a <ACRONYM
2917
CLASS="ACRONYM"
2918
>Comedi</ACRONYM
2919
> driver</TD
2920
></TR
2921
></TABLE
2922
></DIV
2923
></BODY
2924
></HTML
2925
>
b'\\ No newline at end of file'
Loggerhead is a web-based interface for Breezy
Version: 2.0.1