1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4 <!ENTITY % comedilib_entities SYSTEM "comedilib.ent">
8 <section id="acquisitionfunctions">
10 Acquisition and configuration functions
14 This Section gives an overview of all &comedi; functions with which
15 application programmers can implement their data acquisition. (With
16 <quote>acquisition</quote> we mean all possible kinds of interfacing
17 with the cards: input, output, configuration, streaming, etc.)
18 <xref linkend="comedireference"/> explains the function calls in full
22 <section id="singleacquisition">
24 Functions for single acquisition
28 The simplest form of using &comedi; is to get one single sample to or
29 from an interface card. This sections explains how to do such simple
30 <link linkend="dio">digital</link> and
31 <link linkend="singleanalog">analog</link> acquisitions.
36 Single digital acquisition
40 Many boards supported by &comedi; have digital input and output
41 channels; i.e., channels that can only produce a <literal>0</literal>
42 or a <literal>1</literal>.
43 Some boards allow the <emphasis>direction</emphasis> (input or output)
44 of each channel to be specified independently in software.
48 &comedi; groups digital channels into a
49 <emphasis>subdevice</emphasis>, which is a group of digital channels
50 that have the same characteristics. For example, digital output lines
51 will be grouped into a digital
52 output subdevice, bidirectional digital lines will be grouped
53 into a digital I/O subdevice. Thus, there can be multiple
54 digital subdevices on a particular board.
58 Individual bits on a digital I/O device can be read and written using
61 int <link linkend="func-ref-comedi-dio-read">comedi_dio_read</link>(device,subdevice,channel,unsigned int *bit);
62 int <link linkend="func-ref-comedi-dio-write">comedi_dio_write</link>(device,subdevice,channel,unsigned int bit);
64 The <parameter class="function">device</parameter> parameter is a
65 <link linkend="ref-type-comedi-t">pointer</link>
66 to a successfully opened &comedi; device.
67 The <parameter class="function">subdevice</parameter> and
68 <parameter class="function">channel</parameter> parameters are positive
69 integers that indicate which subdevice and channel is used in the
70 acquisition. The integer <parameter class="function">bit</parameter>
71 contains the value of the acquired bit.
74 The direction of bidirectional lines can be configured using
77 <link linkend="func-ref-comedi-dio-config">comedi_dio_config</link>(device,subdevice,channel,unsigned int dir);
79 The parameter <parameter class="function">dir</parameter> should be
80 either <literal>COMEDI_INPUT</literal> or
81 <literal>COMEDI_OUTPUT</literal>.
82 Many digital I/O subdevices group channels into blocks for
83 configuring direction. Changing one channel in a block changes
88 Multiple channels can be read and written simultaneously using the
91 <link linkend="func-ref-comedi-dio-bitfield">comedi_dio_bitfield</link>(device,subdevice,unsigned int write_mask,unsigned int *bits);
93 Each channel is assigned to a bit in the
94 <parameter class="function">write_mask</parameter> and
95 <parameter class="function">bits</parameter>
97 <parameter class="function">write_mask</parameter> is set, the
98 corresponding bit in <parameter class="function">*bits</parameter> will
99 be written to the corresponding digital output line.
100 Each digital line is then read and placed into
101 <parameter class="function">*bits</parameter>. The value
102 of bits in <parameter class="function">*bits</parameter> corresponding
103 to digital output lines is undefined and device-specific. Channel
104 <literal>0</literal> is the least significant bit in the bitfield;
105 channel <literal>31</literal> is the most significant bit. Channels
106 higher than <literal>31</literal> cannot be accessed using this method.
110 The digital acquisition functions seem to be very simple, but, behind
111 the implementation screens of the &comedi; kernel module, they are
112 executed as special cases of the general
113 <link linkend="instructions">instruction</link> command.
120 <section id="singleanalog">
122 Single analog acquisition
125 Analog &comedi; channels can produce data values that are
126 <emphasis>samples</emphasis> from continuous analog signals.
127 These samples are integers with a significant content in
128 the range of, typically, <literal>8</literal>, <literal>10</literal>,
129 <literal>12</literal>, or <literal>16</literal> bits.
134 int <link linkend="func-ref-comedi-data-read">comedi_data_read</link>(<link linkend="ref-type-comedi-t">comedi_t</link> * device, unsigned int subdevice, unsigned int channel,
135 unsigned int range, unsigned int aref, <link linkend="ref-type-lsampl-t">lsampl_t</link> * data);
137 function reads one such data value from a &comedi; channel, and puts it in
138 the user-specified <parameter>data</parameter> buffer. The
140 int <link linkend="func-ref-comedi-data-write">comedi_data_write</link>(<link linkend="ref-type-comedi-t">comedi_t</link> * device, unsigned int subdevice, unsigned int channel,
141 unsigned int range, unsigned int aref, <link linkend="ref-type-lsampl-t">lsampl_t</link> data);
143 works in the opposite direction. Data values returned by this function
144 are unsigned integers less than, or equal to, the maximum sample value
145 of the channel, which can be determined using the function
147 <link linkend="ref-type-lsampl-t">lsampl_t</link> <link linkend="func-ref-comedi-get-maxdata">comedi_get_maxdata</link>(<link linkend="ref-type-comedi-t">comedi_t</link> * device, unsigned int subdevice, unsigned int channel);
149 Conversion of data values to physical units can be performed by the
152 double <link linkend="func-ref-comedi-to-phys">comedi_to_phys</link>(<link linkend="ref-type-lsampl-t">lsampl_t</link> data, comedi_range * range, <link linkend="ref-type-lsampl-t">lsampl_t</link> maxdata);
154 There are two data structures in these commands that are not fully
160 <link linkend="ref-type-comedi-t">comedi_t</link>: this data structure
161 contains all information that a user program has to know about an
162 <emphasis>open</emphasis> &comedi; device. The programmer doesn't have
163 to fill in this data structure manually: it gets filled in by opening
170 <link linkend="ref-type-lsampl-t">lsampl_t</link>: this
171 <quote>data structure</quote> represents one single sample. On most
172 architectures, it's nothing more than a 32 bits value. Internally,
173 &comedi; does some conversion from raw sample data to
174 <quote>correct</quote> integers. This is called <quote>data
182 Each single acquisition by, for example,
184 <link linkend="func-ref-comedi-data-read">comedi_data_read()</link>
186 requires quite some overhead, because all the arguments of the
187 function call are checked. If multiple acquisitions must be done on
188 the same channel, this overhead can be avoided by using a function
189 that can read more than one sample:
191 int <link linkend="func-ref-comedi-dio-read">comedi_data_read_n</link>(<link linkend="ref-type-comedi-t">comedi_t</link> *it, unsigned int subdev, unsigned int chan, unsigned int range,
192 unsigned int aref, <link linkend="ref-type-lsampl-t">lsampl_t</link> *data, unsigned int n)
194 The number of samples, <parameter class="function">n</parameter>, is
195 limited by the &comedi; implementation (to a maximum of 100 samples),
196 because the call is blocking.
199 The start of the data acquisition can also be delayed by a specified
200 number of nano-seconds:
202 int <link linkend="func-ref-comedi-data-read-delayed">comedi_data_read_delayed</link>(<link linkend="ref-type-comedi-t">comedi_t</link> *it, unsigned int subdev, unsigned int chan, unsigned int range,
203 unsigned int aref, <link linkend="ref-type-lsampl-t">lsampl_t</link> *data, unsigned int nano_sec)
205 All these read and write acquisition functions are implemented on top
206 of the generic <link linkend="instructions">instruction</link>
215 <section id="instructions">
217 Instructions for multiple acquisitions
220 The <emphasis>instruction</emphasis> is one of the most generic,
221 overloaden and flexible functions in the &comedi; API. It is used to
222 execute a multiple of identical acquisitions on the same channel, but
224 <link linkend="instructionsconfiguration">configuration</link> of a
226 <anchor id="anchor.instruction.list"/>
227 An <emphasis>instruction list</emphasis> is a list of instructions,
228 possibly on different channels. Both instructions and instructions
229 lists are executed <emphasis>synchronously</emphasis>, i.e., while
230 <emphasis role="strong">blocking</emphasis> the calling process.
231 This is one of the limitations of instructions; the other one is that
232 they cannot code an acquisition involving timers or external events.
233 These limits are eliminated by the
234 <link linkend="commandsstreaming">command</link> acquisition
239 <section id="comediinsnstructure">
241 The instruction data structure
244 All the information needed to execute an instruction is stored in the
245 <link linkend="ref-type-comedi-insn">comedi_insn</link>
248 struct <anchor id="insn-data-structure"/>comedi_insn_struct{
249 <anchor id="insn-data-structure-insn"/>unsigned int insn; // integer encoding the type of acquisition
250 // (or configuration)
251 unsigned int n; // number of elements in data array
252 <link linkend="ref-type-lsampl-t">lsampl_t</link> <anchor id="insn-data-structure-data"/>*data; // pointer to data buffer
253 unsigned int subdev; // subdevice
254 unsigned int <anchor id="insn-data-structure-chanspec"/><link linkend="ref-macro-CR-PACK">chanspec</link>; // encoded channel specification
255 unsigned int unused[3];
258 Because of the large flexibility of the instruction function, many
259 types of instruction do not need to fill in all fields, or attach
260 different meanings to the same field. But the current implementation
261 of &comedi; requires the
262 <link linkend="insn-data-structure-data">data</link> field to be at
267 The <link linkend="insn-data-structure-insn">insn</link> flag of the
268 <link linkend="insn-data-structure">instruction data structure</link>
269 determines the type of acquisition executed in the corresponding
275 INSN_READ: the instruction executes a read on an analog channel.
281 INSN_WRITE: the instruction executes a write on an analog channel.
287 INSN_BITS: indicates that the instruction must
288 read or write values on multiple digital I/O channels.
294 INSN_GTOD: the instruction performs a <quote>Get Time Of Day</quote>
301 INSN_WAIT: the instruction blocks for a specified number of
312 <section id="instructionexecution">
314 Instruction execution
317 Once an instruction data structure has been filled in, the
318 corresponding instruction is executed as follows:
320 int <link linkend="func-ref-comedi-do-insn">comedi_do_insn</link>(<link linkend="ref-type-comedi-t">comedi_t</link> *it, <link linkend="ref-type-comedi-insn">comedi_insn</link> * instruction);
322 Many &comedi; instructions are shortcuts that relieve the programmer
323 from explicitly filling in the data structure and calling the
324 <link linkend="func-ref-comedi-do-insn">comedi_do_insn</link>
330 int <link linkend="func-ref-comedi-do-insnlist">comedi_do_insnlist</link><link linkend="ref-type-comedi-t">comedi_t</link> *it, <link linkend="ref-type-comedi-insnlist">comedi_insnlist</link> * list)
332 instruction allows to perform a list of instructions in one function
333 call. The number of instructions in the list is limited in the
334 implementation, because instructions are executed
335 <emphasis>synchronously</emphasis>, i.e., the call blocks until the
336 whole instruction (list) has finished.
344 <section id="instructionsconfiguration">
346 Instructions for configuration
349 <xref linkend="instructions"/> explains how instructions are used to do
350 <emphasis>acquisition</emphasis> on channels. This section explains
351 how they are used to <emphasis>configure</emphasis> a subdevice.
352 There are various sorts of configurations, and the
353 specific information for each different configuration possibility is
354 to be specified via the
355 <link linkend="insn-data-structure-data">data</link> buffer of the
356 <link linkend="insn-data-structure">instruction data structure</link>.
357 (So, the pointer to a
358 <link linkend="ref-type-lsampl-t">lsampl_t</link>
359 is misused as a pointer to an array with board-specific information.)
363 Using INSN_CONFIG as the
364 <link linkend="insn-data-structure-insn">insn</link> flag in an
365 <link linkend="insn-data-structure">instruction data structure</link>
366 indicates that the instruction will
367 <emphasis>not perform acquisition</emphasis> on a
368 channel, but will <emphasis>configure</emphasis> that channel.
370 <link linkend="ref-macro-CR-PACK">chanspec</link> field in the
371 <link linkend="insn-data-structure-chanspec">comedi_insn</link>
372 data structure, contains the channel to be configured.
373 The zeroth element of the data array
374 is always an id that specifies
375 what type of configuration instruction is being performed. The
376 meaning of rest of the elements in the data array
377 depend on the configuration instruction id.
379 possible ids are summarised in the table below, along with the
380 meanings of the data array elements for
381 each type of configuration instruction.
385 <tgroup cols='4' align='left'>
386 <colspec colwidth='4*' />
387 <colspec colwidth='4*' />
388 <colspec colwidth='1*' />
389 <colspec colwidth='4*' />
392 <entry>data[0]</entry>
393 <entry>Description</entry>
394 <entry>n (number of elements in data array)</entry>
395 <entry>Meanings of data[1], ..., data[n-1]</entry>
400 <entry>INSN_CONFIG_DIO_INPUT</entry>
402 Configure a dio line as input. It is easier to use comedi_dio_config() than
403 to use this configuration instruction directly.
411 <entry>INSN_CONFIG_DIO_OUTPUT</entry>
413 Configure a dio line as output. It is easier to use comedi_dio_config() than
414 to use this configuration instruction directly.
422 <entry>INSN_CONFIG_ALT_SOURCE</entry>
424 Select an alternate input source. This instruction is
425 used by comedi_calibrate to configure analog input channels
426 which can be redirected to read internal calibration
427 references. You need to set the CR_ALT_SOURCE flag in the chanspec
428 when reading to actually read from the configured alternate input source.
429 If you are using comedi_data_read(), then the channel parameter can be
430 bitwise or'd with the CR_ALT_SOURCE flag.
434 data[1]: alternate input source.
438 <entry>INSN_CONFIG_BLOCK_SIZE</entry>
440 Specify block size for asynchonous command data.
441 When performing streaming input, many boards accumulate
442 samples in internal fifos and transfer them to the host
443 computer in chunks. Some drivers let you suggest a size in bytes for how big a
444 the chunks should be. This lets you tune how often the host computer is
445 interrupted with a new chunk of data.
449 data[1]: The desired block size in bytes. The actual configured block size is
450 writen back to data[1] after the instruction completes. This instruction
451 acts purely as a query if the block size is set to zero.
455 <entry>INSN_CONFIG_DIO_QUERY</entry>
457 Queries the configuration of a dio line to see if it is an input or output.
458 It is probably easier to use the comedilib function comedi_dio_get_config()
459 than to use this instruction directly.
463 data[1]: The instruction sets this element to either COMEDI_INPUT or COMEDI_OUTPUT.
471 See the comedilib demo program demo/choose_clock.c for an example
472 of using a configuration instruction.
478 <section id="inttrigconfiguration">
480 Instruction for internal triggering
483 This special instruction has
484 <anchor id="insn-inttrig"/>INSN_INTTRIG as the
485 <link linkend="insn-data-structure-insn">insn</link> flag in its
486 <link linkend="insn-data-structure">instruction data structure</link>.
487 Its execution causes an
488 <link linkend="trig-int-start-src">internal triggering event</link>. This
489 event can, for example, cause the device driver to start a conversion,
490 or to stop an ongoing acquisition. The exact meaning of the triggering
491 depends on the card and its particular driver.
495 <link linkend="insn-data-structure-data">data</link>[0] field of the
496 INSN_INTTRIG instruction is reserved for future use, and should be set
503 <section id="commandsstreaming">
505 Commands for streaming acquisition
509 The most powerful &comedi; acquisition primitive is the
510 <emphasis>command</emphasis>. It's powerful because, with one single
511 command, the programmer launches:
516 a possibly infinite <emphasis>sequence of acquisitions</emphasis>,
522 accompanied with various <emphasis>callback</emphasis> functionalities
523 (DMA, interrupts, driver-specific callback functions),
529 for <emphasis>any number of channels</emphasis>,
535 with an <emphasis>arbitrary order</emphasis> of channels in each scan
536 (possibly even with repeated channels per scan),
542 and with various scan <emphasis>triggering sources</emphasis>,
543 external (i.e., hardware pulses) as well as internal (i.e., pulses
544 generated on the DAQ card itself, or generated by a
545 <link linkend="inttrigconfiguration">software trigger instruction</link>).
550 This command functionality exists in the &comedi; API, because various
551 data acquisition devices have the capability to perform this kind of
552 complex acquisition, driven by either on-board or
553 off-board timers and triggers.
557 A command specifies a particular data
558 <link linkend="fig-acq-seq">acquisition sequence</link>, which
559 consists of a number of <emphasis>scans</emphasis>, and each scan is
560 comprised of a number of <emphasis>conversions</emphasis>, which
561 usually corresponds to a single A/D or D/A conversion. So, for
562 example, a scan could consist of sampling channels 1, 2 and 3 of a
563 particular device, and this scan should be repeated 1000 times, at
564 intervals of 1 millisecond apart.
567 The command function is complementary to the
568 <link linkend="instructionsconfiguration">configuration instruction</link>
569 function: each channel in the command's
570 <link linkend="command-data-struct-chanlist">chanlist</link>
571 should first be configured by an appropriate instruction.
575 <section id="executingcommand">
581 A commands is executed by the following &comedi; function:
583 int <link linkend="func-ref-comedi-command">comedi_command</link>(<link linkend="ref-type-comedi-t">comedi_t</link> * device, <link linkend="ref-type-comedi-cmd">comedi_cmd</link> * command);
585 The following sections explain the meaning of the
586 <link linkend="ref-type-comedi-cmd">comedi_cmd</link> data structure.
587 Filling in this structure can be quite complicated, and
588 requires good knowledge about the exact functionalities of the DAQ
589 card. So, before launching a command, the application programmer is
590 adviced to check whether this complex command data structure can be
591 successfully parsed. So, the typical sequence for executing a command is
592 to first send the command through
593 <link linkend="func-ref-comedi-command-test">comedi_command_test()</link>
594 once or twice. The test will check that the command is valid for the
595 particular device, and often makes some adjustments to the command
596 arguments, which can then be read back by the user to see the actual
600 A &comedi; program can find out on-line what the command capabilities
601 of a specific device are, by means of the
602 <link linkend="func-ref-comedi-get-cmd-src-mask">comedi_get_cmd_src_mask()</link>
609 <section id="comedicmdstructure">
611 The command data structure
614 The command executes according to the information about the requested
615 acquisition, which is stored in the
616 <link linkend="ref-type-comedi-cmd">comedi_cmd</link>
617 <anchor id="command-data-struct"/>data structure:
619 typedef struct comedi_cmd_struct comedi_cmd;
621 struct comedi_cmd_struct{
622 unsigned int subdev; // which subdevice to sample
623 unsigned int <anchor id="command-data-struct-flags"/>flags; // encode some configuration possibilities
624 // of the command execution; e.g.,
625 // whether a callback routine is to be
626 // called at the end of the command
628 unsigned int <anchor id="command-data-struct-start-src"/>start_src; // event to make the acquisition start
629 unsigned int <anchor id="command-data-struct-start-arg"/>start_arg; // parameters that influence this start
631 unsigned int <anchor id="command-data-struct-scan-begin-src"/>scan_begin_src; // event to make a particular scan start
632 unsigned int <anchor id="command-data-struct-scan-begin-arg"/>scan_begin_arg; // parameters that influence this start`
634 unsigned int <anchor id="command-data-struct-convert-src"/>convert_src; // event to make a particular conversion start
635 unsigned int <anchor id="command-data-struct-convert-arg"/>convert_arg; // parameters that influence this start
637 unsigned int <anchor id="command-data-struct-scan-end-src"/>scan_end_src; // event to make a particular scan terminate
638 unsigned int <anchor id="command-data-struct-scan-end-arg"/>scan_end_arg; // parameters that influence this termination
640 unsigned int <anchor id="command-data-struct-stop-src"/>stop_src; // what make the acquisition terminate
641 unsigned int <anchor id="command-data-struct-stop-arg"/>stop_arg; // parameters that influence this termination
643 unsigned int <anchor id="command-data-struct-chanlist"/>*chanlist; // pointer to list of channels to be sampled
644 unsigned int <anchor id="command-data-struct-chanlist-len"/>chanlist_len; // number of channels to be sampled
646 sampl_t *<anchor id="command-data-struct-data"/>data; // address of buffer
647 unsigned int <anchor id="command-data-struct-data-len"/>data_len; // number of samples to acquire
650 The start and end of the whole command acquisition sequence, and the
651 start and end of each scan and of each conversion, is triggered by a
652 so-called <emphasis>event</emphasis>. More on these in
653 <xref linkend="comedicmdsources"/>.
657 The <parameter class="function">subdev</parameter> member of the
658 <link linkend="ref-type-comedi-cmd">comedi_cmd</link> structure is
659 the index of the subdevice the command is intended for. The
660 <link linkend="func-ref-comedi-find-subdevice-by-type">comedi_find_subdevice_by_type()</link>
661 function can be useful in discovering the index of your desired subdevice.
665 The <link linkend="command-data-struct-chanlist">chanlist</link>
667 <link linkend="ref-type-comedi-cmd">comedi_cmd</link> data
668 structure should point to an array whose number of elements is
670 <link linkend="command-data-struct-chanlist-len">chanlist_len</link>
671 (this will generally be the same as the
672 <link linkend="command-data-struct-scan-end-arg">scan_end_arg</link>).
674 <link linkend="command-data-struct-chanlist">chanlist</link>
675 specifies the sequence of channels and gains (and analog references)
676 that should be stepped through for each scan. The elements of the
677 <link linkend="command-data-struct-chanlist">chanlist</link> array should be
678 initialized by <quote>packing</quote> the channel, range and reference
679 information together with the
680 <parameter class="function">
681 <link linkend="ref-macro-CR-PACK">CR_PACK()</link>
687 The <link linkend="command-data-struct-data">data</link> and
688 <link linkend="command-data-struct-data-len">data_len</link>
689 members can be safely ignored when issueing commands from a user-space
690 program. They only have meaning when a command is sent from a
691 <emphasis role="strong">kernel</emphasis> module using the
692 <function>kcomedilib</function> interface, in which case they specify
693 the buffer where the driver should write/read its data to/from.
697 The final member of the
698 <link linkend="command-data-struct">comedi_cmd</link> structure is the
699 <link linkend="command-data-struct-flags">flags</link> field,
700 i.e., bits in a word that can be bitwise-or'd together. The meaning of
701 these bits are explained in a
702 <link linkend="source.flags.anchor">later section</link>.
708 <section id="comedicmdsources">
710 The command trigger events
711 <anchor id="source.trigger.anchor"/>
714 A command is a very versatile acquisition instruction, in the sense
715 that it offers lots of possibilities to let different hardware and
716 software sources determine when acquisitions are started, performed,
717 and stopped. More specifically, the command
718 <link linkend="command-data-struct">data structure</link>
719 has <emphasis>five</emphasis> types of events: start the
720 <link linkend="acquisitionterminology">acquisition</link>,
721 start a <link linkend="scan">scan</link>, start a
722 <link linkend="conversion">conversion</link>, stop a scan, and stop
723 the acquisition. Each event can be given its own
724 <emphasis><link linkend="source.trigger.anchor">source</link></emphasis>
725 (the <parameter class="function">*_src</parameter> members in the
726 <link linkend="ref-type-comedi-cmd">comedi_cmd</link> data
727 structure). And each event source can have a corresponding
728 argument (the <parameter class="function">*_arg</parameter> members of
729 the <link linkend="ref-type-comedi-cmd">comedi_cmd</link> data
730 structure) whose meaning depends on the type of source trigger.
731 For example, to specify an external digital line <quote>3</quote> as a
732 source (in general, <emphasis>any</emphasis> of the five event
733 sources), you would use
734 <parameter>src</parameter>=<link linkend="trig-ext">TRIG_EXT</link> and
735 <parameter>arg</parameter>=3.
738 The following paragraphs discuss in somewhat more detail the trigger
739 event sources(<parameter class="function">*_src</parameter>), and the
740 corresponding arguments (<parameter class="function">*_arg</parameter>).
743 The start of an acquisition is controlled by the
744 <link linkend="command-data-struct-start-src">start_src</link> events.
745 The available options are:
750 <anchor id="trig-now-start-src"/>
752 <link linkend="command-data-struct-start-src">start_src</link>
754 <link linkend="command-data-struct-start-arg">start_arg</link>
755 nanoseconds after the
756 <link linkend="ref-type-comedi-cmd">comedi_cmd</link>
757 is called. Currently, only
758 <link linkend="command-data-struct-start-arg">start_arg</link>=0 is
765 <anchor id="trig-follow-start-src"/>
766 TRIG_FOLLOW: (For an output device.) The
767 <link linkend="command-data-struct-start-src">start_src</link>
768 event occurs when data is written to the buffer.
774 <anchor id="trig-ext-start-src"/>
775 TRIG_EXT: the start event occurs when an external trigger signal
776 occurs; e.g., a rising edge of a digital line.
777 <link linkend="command-data-struct-start-arg">start_arg</link>
778 chooses the particular digital line.
784 <anchor id="trig-int-start-src"/>
785 TRIG_INT: the start event occurs on a &comedi; internal signal, which
786 is typically caused by an
787 <link linkend="insn-inttrig">INSN_INTTRIG instruction</link>.
792 The start of the beginning of each
793 <link linkend="scan">scan</link> is controlled by the
794 <link linkend="command-data-struct-scan-begin-src">scan_begin</link> events.
795 The available options are:
800 <anchor id="trig-timer-start-scan"/>
802 <link linkend="command-data-struct-scan-begin-src">scan_begin</link>
803 events occur periodically. The time between
804 <link linkend="command-data-struct-scan-begin-src">scan_begin</link>
806 <link linkend="command-data-struct-convert-arg">convert_arg</link>
813 <anchor id="trig-follow-start-scan"/>
815 <link linkend="command-data-struct-scan-begin-src">scan_begin</link>
816 event occurs immediately after a
817 <link linkend="command-data-struct-scan-end-src">scan_end</link>
824 <anchor id="trig-ext-start-scan"/>
826 <link linkend="command-data-struct-scan-begin-src">scan_begin</link>
827 event occurs when an external trigger signal
828 occurs; e.g., a rising edge of a digital line.
829 <link linkend="command-data-struct-scan-begin-arg">scan_begin_arg</link>
830 chooses the particular digital line.
836 <link linkend="command-data-struct-scan-begin-arg">scan_begin_arg</link>
837 used here may not be supported exactly by the device, but it
838 will be adjusted to the nearest supported value by
839 <link linkend="func-ref-comedi-command-test">comedi_command_test()</link>.
842 The timing between each sample in a
843 <link linkend="scan">scan</link> is controlled by the
844 <link linkend="command-data-struct-convert-src">convert_*</link>
850 <anchor id="convert-trig-timer"/>
851 <anchor id="trig-timer"/>
852 TRIG_TIMER: the conversion events occur periodically. The time
853 between convert events is
854 <link linkend="command-data-struct-convert-arg">convert_arg</link>
861 <anchor id="convert-trig-ext"/>
862 <anchor id="trig-ext"/>
863 TRIG_EXT: the conversion events occur when an external trigger signal
864 occurs, e.g., a rising edge of a digital line.
865 <link linkend="command-data-struct-convert-arg">convert_arg</link>
866 chooses the particular digital line.
872 <anchor id="convert-trig-now"/>
873 <anchor id="trig-now"/>
874 TRIG_NOW: All conversion events in a
875 <link linkend="scan">scan</link> occur simultaneously.
880 The <emphasis>end</emphasis> of each scan is almost always specified
882 <link linkend="trig-count">TRIG_COUNT</link>, with the argument being
883 the same as the number of channels in the
884 <link linkend="command-data-struct-chanlist">chanlist</link>. You
885 could probably find a device that allows something else, but it would
890 <link linkend="acquisitionterminology">acquisition</link> is
892 <link linkend="command-data-struct-stop-src">stop_src</link>
893 and <link linkend="command-data-struct-stop-arg">stop_arg</link>:
898 <anchor id="acquisition-end-trig-count"/>
899 <anchor id="trig-count"/>
900 TRIG_COUNT: stop the acquisition after
901 <link linkend="command-data-struct-stop-arg">stop_arg</link>
908 <anchor id="acquisition-end-trig-none"/>
909 <anchor id="trig-none"/>
910 TRIG_NONE: perform continuous acquisition, until stopped using
911 <link linkend="func-ref-comedi-cancel">comedi_cancel()</link>.
914 Its argument is reserved and should be set to 0.
915 (<quote>Reserved</quote>
916 means that unspecified things could happen if it is set to something
922 There are a couple of less usual or not yet implemented events:
927 <anchor id="trig-time"/>
929 cause an event to occur at a particular time.
932 (This event source is reserved for future use.)
938 <anchor id="trigother-event"/>
939 TRIG_OTHER: driver specific event trigger.
942 This event can be useful as any of the trigger sources. Its exact
943 meaning is driver specific, because it implements a feature that
944 otherwise does not fit into the generic &comedi; command interface.
945 Configuration of TRIG_OTHER features are done by
946 <link linkend="instructionsconfiguration">INSN_CONFIG</link>
950 The argument is reserved and should be set to 0.
955 Not all event sources are applicable to all events. Supported
956 trigger sources for specific events depend significantly on your
957 particular device, and even more on the current state of its device
959 <link linkend="func-ref-comedi-get-cmd-src-mask">comedi_get_cmd_src_mask()</link>
960 function is useful for determining what trigger sources a subdevice
967 <section id="comedicmdflags">
970 <anchor id="source.flags.anchor"/>
975 <link linkend="command-data-struct-flags">flags</link> field in the
976 <link linkend="ref-type-comedi-cmd">command data structure</link>
977 is used to specify some <quote>behaviour</quote> of the acquisitions in
979 The meaning of the field is as follows:
984 <anchor id="trig-rt"/>
985 TRIG_RT: ask the driver to use a
986 <emphasis role="strong">hard real-time</emphasis> interrupt handler.
987 This will reduce latency in handling interrupts from your data
989 hardware. It can be useful if you are sampling at high frequency, or
990 if your hardware has a small onboard data buffer. You must have a
991 real-time kernel (<ulink url="http://www.rtai.org">RTAI</ulink> or
992 <ulink url="http://www.rtlinux-gpl.org/">RTLinux/GPL</ulink>)
993 and must compile &comedi; with real-time support, or this flag will do
1000 <anchor id="trig-wake-eos"/>
1002 where <quote>EOS</quote> stands for <quote>End of Scan</quote>. Some
1003 drivers will change their behaviour when this flag is set, trying to
1004 transfer data at the end of every scan (instead of, for example,
1005 passing data in chunks whenever the board's hardware data buffer is
1006 half full). This flag may degrade a driver's performance at high
1007 frequencies, because the end of a scan is, in general, a much more
1008 frequent event than the filling up of the data buffer.
1014 <anchor id="trig-round-nearest"/>
1016 round to nearest supported timing period, the default.
1017 This flag (as well as the following three), indicates how timing
1018 arguments should be rounded if the hardware cannot achieve the exact
1025 <anchor id="trig-round-down"/>
1026 TRIG_ROUND_DOWN: round period down.
1032 <anchor id="trig-round-up"/>
1033 TRIG_ROUND_UP: round period up.
1039 <anchor id="trig-round-up-next"/>
1041 this one doesn't do anything, and I don't know what it was intended
1048 <anchor id="trig-dither"/>
1049 TRIG_DITHER: enable dithering? Dithering is a software technique to
1050 smooth the influence of discretization <quote>noise</quote>.
1056 <anchor id="trig-deglitch"/>
1057 TRIG_DEGLITCH: enable deglitching? Another <quote>noise</quote>
1058 smoothing technique.
1064 <anchor id="trig-write"/>
1066 write to bidirectional devices. Could be useful, in principle, if
1067 someone wrote a driver that supported commands for a digital I/O
1068 device that could do either input or output.
1074 <anchor id="trig-bogus"/>
1075 TRIG_BOGUS: do the motions?
1081 <anchor id="trig-other"/>
1082 TRIG_CONFIG: perform configuration, not triggering. This is a legacy
1084 <link linkend="ref-type-comedi-cmd">comedi_trig_struct</link>
1085 data structure, and has no function at present.
1099 If you wish to aquire accurate waveforms, it is vital that you use an
1100 anti-alias filter. An anti-alias filter is a low-pass filter used to
1101 remove all frequencies higher than the Nyquist frequency (half your sampling rate)
1102 from your analog input signal
1103 before you convert it to digital. If you fail to filter your input signal,
1104 any high frequency components in the original analog signal will create
1105 artifacts in your recorded digital waveform that cannot be corrected.
1108 For example, suppose you are sampling an analog input channel at a rate of
1109 1000 Hz. If you were to apply a 900 Hz sine wave to the input, you
1110 would find that your
1111 sampling rate is not high enough to faithfully record the 900 Hz input,
1112 since it is above your Nyquist frequency of 500 Hz. Instead, what you
1113 will see in your recorded digital waveform is a 100 Hz sine wave! If you
1114 don't use an anti-alias filter, it is impossible to tell whether the 100
1115 Hz sine wave you see in your digital signal was really produced by a
1116 100 Hz input signal, or a 900 Hz signal aliased to 100 Hz, or a 1100 Hz
1120 In practice, the cutoff frequency for the anti-alias filter is usually
1121 set 10% to 20% below the Nyquist frequency due to fact that real filters
1122 do not have infinitely sharp cutoffs.
1128 <section id="slowlyvarying">
1130 Slowly-varying inputs
1134 Sometimes, your input channels change slowly enough that
1135 you are able to average many successive input values to get a
1136 more accurate measurement of the actual value. In general,
1137 the more samples you average, the better your estimate
1138 gets, roughly by a factor of sqrt(number_of_samples).
1139 Obviously, there are limitations to this:
1146 you are ultimately limited by <quote>Spurious Free Dynamic
1147 Range</quote>. This SFDR is one of the popular measures to quantify how
1148 much noise a signal carries. If you take a Fourier transform of your
1149 signal, you will see several <quote>peaks</quote> in the transform: one
1150 or more of the fundamental harmonics of the measured signal, and lots
1151 of little <quote>peaks</quote> (called <quote>spurs</quote>) caused by
1152 noise. The SFDR is then the difference between the amplitude of the
1153 fundamental harmonic and of the largest spur (at frequencies below
1154 half of the Nyquist frequency of the DAQ sampler!).
1160 you need to have <emphasis>some</emphasis> noise on the input channel,
1161 otherwise you will be averaging the same number <literal>N</literal>
1162 times. (Of course, this only holds if the noise is large enough to
1163 cause at least a one-bit discretization.)
1169 the more noise you have, the greater your SFDR, but it
1170 takes many more samples to compensate for the increased
1177 if you feel the need to average samples for, for example, two seconds,
1178 your signal will need to be <emphasis>very</emphasis> slowly-varying,
1179 i.e., not varying more than your target uncertainty for the entire two
1187 As you might have guessed, the &comedi; library has functions
1188 to help you in your quest to accurately measure slowly varying
1191 int <link linkend="func-ref-comedi-sv-init">comedi_sv_init</link>(<link linkend="ref-type-comedi-sv-t">comedi_sv_t</link> * sv, <link linkend="ref-type-comedi-t">comedi_t</link> * device, unsigned int subdevice, unsigned int channel);
1193 This function initializes the
1194 <link linkend="ref-type-comedi-sv-t">comedi_sv_t</link> data structure, used
1195 to do the averaging acquisition:
1197 struct comedi_sv_struct{
1198 <link linkend="ref-type-comedi-t">comedi_t</link> *dev;
1199 unsigned int subdevice;
1206 /* number of measurements to average (for analog inputs) */
1212 The actual acquisition is done with:
1214 int <link linkend="func-ref-comedi-sv-measure">comedi_sv_measure</link>(<link linkend="ref-type-comedi-sv-t">comedi_sv_t</link> * sv, double * data);
1216 The number of samples over which the
1217 <function>comedi_sv_measure()</function> averages is limited by the
1218 implementation (currently the limit is 100 samples).
1222 One typical use for this function is the measurement of thermocouple
1224 And the &comedi; self-calibration utility also uses these functions.
1225 On some hardware, it is possible to tell it to measure an
1226 internal stable voltage reference, which is typically going
1227 to be very slowly varying; on the kilosecond time scale
1228 or more. So, it is reasonable to measure millions of samples,
1229 to get a very accurate measurement of the A/D converter output
1230 value that corresponds to the voltage reference. Sometimes,
1231 however, this is overkill, since there is no need to
1232 perform a part-per-million calibration to a standard that
1233 is only accurate to a part-per-thousand.
1238 <section id="experimentalfunctionality">
1240 Experimental functionality
1244 The following subsections document functionality that has not yet
1245 matured. Most of this functionality has even not been implemented yet
1246 in any single device driver. This information is included here, in
1247 order to stimulate discussion about their API, and to encourage
1248 pioneering implementations.
1251 <section id="digitalinputcombining">
1253 Digital input combining machines
1257 (<emphasis role="strong">Status: experimental (i.e., no driver implements
1258 this yet)</emphasis>)
1261 When one or several digital inputs are used to modify an output
1262 value, either an accumulator or a single digital line or bit,
1263 a bitfield structure is typically used in the &comedi; interface.
1264 The digital inputs have two properties, <quote>sensitive</quote> inputs
1265 and <quote>modifier</quote> inputs. Edge transitions on sensitive
1266 inputs cause changes in the output signal, whereas modifier inputs
1267 change the effect of edge transitions on sensitive inputs. Note that
1268 inputs can be both modifier inputs and sensitive inputs.
1272 For simplification purposes, it is assumed that multiple digital
1273 inputs do not change simultaneously.
1277 The combined state of the modifier inputs determine a modifier
1278 state. For each combination of modifier state and sensitive
1279 input, there is a set of bits that determine the effect on the
1280 output value due to positive or negative transitions of the
1281 sensitive input. For each transition direction, there are two
1282 bits defined as follows:
1284 <variablelist spacing="compact">
1287 <listitem>transition is ignored.</listitem>
1291 <listitem>accumulator is incremented, or output is set.</listitem>
1295 <listitem>accumulator is decremented, or output is cleared.</listitem>
1299 <listitem>reserved.</listitem>
1303 For example, a simple digital follower is specified by the bit
1304 pattern 01 10, because it sets the output on positive transitions
1305 of the input, and clears the output on negative transitions. A
1306 digital inverter is similarily 10 01. These systems have only
1307 one sensitive input.
1311 As another example, a simple up counter, which increments on
1312 positive transitions of one input, is specified by 01 00. This
1313 system has only one sensitive input.
1317 When multiple digital inputs are used, the inputs are divided
1318 into two types, inputs which cause changes in the accumulator, and
1319 those that only modify the meaning of transitions on other inputs.
1320 Modifier inputs do not require bitfields, but there needs to be
1321 a bitfield of length 4*(2^(N-1)) for each edge sensitive input,
1322 where N is the total number of inputs. Since N is usually 2 or
1323 3, with only one edge sensitive input, the scaling issues are
1330 <section id="analogconversion">
1332 Analog filtering configuration
1336 <emphasis role="strong">(Status: design (i.e., no driver implements
1337 this yet).)</emphasis>
1341 The <link linkend="insn-data-structure-insn">insn</link> field of the
1342 <link linkend="insn-data-structure">instruction data structure</link>
1343 has not been assigned yet.
1346 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1347 of the <link linkend="insn-data-structure">instruction data
1348 structure</link> is ignored.
1352 Some devices have the capability to add white noise (dithering) to
1353 analog input measurement. This additional noise can then be averaged
1354 out, to get a more accurate measurement of the input signal. It
1355 should not be assumed that channels can be separately configured.
1356 A simple design can use 1 bit to turn this feature on/off.
1360 Some devices have the capability of changing the glitch characteristics
1361 of analog output subsytems. The default (off) case should be where
1362 the average settling time is lowest. A simple design can use 1 bit
1363 to turn this feature on/off.
1367 Some devices have a configurable analog filters as part of the analog
1368 input stage. A simple design can use 1 bit to enable/disable the
1369 filter. Default is disabled, i.e., the filter being bypassed, or if
1370 the choice is between two filters, the filter with the largest
1375 <section id="waveformgeneration">
1377 Analog Output Waveform Generation
1381 <emphasis role="strong">(Status: design (i.e., no driver implements
1382 this yet).)</emphasis>
1385 The <link linkend="insn-data-structure-insn">insn</link> field of the
1386 <link linkend="insn-data-structure">instruction data structure</link>
1387 has not been assigned yet.
1390 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1391 of the <link linkend="insn-data-structure">instruction data
1392 structure</link> is ignored.
1396 Some devices have the ability to cyclicly loop through samples kept in
1397 an on-board analog output FIFO. This config should allow the user to
1398 enable/disable this mode.
1402 This config should allow the user to configure the number of samples
1403 to loop through. It may be necessary to configure the channels used.
1408 <section id="extendedtriggering">
1413 <emphasis role="strong">(Status: alpha.)</emphasis>
1417 The <link linkend="insn-data-structure-insn">insn</link> field of the
1418 <link linkend="insn-data-structure">instruction data structure</link>
1419 has not been assigned yet.
1422 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1423 of the <link linkend="insn-data-structure">instruction data
1424 structure</link> is ignored.
1428 This section covers common information for all extended
1429 triggering configuration, and doesn't describe a particular
1430 type of extended trigger.
1434 Extended triggering is used to configure triggering engines that
1435 do not fit into commands. In a typical programming sequence, the
1436 application will use
1437 <link linkend="instructionsconfiguration">configuration instructions</link>
1438 to configure an extended trigger, and a
1439 <link linkend="commandsstreaming">command</link>,
1441 <link linkend="trig-other">TRIG_OTHER</link> as one of the trigger
1446 Extended trigger configuration should be designed in such a way
1447 that the user can probe for valid parameters, similar to how
1448 command testing works. An extended trigger configuration instruction
1449 should not configure the hardware directly, rather, the configuration
1450 should be saved until the subsequent command is issued. This
1451 allows more flexibility for future interface changes.
1455 It has not been decided whether the configuration stage should return a
1456 token that is then used as the trigger argument in the command.
1457 Using tokens is one method to satisfy the problem that extended
1458 trigger configurations may have subtle compatiblity issues with
1459 other trigger sources/arguments that can only be determined at
1460 command test time. Passing all stages of a command test should
1461 only be allowed with a properly configured extended trigger.
1465 Extended triggers must use
1466 <link linkend="insn-data-structure-data">data[1]</link> as flags. The
1467 upper 16 bits are reserved and used only for flags that are common to
1468 all extended triggers. The lower 16 bits may be defined by the
1469 particular type of extended trigger.
1473 Various types of extended triggers must use
1474 <link linkend="insn-data-structure-data">data[1]</link> to know which
1475 event the extended trigger will be assigned to in the command
1476 structure. The possible values are an OR'd mask of the following:
1487 COMEDI_EV_SCAN_BEGIN
1509 <section id="analogtriggering">
1514 <emphasis role="strong">
1515 (Status: alpha. The <function>ni_mio_common.c</function> driver
1516 implements this feature.)
1521 The <link linkend="insn-data-structure-insn">insn</link> field of the
1522 <link linkend="insn-data-structure">instruction data structure</link>
1523 has not been assigned yet.
1526 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1527 of the <link linkend="insn-data-structure">instruction data
1528 structure</link> is ignored.
1532 The <link linkend="insn-data-structure-data">data</link> field
1533 of the <link linkend="insn-data-structure">instruction data
1534 structure</link> is used as follows:
1535 <variablelist spacing="compact">
1537 <term>data[1]</term>
1538 <listitem>trigger and combining machine configuration.</listitem>
1541 <term>data[2]</term>
1542 <listitem>analog triggering signal chanspec.</listitem>
1545 <term>data[3]</term>
1546 <listitem>primary analog level.</listitem>
1549 <term>data[4]</term>
1550 <listitem>secondary analog level.</listitem>
1555 Analog triggering is described by a digital combining machine that
1556 has two sensitive digital inputs. The sensitive digital inputs are
1557 generated by configurable analog comparators. The analog comparators
1558 generate a digital 1 when the analog triggering signal is greater
1559 than the comparator level. The digital inputs are not modifier
1560 inputs. Note, however, there is an effective modifier due to the
1561 restriction that the primary analog comparator level must be less
1562 than the secondary analog comparator level.
1566 If only one analog comparator signal is used, the combining machine
1567 for the secondary input should be set to ignored, and the secondary
1568 analog level should be set to 0.
1572 The interpretation of the chanspec and voltage levels is device
1573 dependent, but should correspond to similar values of the analog
1574 input subdevice, if possible.
1578 Notes: Reading range information is not addressed. This makes it
1579 difficult to convert comparator voltages to data values.
1583 Possible extensions: A parameter that specifies the necessary time
1584 that the set condition has to be true before the trigger is generated.
1585 A parameter that specifies the necessary time that the reset condition
1586 has to be true before the state machine is reset.
1591 <section id="bitfieldmatching">
1593 Bitfield Pattern Matching Extended Trigger
1596 <emphasis role="strong">
1597 (Status: design. No driver implements this feature yet.)
1602 The <link linkend="insn-data-structure-insn">insn</link> field of the
1603 <link linkend="insn-data-structure">instruction data structure</link>
1604 has not been assigned yet.
1607 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1608 of the <link linkend="insn-data-structure">instruction data
1609 structure</link> is ignored.
1613 The <link linkend="insn-data-structure-data">data</link> field
1614 of the <link linkend="insn-data-structure">instruction data
1615 structure</link> is used as follows:
1617 <variablelist spacing="compact">
1619 <term>data[1]</term>
1620 <listitem>trigger flags.</listitem>
1623 <term>data[2]</term>
1624 <listitem>mask.</listitem>
1627 <term>data[3]</term>
1628 <listitem>pattern.</listitem>
1633 The pattern matching trigger issues a trigger when all of a specifed
1634 set of input lines match a specified pattern. If the device allows,
1635 the input lines should correspond to the input lines of a digital input
1636 subdevice, however, this will necessarily be device dependent. Each
1637 possible digital line that can be matched is assigned a bit in the
1638 mask and pattern. A bit set in the mask indicates that the
1639 input line must match the corresponding bit in the pattern.
1640 A bit cleared in the mask indicates that the input line is ignored.
1644 Notes: This only allows 32 bits in the pattern/mask, which may be
1645 too few. Devices may support selecting different sets of lines from
1646 which to match a pattern.
1650 Discovery: The number of bits can be discovered by setting the mask
1651 to all 1's. The driver must modify this value and return -EAGAIN.
1656 <section id="countertimer">
1658 Counter configuration
1661 <emphasis role="strong">
1662 (Status: design. No driver implements this feature yet.)
1667 The <link linkend="insn-data-structure-insn">insn</link> field of the
1668 <link linkend="insn-data-structure">instruction data structure</link>
1669 has not been assigned yet.
1672 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1673 of the <link linkend="insn-data-structure">instruction data
1674 structure</link> is used to specify which counter to use. (I.e., the
1675 counter is a &comedi; channel.)
1679 The <link linkend="insn-data-structure-data">data</link> field
1680 of the <link linkend="insn-data-structure">instruction data
1681 structure</link> is used as follows:
1683 <variablelist spacing="compact">
1685 <term>data[1]</term>
1686 <listitem>trigger configuration.</listitem>
1689 <term>data[2]</term>
1690 <listitem>primary input chanspec.</listitem>
1693 <term>data[3]</term>
1694 <listitem>primary combining machine configuration.</listitem>
1697 <term>data[4]</term>
1698 <listitem>secondary input chanspec.</listitem>
1701 <term>data[5]</term>
1702 <listitem>secondary combining machine configuration.</listitem>
1705 <term>data[6]</term>
1706 <listitem>latch configuration.</listitem>
1711 Note that this configuration is only useful if the counting has to be
1712 done in <emphasis>software</emphasis>. Many cards offer configurable
1713 counters in hardware; e.g., general purpose timer cards can be
1714 configured to act as pulse generators, frequency counters, timers,
1718 Counters can be operated either in synchronous mode (using
1719 <link linkend="comediinsnstructure">INSN_READ</link>)
1720 or asynchronous mode (using
1721 <link linkend="commandsstreaming">commands</link>), similar to analog
1723 The input signal for both modes is the accumulator.
1724 Commands on counter subdevices are almost always specified using
1725 <link linkend="command-data-struct-scan-begin-src">scan_begin_src</link>
1726 = <link linkend="trigother-event">TRIG_OTHER</link>, with the
1727 counter configuration also serving as the extended configuration for
1728 the scan begin source.
1732 Counters are made up of an accumulator and a combining machine that
1733 determines when the accumulator should be incremented or decremented
1734 based on the values of the input signals. The combining machine
1735 optionally determines when the accumulator should be latched and
1736 put into a buffer. This feature is used in asynchronous mode.
1740 Note: How to access multiple pieces of data acquired at each event?
1745 <section id="auxcounter">
1747 One source plus auxiliary counter configuration
1750 <emphasis role="strong">
1751 (Status: design. No driver implements this feature yet.)
1756 The <link linkend="insn-data-structure-insn">insn</link> field of the
1757 <link linkend="insn-data-structure">instruction data structure</link>
1758 has not been assigned yet.
1761 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1762 of the <link linkend="insn-data-structure">instruction data
1763 structure</link> is used to …
1767 The <link linkend="insn-data-structure-data">data</link> field
1768 of the <link linkend="insn-data-structure">instruction data
1769 structure</link> is used as follows:
1773 <variablelist spacing="compact">
1775 <term>data[1]</term>
1777 is flags, including the flags for the command triggering
1778 configuration. If a command is not subsequently issued on the
1779 subdevice, the command triggering portion of the flags are ignored.
1783 <term>data[2]</term>
1785 determines the mode of operation. The mode of operation
1786 is actually a bitfield that encodes what to do for various
1787 transitions of the source signals.
1791 <term>data[3]</term>
1792 <term>data[4]</term>
1794 determine the primary source for the counter, similar to the
1795 <link linkend="command-data-struct-scan-begin-src">_src</link> and the
1796 <link linkend="command-data-struct-scan-begin-arg">_arg</link> fields
1798 <link linkend="command-data-struct">command data structure</link>.
1805 Notes: How to specify which events cause a latch and push, and what
1813 National instruments RTSI trigger bus
1816 A number of NI boards support the RTSI (Real Time System Integration) bus.
1817 It's primary use is to synchronize multiple DAQ cards.
1818 On PXI boards, the RTSI lines correspond to the PXI trigger lines 0 to 7. PCI
1819 boards use cables to connect to their RTSI ports.
1820 The RTSI bus consists of 8 digital signal lines numbered 0 to 7 that are bi-directional.
1821 Each of these signal lines
1822 can be configured as an input or output, and the signal appearing on the output
1823 of each line can be configured to one of several internal board timing signals
1824 (although on older boards RTSI line 7 can only be used for the clock signal).
1825 The ni_pcimio, ni_atmio, and ni_mio_cs drivers expose the RTSI bus
1826 as a digital I/O subdevice (subdevice number 10).
1829 The functions comedi_dio_config() and comedi_dio_get_config() can be used on
1830 the RTSI subdevice to
1831 set/query the direction (input or output) of each of the RTSI lines individually.
1834 The subdevice also supports the
1835 INSN_CONFIG_SET_CLOCK_SRC and INSN_CONFIG_GET_CLOCK_SRC configuration
1836 instructions, which can be
1837 used to configure/query what source the board uses to synchronize its
1838 master clock to. The various possibilities are defined in the comedi.h
1842 <tgroup cols='2' align='left'>
1845 <entry>Clock Source</entry>
1846 <entry>Description</entry>
1851 <entry>NI_MIO_INTERNAL_CLOCK</entry>
1853 Use the board's internal oscillator.
1857 <entry>NI_MIO_RTSI_CLOCK</entry>
1859 Use the RTSI line 7 as the master clock. This source is
1860 only supported on pre-m-series boards. The newer m-series boards
1861 use NI_MIO_PLL_RTSI_CLOCK() instead.
1865 <entry>NI_MIO_PLL_PXI_STAR_TRIGGER_CLOCK</entry>
1867 Only available for newer m-series PXI boards. Synchronizes the board's
1868 phased-locked loop (which runs at 80MHz) to the PXI star trigger
1873 <entry>NI_MIO_PLL_PXI10_CLOCK</entry>
1875 Only available for newer m-series PXI boards.
1876 Synchronizes the board's
1877 phased-locked loop (which runs at 80MHz) to the 10 MHz PXI backplane
1882 <entry><programlisting>unsigned NI_MIO_PLL_RTSI_CLOCK(unsigned n)</programlisting></entry>
1884 Only available for newer m-series boards.
1885 The function returns a clock source which will cause the board's
1886 phased-locked loop (which runs at 80MHz) to syncronize to the RTSI
1887 line specified in the function argument.
1895 For all clock sources except NI_MIO_INTERNAL_CLOCK and NI_MIO_PLL_PXI10_CLOCK,
1896 you should pass the period of the clock your are feeding to the board when
1897 using INSN_CONFIG_SET_CLOCK_SRC.
1900 Finally, the configuration instructions INSN_CONFIG_SET_ROUTING and
1901 INSN_CONFIG_GET_ROUTING can be used to select/query which internal signal
1902 will appear on a given RTSI output line. The header file comedi.h defines
1903 the following signal sources which can be routed to an RTSI line:
1907 <tgroup cols='2' align='left'>
1910 <entry>Signal Source</entry>
1911 <entry>Description</entry>
1916 <entry>NI_RTSI_OUTPUT_ADR_START1</entry>
1918 ADR_START1, an analog input start signal. See the NI's
1919 DAQ-STC Technical Reference Manual for more information.
1923 <entry>NI_RTSI_OUTPUT_ADR_START2</entry>
1925 ADR_START2, an analog input stop signal. See the NI's
1926 DAQ-STC Technical Reference Manual for more information.
1930 <entry>NI_RTSI_OUTPUT_SCLKG</entry>
1932 SCLKG, a sample clock signal. See the NI's
1933 DAQ-STC Technical Reference Manual for more information.
1937 <entry>NI_RTSI_OUTPUT_DACUPDN</entry>
1939 DACUPDN, a dac update signal. See the NI's
1940 DAQ-STC Technical Reference Manual for more information.
1944 <entry>NI_RTSI_OUTPUT_DA_START1</entry>
1946 DA_START1, an analog output start signal. See the NI's
1947 DAQ-STC Technical Reference Manual for more information.
1951 <entry>NI_RTSI_OUTPUT_G_SRC0</entry>
1953 G_SRC0, the source signal to general purpose counter 0. See the NI's
1954 DAQ-STC Technical Reference Manual for more information.
1958 <entry>NI_RTSI_OUTPUT_G_GATE0</entry>
1960 G_GATE0, the gate signal to general purpose counter 0. See the NI's
1961 DAQ-STC Technical Reference Manual for more information.
1965 <entry>NI_RTSI_OUTPUT_RGOUT0</entry>
1967 RGOUT0, the output signal of general purpose counter 0. See the NI's
1968 DAQ-STC Technical Reference Manual for more information.
1972 <entry><programlisting>unsigned NI_RTSI_OUTPUT_RTSI_BRD(unsigned n)</programlisting></entry>
1974 RTSI_BRD0 though RTSI_BRD3 are four internal signals which can
1975 have various other signals routed to them in turn. Currently, comedi
1976 provides no way to configure the signals routed to the RTSI_BRD lines.
1977 See the NI's DAQ-STC Technical Reference Manual for more information.
1981 <entry>NI_RTSI_OUTPUT_RTSI_OSC</entry>
1983 The RTSI clock signal. On pre-m-series boards, this signal is always
1984 routed to RTSI line 7, and cannot be routed to lines 0 through 6. On
1985 m-series boards, any RTSI line can be configured to output the clock
1994 The RTSI bus pins may be used as trigger inputs for many of the
1995 COMEDI trigger functions. To use the RTSI bus pins, set the source to be
1996 TRIG_EXT and the source argument using the return values from the
1997 NI_EXT_RTSI() function (or similarly the NI_EXT_PFI() function if you want
1998 to trigger from a PFI line). The CR_EDGE and CR_INVERT flags may
1999 also be set on the trigger source argument to specify edge and
2000 falling edge/low level triggering.
2004 An example to set up a device as a master is given below.
2007 <programlisting><![CDATA[
2008 void comediEnableMaster(comedi_t* dev){
2009 comedi_insn configCmd;
2010 lsampl_t configData[2];
2013 static const unsigned rtsi_subdev = 10;
2014 static const unsigned rtsi_clock_line = 7;
2016 /* Route RTSI clock to line 7 (not needed on pre-m-series boards since their
2017 clock is always on line 7). */
2018 memset(&configCmd, 0, sizeof(configCmd));
2019 memset(&configData, 0, sizeof(configData));
2020 configCmd.insn = INSN_CONFIG;
2021 configCmd.subdev = rtsi_subdev;
2022 configCmd.chanspec = rtsi_clock_line;
2024 configCmd.data = configData;
2025 configCmd.data[0] = INSN_CONFIG_SET_ROUTING;
2026 configCmd.data[1] = NI_RTSI_OUTPUT_RTSI_OSC;
2027 ret = comedi_do_insn(dev, &configCmd);
2029 comedi_perror("comedi_do_insn: INSN_CONFIG");
2032 // Set clock RTSI line as output
2033 ret = comedi_dio_config(dev, rtsi_subdev, rtsi_clock_line, INSN_CONFIG_DIO_OUTPUT);
2035 comedi_perror("comedi_dio_config");
2039 /* Set routing of the 3 main AI RTSI signals and their direction to output.
2040 We're reusing the already initialized configCmd instruction here since
2041 it's mostly the same. */
2042 configCmd.chanspec = 0;
2043 configCmd.data[1] = NI_RTSI_OUTPUT_ADR_START1;
2044 ret = comedi_do_insn(dev, &configCmd);
2046 comedi_perror("comedi_do_insn: INSN_CONFIG");
2049 ret = comedi_dio_config(dev, rtsi_subdev, 0, INSN_CONFIG_DIO_OUTPUT);
2051 comedi_perror("comedi_dio_config");
2055 configCmd.chanspec = 1;
2056 configCmd.data[1] = NI_RTSI_OUTPUT_ADR_START2;
2057 ret = comedi_do_insn(dev, &configCmd);
2059 comedi_perror("comedi_do_insn: INSN_CONFIG");
2062 ret = comedi_dio_config(dev, rtsi_subdev, 1, INSN_CONFIG_DIO_OUTPUT);
2064 comedi_perror("comedi_dio_config");
2068 configCmd.chanspec = 2;
2069 configCmd.data[1] = NI_RTSI_OUTPUT_SCLKG;
2070 ret = comedi_do_insn(dev, &configCmd);
2072 comedi_perror("comedi_do_insn: INSN_CONFIG");
2075 ret = comedi_dio_config(dev, rtsi_subdev, 2, INSN_CONFIG_DIO_OUTPUT);
2077 comedi_perror("comedi_dio_config");
2081 ]]></programlisting>
2084 An example to slave a m-series device from this master follows. A pre-m-series
2085 device would need to use NI_MIO_RTSI_CLOCK for the clock source instead. In
2086 your code, you may also wish to configure the master device to use the
2087 external clock source instead of using its internal clock directly (for
2088 best syncronization).
2090 <programlisting><![CDATA[
2091 void comediEnableSlave(comedi_t* dev){
2092 comedi_insn configCmd;
2093 lsampl_t configData[3];
2095 unsigned int d = 0;;
2096 static const unsigned rtsi_subdev = 10;
2097 static const unsigned rtsi_clock_line = 7;
2099 memset(&configCmd, 0, sizeof(configCmd));
2100 memset(&configData, 0, sizeof(configData));
2101 configCmd.insn = INSN_CONFIG;
2102 configCmd.subdev = rtsi_subdev;
2103 configCmd.chanspec = 0;
2105 configCmd.data = configData;
2106 configCmd.data[0] = INSN_CONFIG_SET_CLOCK_SRC;
2107 configCmd.data[1] = NI_MIO_PLL_RTSI_CLOCK(rtsi_clock_line);
2108 configCmd.data[2] = 100; /* need to give it correct external clock period */
2109 ret = comedi_do_insn(dev, &configCmd);
2111 comedi_perror("comedi_do_insn: INSN_CONFIG");
2114 /* configure RTSI clock line as input */
2115 ret = comedi_dio_config(dev, rtsi_subdev, rtsi_clock_line, INSN_CONFIG_DIO_INPUT);
2117 comedi_perror("comedi_dio_config");
2120 /* Configure RTSI lines we are using for AI signals as inputs. */
2121 ret = comedi_dio_config(dev, rtsi_subdev, 0, INSN_CONFIG_DIO_INPUT);
2123 comedi_perror("comedi_dio_config");
2126 ret = comedi_dio_config(dev, rtsi_subdev, 1, INSN_CONFIG_DIO_INPUT);
2128 comedi_perror("comedi_dio_config");
2131 ret = comedi_dio_config(dev, rtsi_subdev, 2, INSN_CONFIG_DIO_INPUT);
2133 comedi_perror("comedi_dio_config");
2138 int comediSlaveStart(comedi_t* dev){
2140 unsigned int nChannels = 8;
2141 double sampleRate = 50000;
2142 unsigned int chanList[8];
2146 for(i = 0; i < nChannels; i++){
2147 chanList[i] = CR_PACK(i, 0, AREF_GROUND);
2150 memset(&cmd, 0, sizeof(cmd));
2151 ret = comedi_get_cmd_generic_timed(dev, subdevice, &cmd, int(1e9/(nChannels * sampleRate)));
2153 printf("comedi_get_cmd_generic_timed failed\n");
2156 cmd.chanlist = chanList;
2157 cmd.chanlist_len = nChannels;
2158 cmd.scan_end_arg = nChannels;
2159 cmd.start_src = TRIG_EXT;
2160 cmd.start_arg = CR_EDGE | NI_EXT_RTSI(0);
2161 cmd.convert_src = TRIG_EXT;
2162 cmd.convert_arg = CR_INVERT | CR_EDGE | NI_EXT_RTSI(2);
2163 cmd.stop_src = TRIG_NONE;
2165 ret = comedi_command(dev0, &cmd0);
2167 printf("comedi_command failed\n");
2172 ]]></programlisting>