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>(<link linkend="ref-type-comedi-t">comedi_t</link> *device, unsigned int subdevice, unsigned int channel,
63 int <link linkend="func-ref-comedi-dio-write">comedi_dio_write</link>(<link linkend="ref-type-comedi-t">comedi_t</link> *device, unsigned int subdevice, unsigned int channel,
66 The <parameter class="function">device</parameter> parameter is a
67 <link linkend="ref-type-comedi-t">pointer</link>
68 to a successfully opened &comedi; device.
69 The <parameter class="function">subdevice</parameter> and
70 <parameter class="function">channel</parameter> parameters are positive
71 integers that indicate which subdevice and channel is used in the
72 acquisition. The integer <parameter class="function">bit</parameter>
73 contains the value of the acquired bit.
76 The direction of bidirectional lines can be configured using
79 int <link linkend="func-ref-comedi-dio-config">comedi_dio_config</link>(<link linkend="ref-type-comedi-t">comedi_t</link> *device, unsigned int subdevice, unsigned int channel,
82 The parameter <parameter class="function">dir</parameter> should be
83 either <literal>COMEDI_INPUT</literal> or
84 <literal>COMEDI_OUTPUT</literal>.
85 Many digital I/O subdevices group channels into blocks for
86 configuring direction. Changing one channel in a block changes
91 Multiple channels can be read and written simultaneously using the
94 int <link linkend="func-ref-comedi-dio-bitfield">comedi_dio_bitfield</link>(<link linkend="ref-type-comedi-t">comedi_t</link> *device, unsigned int subdevice,
95 unsigned int write_mask, unsigned int *bits);
97 Each channel is assigned to a bit in the
98 <parameter class="function">write_mask</parameter> and
99 <parameter class="function">bits</parameter>
100 bitfield. If a bit in
101 <parameter class="function">write_mask</parameter> is set, the
102 corresponding bit in <parameter class="function">*bits</parameter> will
103 be written to the corresponding digital output line.
104 Each digital line is then read and placed into
105 <parameter class="function">*bits</parameter>. The value
106 of bits in <parameter class="function">*bits</parameter> corresponding
107 to digital output lines is undefined and device-specific. Channel
108 <literal>0</literal> is the least significant bit in the bitfield;
109 channel <literal>31</literal> is the most significant bit. Channels
110 higher than <literal>31</literal> cannot be accessed using this method.
114 The digital acquisition functions seem to be very simple, but, behind
115 the implementation screens of the &comedi; kernel module, they are
116 executed as special cases of the general
117 <link linkend="instructions">instruction</link> command.
124 <section id="singleanalog">
126 Single analog acquisition
129 Analog &comedi; channels can produce data values that are
130 <emphasis>samples</emphasis> from continuous analog signals.
131 These samples are integers with a significant content in
132 the range of, typically, <literal>8</literal>, <literal>10</literal>,
133 <literal>12</literal>, or <literal>16</literal> bits.
138 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,
139 unsigned int range, unsigned int aref, <link linkend="ref-type-lsampl-t">lsampl_t</link> * data);
141 function reads one such data value from a &comedi; channel, and puts it in
142 the user-specified <parameter>data</parameter> buffer. The
144 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,
145 unsigned int range, unsigned int aref, <link linkend="ref-type-lsampl-t">lsampl_t</link> data);
147 works in the opposite direction. Data values returned by this function
148 are unsigned integers less than, or equal to, the maximum sample value
149 of the channel, which can be determined using the function
151 <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,
152 unsigned int channel);
154 Conversion of data values to physical units can be performed by the
157 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);
159 There are two data structures in these commands that are not fully
165 <link linkend="ref-type-comedi-t">comedi_t</link>: this data structure
166 contains all information that a user program has to know about an
167 <emphasis>open</emphasis> &comedi; device. The programmer doesn't have
168 to fill in this data structure manually: it gets filled in by opening
175 <link linkend="ref-type-lsampl-t">lsampl_t</link>: this
176 <quote>data structure</quote> represents one single sample. On most
177 architectures, it's nothing more than a 32 bits value. Internally,
178 &comedi; does some conversion from raw sample data to
179 <quote>correct</quote> integers. This is called <quote>data
187 Each single acquisition by, for example,
189 <link linkend="func-ref-comedi-data-read">comedi_data_read()</link>
191 requires quite some overhead, because all the arguments of the
192 function call are checked. If multiple acquisitions must be done on
193 the same channel, this overhead can be avoided by using a function
194 that can read more than one sample:
196 int <link linkend="func-ref-comedi-data-read-n">comedi_data_read_n</link>(<link linkend="ref-type-comedi-t">comedi_t</link> *it, unsigned int subdev, unsigned int chan,
197 unsigned int range, unsigned int aref, <link linkend="ref-type-lsampl-t">lsampl_t</link> *data, unsigned int n);
199 The number of samples, <parameter class="function">n</parameter>, is
200 limited by the &comedi; implementation (to a maximum of 100 samples),
201 because the call is blocking.
204 The start of the data acquisition can also be delayed by a specified
205 number of nano-seconds:
207 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,
208 unsigned int range, unsigned int aref, <link linkend="ref-type-lsampl-t">lsampl_t</link> *data,
209 unsigned int nano_sec);
211 All these read and write acquisition functions are implemented on top
212 of the generic <link linkend="instructions">instruction</link>
221 <section id="instructions">
223 Instructions for multiple acquisitions
226 The <emphasis>instruction</emphasis> is one of the most generic,
227 overloaden and flexible functions in the &comedi; API. It is used to
228 execute a multiple of identical acquisitions on the same channel, but
230 <link linkend="instructionsconfiguration">configuration</link> of a
232 <anchor id="anchor.instruction.list"/>
233 An <emphasis>instruction list</emphasis> is a list of instructions,
234 possibly on different channels. Both instructions and instructions
235 lists are executed <emphasis>synchronously</emphasis>, i.e., while
236 <emphasis role="strong">blocking</emphasis> the calling process.
237 This is one of the limitations of instructions; the other one is that
238 they cannot code an acquisition involving timers or external events.
239 These limits are eliminated by the
240 <link linkend="commandsstreaming">command</link> acquisition
245 <section id="comediinsnstructure">
247 The instruction data structure
250 All the information needed to execute an instruction is stored in the
251 <link linkend="ref-type-comedi-insn">comedi_insn</link>
254 struct <anchor id="insn-data-structure"/>comedi_insn_struct {
255 <anchor id="insn-data-structure-insn"/>unsigned int insn; // integer encoding the type of acquisition
256 // (or configuration)
257 unsigned int n; // number of elements in data array
258 <link linkend="ref-type-lsampl-t">lsampl_t</link> <anchor id="insn-data-structure-data"/>*data; // pointer to data buffer
259 unsigned int subdev; // subdevice
260 unsigned int <anchor id="insn-data-structure-chanspec"/><link linkend="ref-macro-CR-PACK">chanspec</link>; // encoded channel specification
261 unsigned int unused[3];
264 Because of the large flexibility of the instruction function, many
265 types of instruction do not need to fill in all fields, or attach
266 different meanings to the same field. But the current implementation
267 of &comedi; requires the
268 <link linkend="insn-data-structure-data">data</link> field to be at
273 The <link linkend="insn-data-structure-insn">insn</link> flag of the
274 <link linkend="insn-data-structure">instruction data structure</link>
275 determines the type of acquisition executed in the corresponding
281 INSN_READ: the instruction executes a read on an analog channel.
287 INSN_WRITE: the instruction executes a write on an analog channel.
293 INSN_BITS: indicates that the instruction must
294 read or write values on multiple digital I/O channels.
300 INSN_GTOD: the instruction performs a <quote>Get Time Of Day</quote>
307 INSN_WAIT: the instruction blocks for a specified number of
318 <section id="instructionexecution">
320 Instruction execution
323 Once an instruction data structure has been filled in, the
324 corresponding instruction is executed as follows:
326 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);
328 Many &comedi; instructions are shortcuts that relieve the programmer
329 from explicitly filling in the data structure and calling the
330 <link linkend="func-ref-comedi-do-insn">comedi_do_insn</link>
336 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)
338 instruction allows to perform a list of instructions in one function
339 call. The number of instructions in the list is limited in the
340 implementation, because instructions are executed
341 <emphasis>synchronously</emphasis>, i.e., the call blocks until the
342 whole instruction (list) has finished.
350 <section id="instructionsconfiguration">
352 Instructions for configuration
355 <xref linkend="instructions"/> explains how instructions are used to do
356 <emphasis>acquisition</emphasis> on channels. This section explains
357 how they are used to <emphasis>configure</emphasis> a subdevice.
358 There are various sorts of configurations, and the
359 specific information for each different configuration possibility is
360 to be specified via the
361 <link linkend="insn-data-structure-data">data</link> buffer of the
362 <link linkend="insn-data-structure">instruction data structure</link>.
363 (So, the pointer to a
364 <link linkend="ref-type-lsampl-t">lsampl_t</link>
365 is misused as a pointer to an array with board-specific information.)
369 Using INSN_CONFIG as the
370 <link linkend="insn-data-structure-insn">insn</link> flag in an
371 <link linkend="insn-data-structure">instruction data structure</link>
372 indicates that the instruction will
373 <emphasis>not perform acquisition</emphasis> on a
374 channel, but will <emphasis>configure</emphasis> that channel.
376 <link linkend="ref-macro-CR-PACK">chanspec</link> field in the
377 <link linkend="insn-data-structure-chanspec">comedi_insn</link>
378 data structure, contains the channel to be configured.
379 The zeroth element of the data array
380 is always an id that specifies
381 what type of configuration instruction is being performed. The
382 meaning of rest of the elements in the data array
383 depend on the configuration instruction id.
385 possible ids are summarised in the table below, along with the
386 meanings of the data array elements for
387 each type of configuration instruction.
391 <tgroup cols='4' align='left'>
392 <colspec colwidth='4*' />
393 <colspec colwidth='4*' />
394 <colspec colwidth='1*' />
395 <colspec colwidth='4*' />
398 <entry>data[0]</entry>
399 <entry>Description</entry>
400 <entry>n (number of elements in data array)</entry>
401 <entry>Meanings of data[1], ..., data[n-1]</entry>
406 <entry>INSN_CONFIG_DIO_INPUT</entry>
408 Configure a dio line as input. It is easier to use comedi_dio_config() than
409 to use this configuration instruction directly.
417 <entry>INSN_CONFIG_DIO_OUTPUT</entry>
419 Configure a dio line as output. It is easier to use comedi_dio_config() than
420 to use this configuration instruction directly.
428 <entry>INSN_CONFIG_ALT_SOURCE</entry>
430 Select an alternate input source. This instruction is
431 used by comedi_calibrate to configure analog input channels
432 which can be redirected to read internal calibration
433 references. You need to set the CR_ALT_SOURCE flag in the chanspec
434 when reading to actually read from the configured alternate input source.
435 If you are using comedi_data_read(), then the channel parameter can be
436 bitwise or'd with the CR_ALT_SOURCE flag.
440 data[1]: alternate input source.
444 <entry>INSN_CONFIG_BLOCK_SIZE</entry>
446 Specify block size for asynchonous command data.
447 When performing streaming input, many boards accumulate
448 samples in internal fifos and transfer them to the host
449 computer in chunks. Some drivers let you suggest a size in bytes for how big a
450 the chunks should be. This lets you tune how often the host computer is
451 interrupted with a new chunk of data.
455 data[1]: The desired block size in bytes. The actual configured block size is
456 writen back to data[1] after the instruction completes. This instruction
457 acts purely as a query if the block size is set to zero.
461 <entry>INSN_CONFIG_DIO_QUERY</entry>
463 Queries the configuration of a dio line to see if it is an input or output.
464 It is probably easier to use the comedilib function comedi_dio_get_config()
465 than to use this instruction directly.
469 data[1]: The instruction sets this element to either COMEDI_INPUT or COMEDI_OUTPUT.
477 See the comedilib demo program demo/choose_clock.c for an example
478 of using a configuration instruction.
484 <section id="inttrigconfiguration">
486 Instruction for internal triggering
489 This special instruction has
490 <anchor id="insn-inttrig"/>INSN_INTTRIG as the
491 <link linkend="insn-data-structure-insn">insn</link> flag in its
492 <link linkend="insn-data-structure">instruction data structure</link>.
493 Its execution causes an
494 <link linkend="trig-int-start-src">internal triggering event</link>. This
495 event can, for example, cause the device driver to start a conversion,
496 or to stop an ongoing acquisition. The exact meaning of the triggering
497 depends on the card and its particular driver.
501 <link linkend="insn-data-structure-data">data</link>[0] field of the
502 INSN_INTTRIG instruction is reserved for future use, and should be set
509 <section id="commandsstreaming">
511 Commands for streaming acquisition
515 The most powerful &comedi; acquisition primitive is the
516 <emphasis>command</emphasis>. It's powerful because, with one single
517 command, the programmer launches:
522 a possibly infinite <emphasis>sequence of acquisitions</emphasis>,
528 accompanied with various <emphasis>callback</emphasis> functionalities
529 (DMA, interrupts, driver-specific callback functions),
535 for <emphasis>any number of channels</emphasis>,
541 with an <emphasis>arbitrary order</emphasis> of channels in each scan
542 (possibly even with repeated channels per scan),
548 and with various scan <emphasis>triggering sources</emphasis>,
549 external (i.e., hardware pulses) as well as internal (i.e., pulses
550 generated on the DAQ card itself, or generated by a
551 <link linkend="inttrigconfiguration">software trigger instruction</link>).
556 This command functionality exists in the &comedi; API, because various
557 data acquisition devices have the capability to perform this kind of
558 complex acquisition, driven by either on-board or
559 off-board timers and triggers.
563 A command specifies a particular data
564 <link linkend="fig-acq-seq">acquisition sequence</link>, which
565 consists of a number of <emphasis>scans</emphasis>, and each scan is
566 comprised of a number of <emphasis>conversions</emphasis>, which
567 usually corresponds to a single A/D or D/A conversion. So, for
568 example, a scan could consist of sampling channels 1, 2 and 3 of a
569 particular device, and this scan should be repeated 1000 times, at
570 intervals of 1 millisecond apart.
573 The command function is complementary to the
574 <link linkend="instructionsconfiguration">configuration instruction</link>
575 function: each channel in the command's
576 <link linkend="command-data-struct-chanlist">chanlist</link>
577 should first be configured by an appropriate instruction.
581 <section id="executingcommand">
587 A commands is executed by the following &comedi; function:
589 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);
591 The following sections explain the meaning of the
592 <link linkend="ref-type-comedi-cmd">comedi_cmd</link> data structure.
593 Filling in this structure can be quite complicated, and
594 requires good knowledge about the exact functionalities of the DAQ
595 card. So, before launching a command, the application programmer is
596 adviced to check whether this complex command data structure can be
597 successfully parsed. So, the typical sequence for executing a command is
598 to first send the command through
599 <link linkend="func-ref-comedi-command-test">comedi_command_test()</link>
600 once or twice. The test will check that the command is valid for the
601 particular device, and often makes some adjustments to the command
602 arguments, which can then be read back by the user to see the actual
606 A &comedi; program can find out on-line what the command capabilities
607 of a specific device are, by means of the
608 <link linkend="func-ref-comedi-get-cmd-src-mask">comedi_get_cmd_src_mask()</link>
615 <section id="comedicmdstructure">
617 The command data structure
620 The command executes according to the information about the requested
621 acquisition, which is stored in the
622 <link linkend="ref-type-comedi-cmd">comedi_cmd</link>
623 <anchor id="command-data-struct"/>data structure:
625 typedef struct comedi_cmd_struct comedi_cmd;
627 struct comedi_cmd_struct {
628 unsigned int subdev; // which subdevice to sample
629 unsigned int <anchor id="command-data-struct-flags"/>flags; // encode some configuration possibilities
630 // of the command execution; e.g.,
631 // whether a callback routine is to be
632 // called at the end of the command
634 unsigned int <anchor id="command-data-struct-start-src"/>start_src; // event to make the acquisition start
635 unsigned int <anchor id="command-data-struct-start-arg"/>start_arg; // parameters that influence this start
637 unsigned int <anchor id="command-data-struct-scan-begin-src"/>scan_begin_src; // event to make a particular scan start
638 unsigned int <anchor id="command-data-struct-scan-begin-arg"/>scan_begin_arg; // parameters that influence this start`
640 unsigned int <anchor id="command-data-struct-convert-src"/>convert_src; // event to make a particular conversion start
641 unsigned int <anchor id="command-data-struct-convert-arg"/>convert_arg; // parameters that influence this start
643 unsigned int <anchor id="command-data-struct-scan-end-src"/>scan_end_src; // event to make a particular scan terminate
644 unsigned int <anchor id="command-data-struct-scan-end-arg"/>scan_end_arg; // parameters that influence this termination
646 unsigned int <anchor id="command-data-struct-stop-src"/>stop_src; // what make the acquisition terminate
647 unsigned int <anchor id="command-data-struct-stop-arg"/>stop_arg; // parameters that influence this termination
649 unsigned int <anchor id="command-data-struct-chanlist"/>*chanlist; // pointer to list of channels to be sampled
650 unsigned int <anchor id="command-data-struct-chanlist-len"/>chanlist_len; // number of channels to be sampled
652 sampl_t *<anchor id="command-data-struct-data"/>data; // address of buffer
653 unsigned int <anchor id="command-data-struct-data-len"/>data_len; // number of samples to acquire
656 The start and end of the whole command acquisition sequence, and the
657 start and end of each scan and of each conversion, is triggered by a
658 so-called <emphasis>event</emphasis>. More on these in
659 <xref linkend="comedicmdsources"/>.
663 The <parameter class="function">subdev</parameter> member of the
664 <link linkend="ref-type-comedi-cmd">comedi_cmd</link> structure is
665 the index of the subdevice the command is intended for. The
666 <link linkend="func-ref-comedi-find-subdevice-by-type">comedi_find_subdevice_by_type()</link>
667 function can be useful in discovering the index of your desired subdevice.
671 The <link linkend="command-data-struct-chanlist">chanlist</link>
673 <link linkend="ref-type-comedi-cmd">comedi_cmd</link> data
674 structure should point to an array whose number of elements is
676 <link linkend="command-data-struct-chanlist-len">chanlist_len</link>
677 (this will generally be the same as the
678 <link linkend="command-data-struct-scan-end-arg">scan_end_arg</link>).
680 <link linkend="command-data-struct-chanlist">chanlist</link>
681 specifies the sequence of channels and gains (and analog references)
682 that should be stepped through for each scan. The elements of the
683 <link linkend="command-data-struct-chanlist">chanlist</link> array should be
684 initialized by <quote>packing</quote> the channel, range and reference
685 information together with the
686 <parameter class="function">
687 <link linkend="ref-macro-CR-PACK">CR_PACK()</link>
693 The <link linkend="command-data-struct-data">data</link> and
694 <link linkend="command-data-struct-data-len">data_len</link>
695 members can be safely ignored when issueing commands from a user-space
696 program. They only have meaning when a command is sent from a
697 <emphasis role="strong">kernel</emphasis> module using the
698 <function>kcomedilib</function> interface, in which case they specify
699 the buffer where the driver should write/read its data to/from.
703 The final member of the
704 <link linkend="command-data-struct">comedi_cmd</link> structure is the
705 <link linkend="command-data-struct-flags">flags</link> field,
706 i.e., bits in a word that can be bitwise-or'd together. The meaning of
707 these bits are explained in a
708 <link linkend="source.flags.anchor">later section</link>.
714 <section id="comedicmdsources">
716 The command trigger events
717 <anchor id="source.trigger.anchor"/>
720 A command is a very versatile acquisition instruction, in the sense
721 that it offers lots of possibilities to let different hardware and
722 software sources determine when acquisitions are started, performed,
723 and stopped. More specifically, the command
724 <link linkend="command-data-struct">data structure</link>
725 has <emphasis>five</emphasis> types of events: start the
726 <link linkend="acquisitionterminology">acquisition</link>,
727 start a <link linkend="scan">scan</link>, start a
728 <link linkend="conversion">conversion</link>, stop a scan, and stop
729 the acquisition. Each event can be given its own
730 <emphasis><link linkend="source.trigger.anchor">source</link></emphasis>
731 (the <parameter class="function">*_src</parameter> members in the
732 <link linkend="ref-type-comedi-cmd">comedi_cmd</link> data
733 structure). And each event source can have a corresponding
734 argument (the <parameter class="function">*_arg</parameter> members of
735 the <link linkend="ref-type-comedi-cmd">comedi_cmd</link> data
736 structure) whose meaning depends on the type of source trigger.
737 For example, to specify an external digital line <quote>3</quote> as a
738 source (in general, <emphasis>any</emphasis> of the five event
739 sources), you would use
740 <parameter>src</parameter>=<link linkend="trig-ext">TRIG_EXT</link> and
741 <parameter>arg</parameter>=3.
744 The following paragraphs discuss in somewhat more detail the trigger
745 event sources(<parameter class="function">*_src</parameter>), and the
746 corresponding arguments (<parameter class="function">*_arg</parameter>).
749 The start of an acquisition is controlled by the
750 <link linkend="command-data-struct-start-src">start_src</link> events.
751 The available options are:
756 <anchor id="trig-now-start-src"/>
758 <link linkend="command-data-struct-start-src">start_src</link>
760 <link linkend="command-data-struct-start-arg">start_arg</link>
761 nanoseconds after the
762 <link linkend="ref-type-comedi-cmd">comedi_cmd</link>
763 is called. Currently, only
764 <link linkend="command-data-struct-start-arg">start_arg</link>=0 is
771 <anchor id="trig-follow-start-src"/>
772 TRIG_FOLLOW: (For an output device.) The
773 <link linkend="command-data-struct-start-src">start_src</link>
774 event occurs when data is written to the buffer.
780 <anchor id="trig-ext-start-src"/>
781 TRIG_EXT: the start event occurs when an external trigger signal
782 occurs; e.g., a rising edge of a digital line.
783 <link linkend="command-data-struct-start-arg">start_arg</link>
784 chooses the particular digital line.
790 <anchor id="trig-int-start-src"/>
791 TRIG_INT: the start event occurs on a &comedi; internal signal, which
792 is typically caused by an
793 <link linkend="insn-inttrig">INSN_INTTRIG instruction</link>.
798 The start of the beginning of each
799 <link linkend="scan">scan</link> is controlled by the
800 <link linkend="command-data-struct-scan-begin-src">scan_begin</link> events.
801 The available options are:
806 <anchor id="trig-timer-start-scan"/>
808 <link linkend="command-data-struct-scan-begin-src">scan_begin</link>
809 events occur periodically. The time between
810 <link linkend="command-data-struct-scan-begin-src">scan_begin</link>
812 <link linkend="command-data-struct-convert-arg">convert_arg</link>
819 <anchor id="trig-follow-start-scan"/>
821 <link linkend="command-data-struct-scan-begin-src">scan_begin</link>
822 event occurs immediately after a
823 <link linkend="command-data-struct-scan-end-src">scan_end</link>
830 <anchor id="trig-ext-start-scan"/>
832 <link linkend="command-data-struct-scan-begin-src">scan_begin</link>
833 event occurs when an external trigger signal
834 occurs; e.g., a rising edge of a digital line.
835 <link linkend="command-data-struct-scan-begin-arg">scan_begin_arg</link>
836 chooses the particular digital line.
842 <link linkend="command-data-struct-scan-begin-arg">scan_begin_arg</link>
843 used here may not be supported exactly by the device, but it
844 will be adjusted to the nearest supported value by
845 <link linkend="func-ref-comedi-command-test">comedi_command_test()</link>.
848 The timing between each sample in a
849 <link linkend="scan">scan</link> is controlled by the
850 <link linkend="command-data-struct-convert-src">convert_*</link>
856 <anchor id="convert-trig-timer"/>
857 <anchor id="trig-timer"/>
858 TRIG_TIMER: the conversion events occur periodically. The time
859 between convert events is
860 <link linkend="command-data-struct-convert-arg">convert_arg</link>
867 <anchor id="convert-trig-ext"/>
868 <anchor id="trig-ext"/>
869 TRIG_EXT: the conversion events occur when an external trigger signal
870 occurs, e.g., a rising edge of a digital line.
871 <link linkend="command-data-struct-convert-arg">convert_arg</link>
872 chooses the particular digital line.
878 <anchor id="convert-trig-now"/>
879 <anchor id="trig-now"/>
880 TRIG_NOW: All conversion events in a
881 <link linkend="scan">scan</link> occur simultaneously.
886 The <emphasis>end</emphasis> of each scan is almost always specified
888 <link linkend="trig-count">TRIG_COUNT</link>, with the argument being
889 the same as the number of channels in the
890 <link linkend="command-data-struct-chanlist">chanlist</link>. You
891 could probably find a device that allows something else, but it would
896 <link linkend="acquisitionterminology">acquisition</link> is
898 <link linkend="command-data-struct-stop-src">stop_src</link>
899 and <link linkend="command-data-struct-stop-arg">stop_arg</link>:
904 <anchor id="acquisition-end-trig-count"/>
905 <anchor id="trig-count"/>
906 TRIG_COUNT: stop the acquisition after
907 <link linkend="command-data-struct-stop-arg">stop_arg</link>
914 <anchor id="acquisition-end-trig-none"/>
915 <anchor id="trig-none"/>
916 TRIG_NONE: perform continuous acquisition, until stopped using
917 <link linkend="func-ref-comedi-cancel">comedi_cancel()</link>.
920 Its argument is reserved and should be set to 0.
921 (<quote>Reserved</quote>
922 means that unspecified things could happen if it is set to something
928 There are a couple of less usual or not yet implemented events:
933 <anchor id="trig-time"/>
935 cause an event to occur at a particular time.
938 (This event source is reserved for future use.)
944 <anchor id="trigother-event"/>
945 TRIG_OTHER: driver specific event trigger.
948 This event can be useful as any of the trigger sources. Its exact
949 meaning is driver specific, because it implements a feature that
950 otherwise does not fit into the generic &comedi; command interface.
951 Configuration of TRIG_OTHER features are done by
952 <link linkend="instructionsconfiguration">INSN_CONFIG</link>
956 The argument is reserved and should be set to 0.
961 Not all event sources are applicable to all events. Supported
962 trigger sources for specific events depend significantly on your
963 particular device, and even more on the current state of its device
965 <link linkend="func-ref-comedi-get-cmd-src-mask">comedi_get_cmd_src_mask()</link>
966 function is useful for determining what trigger sources a subdevice
973 <section id="comedicmdflags">
976 <anchor id="source.flags.anchor"/>
981 <link linkend="command-data-struct-flags">flags</link> field in the
982 <link linkend="ref-type-comedi-cmd">command data structure</link>
983 is used to specify some <quote>behaviour</quote> of the acquisitions in
985 The meaning of the field is as follows:
990 <anchor id="trig-rt"/>
991 TRIG_RT: ask the driver to use a
992 <emphasis role="strong">hard real-time</emphasis> interrupt handler.
993 This will reduce latency in handling interrupts from your data
995 hardware. It can be useful if you are sampling at high frequency, or
996 if your hardware has a small onboard data buffer. You must have a
997 real-time kernel (<ulink url="http://www.rtai.org">RTAI</ulink> or
998 <ulink url="http://www.rtlinux-gpl.org/">RTLinux/GPL</ulink>)
999 and must compile &comedi; with real-time support, or this flag will do
1006 <anchor id="trig-wake-eos"/>
1008 where <quote>EOS</quote> stands for <quote>End of Scan</quote>. Some
1009 drivers will change their behaviour when this flag is set, trying to
1010 transfer data at the end of every scan (instead of, for example,
1011 passing data in chunks whenever the board's hardware data buffer is
1012 half full). This flag may degrade a driver's performance at high
1013 frequencies, because the end of a scan is, in general, a much more
1014 frequent event than the filling up of the data buffer.
1020 <anchor id="trig-round-nearest"/>
1022 round to nearest supported timing period, the default.
1023 This flag (as well as the following three), indicates how timing
1024 arguments should be rounded if the hardware cannot achieve the exact
1031 <anchor id="trig-round-down"/>
1032 TRIG_ROUND_DOWN: round period down.
1038 <anchor id="trig-round-up"/>
1039 TRIG_ROUND_UP: round period up.
1045 <anchor id="trig-round-up-next"/>
1047 this one doesn't do anything, and I don't know what it was intended
1054 <anchor id="trig-dither"/>
1055 TRIG_DITHER: enable dithering? Dithering is a software technique to
1056 smooth the influence of discretization <quote>noise</quote>.
1062 <anchor id="trig-deglitch"/>
1063 TRIG_DEGLITCH: enable deglitching? Another <quote>noise</quote>
1064 smoothing technique.
1070 <anchor id="trig-write"/>
1072 write to bidirectional devices. Could be useful, in principle, if
1073 someone wrote a driver that supported commands for a digital I/O
1074 device that could do either input or output.
1080 <anchor id="trig-bogus"/>
1081 TRIG_BOGUS: do the motions?
1087 <anchor id="trig-other"/>
1088 TRIG_CONFIG: perform configuration, not triggering. This is a legacy
1090 <link linkend="ref-type-comedi-cmd">comedi_trig_struct</link>
1091 data structure, and has no function at present.
1105 If you wish to aquire accurate waveforms, it is vital that you use an
1106 anti-alias filter. An anti-alias filter is a low-pass filter used to
1107 remove all frequencies higher than the Nyquist frequency (half your sampling rate)
1108 from your analog input signal
1109 before you convert it to digital. If you fail to filter your input signal,
1110 any high frequency components in the original analog signal will create
1111 artifacts in your recorded digital waveform that cannot be corrected.
1114 For example, suppose you are sampling an analog input channel at a rate of
1115 1000 Hz. If you were to apply a 900 Hz sine wave to the input, you
1116 would find that your
1117 sampling rate is not high enough to faithfully record the 900 Hz input,
1118 since it is above your Nyquist frequency of 500 Hz. Instead, what you
1119 will see in your recorded digital waveform is a 100 Hz sine wave! If you
1120 don't use an anti-alias filter, it is impossible to tell whether the 100
1121 Hz sine wave you see in your digital signal was really produced by a
1122 100 Hz input signal, or a 900 Hz signal aliased to 100 Hz, or a 1100 Hz
1126 In practice, the cutoff frequency for the anti-alias filter is usually
1127 set 10% to 20% below the Nyquist frequency due to fact that real filters
1128 do not have infinitely sharp cutoffs.
1134 <section id="slowlyvarying">
1136 Slowly-varying inputs
1140 Sometimes, your input channels change slowly enough that
1141 you are able to average many successive input values to get a
1142 more accurate measurement of the actual value. In general,
1143 the more samples you average, the better your estimate
1144 gets, roughly by a factor of sqrt(number_of_samples).
1145 Obviously, there are limitations to this:
1152 you are ultimately limited by <quote>Spurious Free Dynamic
1153 Range</quote>. This SFDR is one of the popular measures to quantify how
1154 much noise a signal carries. If you take a Fourier transform of your
1155 signal, you will see several <quote>peaks</quote> in the transform: one
1156 or more of the fundamental harmonics of the measured signal, and lots
1157 of little <quote>peaks</quote> (called <quote>spurs</quote>) caused by
1158 noise. The SFDR is then the difference between the amplitude of the
1159 fundamental harmonic and of the largest spur (at frequencies below
1160 half of the Nyquist frequency of the DAQ sampler!).
1166 you need to have <emphasis>some</emphasis> noise on the input channel,
1167 otherwise you will be averaging the same number <literal>N</literal>
1168 times. (Of course, this only holds if the noise is large enough to
1169 cause at least a one-bit discretization.)
1175 the more noise you have, the greater your SFDR, but it
1176 takes many more samples to compensate for the increased
1183 if you feel the need to average samples for, for example, two seconds,
1184 your signal will need to be <emphasis>very</emphasis> slowly-varying,
1185 i.e., not varying more than your target uncertainty for the entire two
1193 As you might have guessed, the &comedi; library has functions
1194 to help you in your quest to accurately measure slowly varying
1197 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,
1198 unsigned int channel);
1200 This function initializes the
1201 <link linkend="ref-type-comedi-sv-t">comedi_sv_t</link> data structure, used
1202 to do the averaging acquisition:
1204 struct comedi_sv_struct {
1205 <link linkend="ref-type-comedi-t">comedi_t</link> *dev;
1206 unsigned int subdevice;
1213 /* number of measurements to average (for analog inputs) */
1219 The actual acquisition is done with:
1221 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);
1223 The number of samples over which the
1224 <function>comedi_sv_measure()</function> averages is limited by the
1225 implementation (currently the limit is 100 samples).
1229 One typical use for this function is the measurement of thermocouple
1231 And the &comedi; self-calibration utility also uses these functions.
1232 On some hardware, it is possible to tell it to measure an
1233 internal stable voltage reference, which is typically going
1234 to be very slowly varying; on the kilosecond time scale
1235 or more. So, it is reasonable to measure millions of samples,
1236 to get a very accurate measurement of the A/D converter output
1237 value that corresponds to the voltage reference. Sometimes,
1238 however, this is overkill, since there is no need to
1239 perform a part-per-million calibration to a standard that
1240 is only accurate to a part-per-thousand.
1245 <section id="experimentalfunctionality">
1247 Experimental functionality
1251 The following subsections document functionality that has not yet
1252 matured. Most of this functionality has even not been implemented yet
1253 in any single device driver. This information is included here, in
1254 order to stimulate discussion about their API, and to encourage
1255 pioneering implementations.
1258 <section id="digitalinputcombining">
1260 Digital input combining machines
1264 (<emphasis role="strong">Status: experimental (i.e., no driver implements
1265 this yet)</emphasis>)
1268 When one or several digital inputs are used to modify an output
1269 value, either an accumulator or a single digital line or bit,
1270 a bitfield structure is typically used in the &comedi; interface.
1271 The digital inputs have two properties, <quote>sensitive</quote> inputs
1272 and <quote>modifier</quote> inputs. Edge transitions on sensitive
1273 inputs cause changes in the output signal, whereas modifier inputs
1274 change the effect of edge transitions on sensitive inputs. Note that
1275 inputs can be both modifier inputs and sensitive inputs.
1279 For simplification purposes, it is assumed that multiple digital
1280 inputs do not change simultaneously.
1284 The combined state of the modifier inputs determine a modifier
1285 state. For each combination of modifier state and sensitive
1286 input, there is a set of bits that determine the effect on the
1287 output value due to positive or negative transitions of the
1288 sensitive input. For each transition direction, there are two
1289 bits defined as follows:
1291 <variablelist spacing="compact">
1294 <listitem>transition is ignored.</listitem>
1298 <listitem>accumulator is incremented, or output is set.</listitem>
1302 <listitem>accumulator is decremented, or output is cleared.</listitem>
1306 <listitem>reserved.</listitem>
1310 For example, a simple digital follower is specified by the bit
1311 pattern 01 10, because it sets the output on positive transitions
1312 of the input, and clears the output on negative transitions. A
1313 digital inverter is similarily 10 01. These systems have only
1314 one sensitive input.
1318 As another example, a simple up counter, which increments on
1319 positive transitions of one input, is specified by 01 00. This
1320 system has only one sensitive input.
1324 When multiple digital inputs are used, the inputs are divided
1325 into two types, inputs which cause changes in the accumulator, and
1326 those that only modify the meaning of transitions on other inputs.
1327 Modifier inputs do not require bitfields, but there needs to be
1328 a bitfield of length 4*(2^(N-1)) for each edge sensitive input,
1329 where N is the total number of inputs. Since N is usually 2 or
1330 3, with only one edge sensitive input, the scaling issues are
1337 <section id="analogconversion">
1339 Analog filtering configuration
1343 <emphasis role="strong">(Status: design (i.e., no driver implements
1344 this yet).)</emphasis>
1348 The <link linkend="insn-data-structure-insn">insn</link> field of the
1349 <link linkend="insn-data-structure">instruction data structure</link>
1350 has not been assigned yet.
1353 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1354 of the <link linkend="insn-data-structure">instruction data
1355 structure</link> is ignored.
1359 Some devices have the capability to add white noise (dithering) to
1360 analog input measurement. This additional noise can then be averaged
1361 out, to get a more accurate measurement of the input signal. It
1362 should not be assumed that channels can be separately configured.
1363 A simple design can use 1 bit to turn this feature on/off.
1367 Some devices have the capability of changing the glitch characteristics
1368 of analog output subsytems. The default (off) case should be where
1369 the average settling time is lowest. A simple design can use 1 bit
1370 to turn this feature on/off.
1374 Some devices have a configurable analog filters as part of the analog
1375 input stage. A simple design can use 1 bit to enable/disable the
1376 filter. Default is disabled, i.e., the filter being bypassed, or if
1377 the choice is between two filters, the filter with the largest
1382 <section id="waveformgeneration">
1384 Analog Output Waveform Generation
1388 <emphasis role="strong">(Status: design (i.e., no driver implements
1389 this yet).)</emphasis>
1392 The <link linkend="insn-data-structure-insn">insn</link> field of the
1393 <link linkend="insn-data-structure">instruction data structure</link>
1394 has not been assigned yet.
1397 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1398 of the <link linkend="insn-data-structure">instruction data
1399 structure</link> is ignored.
1403 Some devices have the ability to cyclicly loop through samples kept in
1404 an on-board analog output FIFO. This config should allow the user to
1405 enable/disable this mode.
1409 This config should allow the user to configure the number of samples
1410 to loop through. It may be necessary to configure the channels used.
1415 <section id="extendedtriggering">
1420 <emphasis role="strong">(Status: alpha.)</emphasis>
1424 The <link linkend="insn-data-structure-insn">insn</link> field of the
1425 <link linkend="insn-data-structure">instruction data structure</link>
1426 has not been assigned yet.
1429 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1430 of the <link linkend="insn-data-structure">instruction data
1431 structure</link> is ignored.
1435 This section covers common information for all extended
1436 triggering configuration, and doesn't describe a particular
1437 type of extended trigger.
1441 Extended triggering is used to configure triggering engines that
1442 do not fit into commands. In a typical programming sequence, the
1443 application will use
1444 <link linkend="instructionsconfiguration">configuration instructions</link>
1445 to configure an extended trigger, and a
1446 <link linkend="commandsstreaming">command</link>,
1448 <link linkend="trig-other">TRIG_OTHER</link> as one of the trigger
1453 Extended trigger configuration should be designed in such a way
1454 that the user can probe for valid parameters, similar to how
1455 command testing works. An extended trigger configuration instruction
1456 should not configure the hardware directly, rather, the configuration
1457 should be saved until the subsequent command is issued. This
1458 allows more flexibility for future interface changes.
1462 It has not been decided whether the configuration stage should return a
1463 token that is then used as the trigger argument in the command.
1464 Using tokens is one method to satisfy the problem that extended
1465 trigger configurations may have subtle compatiblity issues with
1466 other trigger sources/arguments that can only be determined at
1467 command test time. Passing all stages of a command test should
1468 only be allowed with a properly configured extended trigger.
1472 Extended triggers must use
1473 <link linkend="insn-data-structure-data">data[1]</link> as flags. The
1474 upper 16 bits are reserved and used only for flags that are common to
1475 all extended triggers. The lower 16 bits may be defined by the
1476 particular type of extended trigger.
1480 Various types of extended triggers must use
1481 <link linkend="insn-data-structure-data">data[1]</link> to know which
1482 event the extended trigger will be assigned to in the command
1483 structure. The possible values are an OR'd mask of the following:
1494 COMEDI_EV_SCAN_BEGIN
1516 <section id="analogtriggering">
1521 <emphasis role="strong">
1522 (Status: alpha. The <function>ni_mio_common.c</function> driver
1523 implements this feature.)
1528 The <link linkend="insn-data-structure-insn">insn</link> field of the
1529 <link linkend="insn-data-structure">instruction data structure</link>
1530 has not been assigned yet.
1533 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1534 of the <link linkend="insn-data-structure">instruction data
1535 structure</link> is ignored.
1539 The <link linkend="insn-data-structure-data">data</link> field
1540 of the <link linkend="insn-data-structure">instruction data
1541 structure</link> is used as follows:
1542 <variablelist spacing="compact">
1544 <term>data[1]</term>
1545 <listitem>trigger and combining machine configuration.</listitem>
1548 <term>data[2]</term>
1549 <listitem>analog triggering signal chanspec.</listitem>
1552 <term>data[3]</term>
1553 <listitem>primary analog level.</listitem>
1556 <term>data[4]</term>
1557 <listitem>secondary analog level.</listitem>
1562 Analog triggering is described by a digital combining machine that
1563 has two sensitive digital inputs. The sensitive digital inputs are
1564 generated by configurable analog comparators. The analog comparators
1565 generate a digital 1 when the analog triggering signal is greater
1566 than the comparator level. The digital inputs are not modifier
1567 inputs. Note, however, there is an effective modifier due to the
1568 restriction that the primary analog comparator level must be less
1569 than the secondary analog comparator level.
1573 If only one analog comparator signal is used, the combining machine
1574 for the secondary input should be set to ignored, and the secondary
1575 analog level should be set to 0.
1579 The interpretation of the chanspec and voltage levels is device
1580 dependent, but should correspond to similar values of the analog
1581 input subdevice, if possible.
1585 Notes: Reading range information is not addressed. This makes it
1586 difficult to convert comparator voltages to data values.
1590 Possible extensions: A parameter that specifies the necessary time
1591 that the set condition has to be true before the trigger is generated.
1592 A parameter that specifies the necessary time that the reset condition
1593 has to be true before the state machine is reset.
1598 <section id="bitfieldmatching">
1600 Bitfield Pattern Matching Extended Trigger
1603 <emphasis role="strong">
1604 (Status: design. No driver implements this feature yet.)
1609 The <link linkend="insn-data-structure-insn">insn</link> field of the
1610 <link linkend="insn-data-structure">instruction data structure</link>
1611 has not been assigned yet.
1614 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1615 of the <link linkend="insn-data-structure">instruction data
1616 structure</link> is ignored.
1620 The <link linkend="insn-data-structure-data">data</link> field
1621 of the <link linkend="insn-data-structure">instruction data
1622 structure</link> is used as follows:
1624 <variablelist spacing="compact">
1626 <term>data[1]</term>
1627 <listitem>trigger flags.</listitem>
1630 <term>data[2]</term>
1631 <listitem>mask.</listitem>
1634 <term>data[3]</term>
1635 <listitem>pattern.</listitem>
1640 The pattern matching trigger issues a trigger when all of a specifed
1641 set of input lines match a specified pattern. If the device allows,
1642 the input lines should correspond to the input lines of a digital input
1643 subdevice, however, this will necessarily be device dependent. Each
1644 possible digital line that can be matched is assigned a bit in the
1645 mask and pattern. A bit set in the mask indicates that the
1646 input line must match the corresponding bit in the pattern.
1647 A bit cleared in the mask indicates that the input line is ignored.
1651 Notes: This only allows 32 bits in the pattern/mask, which may be
1652 too few. Devices may support selecting different sets of lines from
1653 which to match a pattern.
1657 Discovery: The number of bits can be discovered by setting the mask
1658 to all 1's. The driver must modify this value and return -EAGAIN.
1663 <section id="countertimer">
1665 Counter configuration
1668 <emphasis role="strong">
1669 (Status: design. No driver implements this feature yet.)
1674 The <link linkend="insn-data-structure-insn">insn</link> field of the
1675 <link linkend="insn-data-structure">instruction data structure</link>
1676 has not been assigned yet.
1679 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1680 of the <link linkend="insn-data-structure">instruction data
1681 structure</link> is used to specify which counter to use. (I.e., the
1682 counter is a &comedi; channel.)
1686 The <link linkend="insn-data-structure-data">data</link> field
1687 of the <link linkend="insn-data-structure">instruction data
1688 structure</link> is used as follows:
1690 <variablelist spacing="compact">
1692 <term>data[1]</term>
1693 <listitem>trigger configuration.</listitem>
1696 <term>data[2]</term>
1697 <listitem>primary input chanspec.</listitem>
1700 <term>data[3]</term>
1701 <listitem>primary combining machine configuration.</listitem>
1704 <term>data[4]</term>
1705 <listitem>secondary input chanspec.</listitem>
1708 <term>data[5]</term>
1709 <listitem>secondary combining machine configuration.</listitem>
1712 <term>data[6]</term>
1713 <listitem>latch configuration.</listitem>
1718 Note that this configuration is only useful if the counting has to be
1719 done in <emphasis>software</emphasis>. Many cards offer configurable
1720 counters in hardware; e.g., general purpose timer cards can be
1721 configured to act as pulse generators, frequency counters, timers,
1725 Counters can be operated either in synchronous mode (using
1726 <link linkend="comediinsnstructure">INSN_READ</link>)
1727 or asynchronous mode (using
1728 <link linkend="commandsstreaming">commands</link>), similar to analog
1730 The input signal for both modes is the accumulator.
1731 Commands on counter subdevices are almost always specified using
1732 <link linkend="command-data-struct-scan-begin-src">scan_begin_src</link>
1733 = <link linkend="trigother-event">TRIG_OTHER</link>, with the
1734 counter configuration also serving as the extended configuration for
1735 the scan begin source.
1739 Counters are made up of an accumulator and a combining machine that
1740 determines when the accumulator should be incremented or decremented
1741 based on the values of the input signals. The combining machine
1742 optionally determines when the accumulator should be latched and
1743 put into a buffer. This feature is used in asynchronous mode.
1747 Note: How to access multiple pieces of data acquired at each event?
1752 <section id="auxcounter">
1754 One source plus auxiliary counter configuration
1757 <emphasis role="strong">
1758 (Status: design. No driver implements this feature yet.)
1763 The <link linkend="insn-data-structure-insn">insn</link> field of the
1764 <link linkend="insn-data-structure">instruction data structure</link>
1765 has not been assigned yet.
1768 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1769 of the <link linkend="insn-data-structure">instruction data
1770 structure</link> is used to …
1774 The <link linkend="insn-data-structure-data">data</link> field
1775 of the <link linkend="insn-data-structure">instruction data
1776 structure</link> is used as follows:
1780 <variablelist spacing="compact">
1782 <term>data[1]</term>
1784 is flags, including the flags for the command triggering
1785 configuration. If a command is not subsequently issued on the
1786 subdevice, the command triggering portion of the flags are ignored.
1790 <term>data[2]</term>
1792 determines the mode of operation. The mode of operation
1793 is actually a bitfield that encodes what to do for various
1794 transitions of the source signals.
1798 <term>data[3]</term>
1799 <term>data[4]</term>
1801 determine the primary source for the counter, similar to the
1802 <link linkend="command-data-struct-scan-begin-src">_src</link> and the
1803 <link linkend="command-data-struct-scan-begin-arg">_arg</link> fields
1805 <link linkend="command-data-struct">command data structure</link>.
1812 Notes: How to specify which events cause a latch and push, and what
1820 National instruments RTSI trigger bus
1823 A number of NI boards support the RTSI (Real Time System Integration) bus.
1824 It's primary use is to synchronize multiple DAQ cards.
1825 On PXI boards, the RTSI lines correspond to the PXI trigger lines 0 to 7. PCI
1826 boards use cables to connect to their RTSI ports.
1827 The RTSI bus consists of 8 digital signal lines numbered 0 to 7 that are bi-directional.
1828 Each of these signal lines
1829 can be configured as an input or output, and the signal appearing on the output
1830 of each line can be configured to one of several internal board timing signals
1831 (although on older boards RTSI line 7 can only be used for the clock signal).
1832 The ni_pcimio, ni_atmio, and ni_mio_cs drivers expose the RTSI bus
1833 as a digital I/O subdevice (subdevice number 10).
1836 The functions comedi_dio_config() and comedi_dio_get_config() can be used on
1837 the RTSI subdevice to
1838 set/query the direction (input or output) of each of the RTSI lines individually.
1841 The subdevice also supports the
1842 INSN_CONFIG_SET_CLOCK_SRC and INSN_CONFIG_GET_CLOCK_SRC configuration
1843 instructions, which can be
1844 used to configure/query what source the board uses to synchronize its
1845 master clock to. The various possibilities are defined in the comedi.h
1849 <tgroup cols='2' align='left'>
1852 <entry>Clock Source</entry>
1853 <entry>Description</entry>
1858 <entry>NI_MIO_INTERNAL_CLOCK</entry>
1860 Use the board's internal oscillator.
1864 <entry>NI_MIO_RTSI_CLOCK</entry>
1866 Use the RTSI line 7 as the master clock. This source is
1867 only supported on pre-m-series boards. The newer m-series boards
1868 use NI_MIO_PLL_RTSI_CLOCK() instead.
1872 <entry>NI_MIO_PLL_PXI_STAR_TRIGGER_CLOCK</entry>
1874 Only available for newer m-series PXI boards. Synchronizes the board's
1875 phased-locked loop (which runs at 80MHz) to the PXI star trigger
1880 <entry>NI_MIO_PLL_PXI10_CLOCK</entry>
1882 Only available for newer m-series PXI boards.
1883 Synchronizes the board's
1884 phased-locked loop (which runs at 80MHz) to the 10 MHz PXI backplane
1889 <entry><programlisting>unsigned NI_MIO_PLL_RTSI_CLOCK(unsigned n)</programlisting></entry>
1891 Only available for newer m-series boards.
1892 The function returns a clock source which will cause the board's
1893 phased-locked loop (which runs at 80MHz) to syncronize to the RTSI
1894 line specified in the function argument.
1902 For all clock sources except NI_MIO_INTERNAL_CLOCK and NI_MIO_PLL_PXI10_CLOCK,
1903 you should pass the period of the clock your are feeding to the board when
1904 using INSN_CONFIG_SET_CLOCK_SRC.
1907 Finally, the configuration instructions INSN_CONFIG_SET_ROUTING and
1908 INSN_CONFIG_GET_ROUTING can be used to select/query which internal signal
1909 will appear on a given RTSI output line. The header file comedi.h defines
1910 the following signal sources which can be routed to an RTSI line:
1914 <tgroup cols='2' align='left'>
1917 <entry>Signal Source</entry>
1918 <entry>Description</entry>
1923 <entry>NI_RTSI_OUTPUT_ADR_START1</entry>
1925 ADR_START1, an analog input start signal. See the NI's
1926 DAQ-STC Technical Reference Manual for more information.
1930 <entry>NI_RTSI_OUTPUT_ADR_START2</entry>
1932 ADR_START2, an analog input stop signal. See the NI's
1933 DAQ-STC Technical Reference Manual for more information.
1937 <entry>NI_RTSI_OUTPUT_SCLKG</entry>
1939 SCLKG, a sample clock signal. See the NI's
1940 DAQ-STC Technical Reference Manual for more information.
1944 <entry>NI_RTSI_OUTPUT_DACUPDN</entry>
1946 DACUPDN, a dac update signal. See the NI's
1947 DAQ-STC Technical Reference Manual for more information.
1951 <entry>NI_RTSI_OUTPUT_DA_START1</entry>
1953 DA_START1, an analog output start signal. See the NI's
1954 DAQ-STC Technical Reference Manual for more information.
1958 <entry>NI_RTSI_OUTPUT_G_SRC0</entry>
1960 G_SRC0, the source signal to general purpose counter 0. See the NI's
1961 DAQ-STC Technical Reference Manual for more information.
1965 <entry>NI_RTSI_OUTPUT_G_GATE0</entry>
1967 G_GATE0, the gate signal to general purpose counter 0. See the NI's
1968 DAQ-STC Technical Reference Manual for more information.
1972 <entry>NI_RTSI_OUTPUT_RGOUT0</entry>
1974 RGOUT0, the output signal of general purpose counter 0. See the NI's
1975 DAQ-STC Technical Reference Manual for more information.
1979 <entry><programlisting>unsigned NI_RTSI_OUTPUT_RTSI_BRD(unsigned n)</programlisting></entry>
1981 RTSI_BRD0 though RTSI_BRD3 are four internal signals which can
1982 have various other signals routed to them in turn. Currently, comedi
1983 provides no way to configure the signals routed to the RTSI_BRD lines.
1984 See the NI's DAQ-STC Technical Reference Manual for more information.
1988 <entry>NI_RTSI_OUTPUT_RTSI_OSC</entry>
1990 The RTSI clock signal. On pre-m-series boards, this signal is always
1991 routed to RTSI line 7, and cannot be routed to lines 0 through 6. On
1992 m-series boards, any RTSI line can be configured to output the clock
2001 The RTSI bus pins may be used as trigger inputs for many of the
2002 COMEDI trigger functions. To use the RTSI bus pins, set the source to be
2003 TRIG_EXT and the source argument using the return values from the
2004 NI_EXT_RTSI() function (or similarly the NI_EXT_PFI() function if you want
2005 to trigger from a PFI line). The CR_EDGE and CR_INVERT flags may
2006 also be set on the trigger source argument to specify edge and
2007 falling edge/low level triggering.
2011 An example to set up a device as a master is given below.
2014 <programlisting><![CDATA[
2015 void comediEnableMaster(comedi_t *dev){
2016 comedi_insn configCmd;
2017 lsampl_t configData[2];
2020 static const unsigned rtsi_subdev = 10;
2021 static const unsigned rtsi_clock_line = 7;
2023 /* Route RTSI clock to line 7 (not needed on pre-m-series boards since their
2024 clock is always on line 7). */
2025 memset(&configCmd, 0, sizeof(configCmd));
2026 memset(&configData, 0, sizeof(configData));
2027 configCmd.insn = INSN_CONFIG;
2028 configCmd.subdev = rtsi_subdev;
2029 configCmd.chanspec = rtsi_clock_line;
2031 configCmd.data = configData;
2032 configCmd.data[0] = INSN_CONFIG_SET_ROUTING;
2033 configCmd.data[1] = NI_RTSI_OUTPUT_RTSI_OSC;
2034 ret = comedi_do_insn(dev, &configCmd);
2036 comedi_perror("comedi_do_insn: INSN_CONFIG");
2039 // Set clock RTSI line as output
2040 ret = comedi_dio_config(dev, rtsi_subdev, rtsi_clock_line, INSN_CONFIG_DIO_OUTPUT);
2042 comedi_perror("comedi_dio_config");
2046 /* Set routing of the 3 main AI RTSI signals and their direction to output.
2047 We're reusing the already initialized configCmd instruction here since
2048 it's mostly the same. */
2049 configCmd.chanspec = 0;
2050 configCmd.data[1] = NI_RTSI_OUTPUT_ADR_START1;
2051 ret = comedi_do_insn(dev, &configCmd);
2053 comedi_perror("comedi_do_insn: INSN_CONFIG");
2056 ret = comedi_dio_config(dev, rtsi_subdev, 0, INSN_CONFIG_DIO_OUTPUT);
2058 comedi_perror("comedi_dio_config");
2062 configCmd.chanspec = 1;
2063 configCmd.data[1] = NI_RTSI_OUTPUT_ADR_START2;
2064 ret = comedi_do_insn(dev, &configCmd);
2066 comedi_perror("comedi_do_insn: INSN_CONFIG");
2069 ret = comedi_dio_config(dev, rtsi_subdev, 1, INSN_CONFIG_DIO_OUTPUT);
2071 comedi_perror("comedi_dio_config");
2075 configCmd.chanspec = 2;
2076 configCmd.data[1] = NI_RTSI_OUTPUT_SCLKG;
2077 ret = comedi_do_insn(dev, &configCmd);
2079 comedi_perror("comedi_do_insn: INSN_CONFIG");
2082 ret = comedi_dio_config(dev, rtsi_subdev, 2, INSN_CONFIG_DIO_OUTPUT);
2084 comedi_perror("comedi_dio_config");
2088 ]]></programlisting>
2091 An example to slave a m-series device from this master follows. A pre-m-series
2092 device would need to use NI_MIO_RTSI_CLOCK for the clock source instead. In
2093 your code, you may also wish to configure the master device to use the
2094 external clock source instead of using its internal clock directly (for
2095 best syncronization).
2097 <programlisting><![CDATA[
2098 void comediEnableSlave(comedi_t *dev){
2099 comedi_insn configCmd;
2100 lsampl_t configData[3];
2102 unsigned int d = 0;;
2103 static const unsigned rtsi_subdev = 10;
2104 static const unsigned rtsi_clock_line = 7;
2106 memset(&configCmd, 0, sizeof(configCmd));
2107 memset(&configData, 0, sizeof(configData));
2108 configCmd.insn = INSN_CONFIG;
2109 configCmd.subdev = rtsi_subdev;
2110 configCmd.chanspec = 0;
2112 configCmd.data = configData;
2113 configCmd.data[0] = INSN_CONFIG_SET_CLOCK_SRC;
2114 configCmd.data[1] = NI_MIO_PLL_RTSI_CLOCK(rtsi_clock_line);
2115 configCmd.data[2] = 100; /* need to give it correct external clock period */
2116 ret = comedi_do_insn(dev, &configCmd);
2118 comedi_perror("comedi_do_insn: INSN_CONFIG");
2121 /* configure RTSI clock line as input */
2122 ret = comedi_dio_config(dev, rtsi_subdev, rtsi_clock_line, INSN_CONFIG_DIO_INPUT);
2124 comedi_perror("comedi_dio_config");
2127 /* Configure RTSI lines we are using for AI signals as inputs. */
2128 ret = comedi_dio_config(dev, rtsi_subdev, 0, INSN_CONFIG_DIO_INPUT);
2130 comedi_perror("comedi_dio_config");
2133 ret = comedi_dio_config(dev, rtsi_subdev, 1, INSN_CONFIG_DIO_INPUT);
2135 comedi_perror("comedi_dio_config");
2138 ret = comedi_dio_config(dev, rtsi_subdev, 2, INSN_CONFIG_DIO_INPUT);
2140 comedi_perror("comedi_dio_config");
2145 int comediSlaveStart(comedi_t *dev){
2147 unsigned int nChannels = 8;
2148 double sampleRate = 50000;
2149 unsigned int chanList[8];
2153 for(i = 0; i < nChannels; i++){
2154 chanList[i] = CR_PACK(i, 0, AREF_GROUND);
2157 memset(&cmd, 0, sizeof(cmd));
2158 ret = comedi_get_cmd_generic_timed(dev, subdevice, &cmd,
2159 (int)(1e9/(nChannels * sampleRate)));
2161 printf("comedi_get_cmd_generic_timed failed\n");
2164 cmd.chanlist = chanList;
2165 cmd.chanlist_len = nChannels;
2166 cmd.scan_end_arg = nChannels;
2167 cmd.start_src = TRIG_EXT;
2168 cmd.start_arg = CR_EDGE | NI_EXT_RTSI(0);
2169 cmd.convert_src = TRIG_EXT;
2170 cmd.convert_arg = CR_INVERT | CR_EDGE | NI_EXT_RTSI(2);
2171 cmd.stop_src = TRIG_NONE;
2173 ret = comedi_command(dev0, &cmd0);
2175 printf("comedi_command failed\n");
2180 ]]></programlisting>