doc/other.xml

   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">
   5 %comedilib_entities;
   6 ]>
   7
   8 <section id="acquisitionfunctions">
   9 <title>
  10 Acquisition and configuration functions
  11 </title>
  12
  13 <para>
  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
  19 detail.
  20 </para>
  21
  22 <section id="singleacquisition">
  23 <title>
  24 Functions for single acquisition
  25 </title>
  26
  27 <para>
  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.
  32 </para>
  33
  34 <section id="dio">
  35 <title>
  36 Single digital acquisition
  37 </title>
  38
  39 <para>
  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.
  45 </para>
  46
  47 <para>
  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.
  55 </para>
  56
  57 <para>
  58 Individual bits on a digital I/O device can be read and written using
  59 the functions <function><link linkend="func-ref-comedi-dio-read">comedi_dio_read</link></function>
  60 and <function><link linkend="func-ref-comedi-dio-write">comedi_dio_write</link></function>:
  61
  62 <funcsynopsis><funcprototype>
  63 <funcdef>int <function>comedi_dio_read</function></funcdef>
  64 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
  65 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
  66 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
  67 <paramdef>unsigned int *<parameter>bit</parameter></paramdef>
  68 </funcprototype></funcsynopsis>
  69
  70 <funcsynopsis><funcprototype>
  71 <funcdef>int <function>comedi_dio_write</function></funcdef>
  72 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
  73 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
  74 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
  75 <paramdef>unsigned int <parameter>bit</parameter></paramdef>
  76 </funcprototype></funcsynopsis>
  77
  78 The <parameter class="function">device</parameter> parameter is a
  79 <link linkend="ref-type-comedi-t">pointer</link>
  80 to a successfully opened &comedi; device.
  81 The <parameter class="function">subdevice</parameter> and
  82 <parameter class="function">channel</parameter> parameters are positive
  83 integers that indicate which subdevice and channel is used in the
  84 acquisition. The integer <parameter class="function">bit</parameter>
  85 contains the value of the acquired bit.
  86 </para>
  87 <para>
  88 The direction of bidirectional lines can be configured using the function
  89 <function><link linkend="func-ref-comedi-dio-config">comedi_dio_config</link></function>:
  90
  91 <funcsynopsis><funcprototype>
  92 <funcdef>int <function>comedi_dio_config</function></funcdef>
  93 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
  94 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
  95 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
  96 <paramdef>unsigned int <parameter>dir</parameter></paramdef>
  97 </funcprototype></funcsynopsis>
  98
  99 The parameter <parameter class="function">dir</parameter> should be
 100 either <constant>COMEDI_INPUT</constant> or
 101 <constant>COMEDI_OUTPUT</constant>.
 102 Many digital I/O subdevices group channels into blocks for
 103 configuring direction.  Changing one channel in a block changes
 104 the entire block.
 105 </para>
 106
 107 <para>
 108 Multiple channels can be read and written simultaneously using the
 109 function <function><link linkend="func-ref-comedi-dio-bitfield2">comedi_dio_bitfield2</link></function>:
 110
 111 <funcsynopsis><funcprototype>
 112 <funcdef>int <function>comedi_dio_bitfield2</function></funcdef>
 113 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
 114 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
 115 <paramdef>unsigned int <parameter>write_mask</parameter></paramdef>
 116 <paramdef>unsigned int *<parameter>bits</parameter></paramdef>
 117 <paramdef>unsigned int <parameter>base_channel</parameter></paramdef>
 118 </funcprototype></funcsynopsis>
 119
 120 Each channel from <parameter class="function">base_channel</parameter>
 121 to <parameter class="function">base_channel</parameter> &plus;
 122 <literal>31</literal> is assigned to a bit in the
 123 <parameter class="function">write_mask</parameter> and
 124 <parameter class="function">bits</parameter>
 125 bitfield with bit 0 assigned to channel
 126 <parameter class="function">base_channel</parameter>, bit 1 assigned to channel
 127 <parameter class="function">base_channel</parameter> &plus;
 128 <literal>1</literal>, etc.  If a bit in
 129 <parameter class="function">write_mask</parameter> is set, the
 130 corresponding bit in <parameter class="function">*bits</parameter> will
 131 be written to the digital output line corresponding to the channel given by
 132 <parameter class="function">base_channel</parameter> plus the bit number.
 133 Each digital line is then read and placed into
 134 <parameter class="function">*bits</parameter>.  The value
 135 of bits in <parameter class="function">*bits</parameter> corresponding
 136 to digital output lines is undefined and device-specific.  Channel
 137 <parameter class="function">base_channel</parameter> &plus;
 138 <literal>0</literal> is the least significant bit in the bitfield.  No
 139 more than 32 channels at once can be accessed using this method.
 140 <emphasis role="strong">Warning!</emphasis> Older versions of &comedi;
 141 may ignore <parameter class="function">base_channel</parameter> and treat
 142 it as <literal>0</literal> unless the subdevice has more than 32 channels.
 143 </para>
 144
 145 <para>
 146 The digital acquisition functions seem to be very simple, but, behind
 147 the implementation screens of the &comedi; kernel module, they are
 148 executed as special cases of the general
 149 <link linkend="instructions">instruction</link> command.
 150 </para>
 151
 152
 153 </section>
 154
 155
 156 <section id="singleanalog">
 157 <title>
 158 Single analog acquisition
 159 </title>
 160 <para>
 161 Analog &comedi; channels can produce data values that are
 162 <emphasis>samples</emphasis> from continuous analog signals.
 163 These samples are integers with a significant content in
 164 the range of, typically, 8, 10, 12, or 16 bits.
 165 </para>
 166 <para>
 167 Single samples can be read from an analog channel using the function
 168 <function><link linkend="func-ref-comedi-data-read">comedi_data_read</link></function>:
 169
 170 <funcsynopsis><funcprototype>
 171 <funcdef>int <function>comedi_data_read</function></funcdef>
 172 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
 173 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
 174 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
 175 <paramdef>unsigned int <parameter>range</parameter></paramdef>
 176 <paramdef>unsigned int <parameter>aref</parameter></paramdef>
 177 <paramdef>lsampl_t *<parameter>data</parameter></paramdef>
 178 </funcprototype></funcsynopsis>
 179
 180 This reads one such data value from a &comedi; channel, and puts it in
 181 the user-specified <parameter class="function">data</parameter> buffer.
 182 </para>
 183
 184 <para>
 185 The <parameter class="function">range</parameter> parameter is the zero-based
 186 index of one of the gain ranges supported by the channel.  This is a number
 187 from 0 to N-1 where N is the number of ranges supported by the channel.
 188 Use the function
 189 <function><link linkend="func-ref-comedi-get-n-ranges">comedi_get_n_ranges</link></function>
 190 to get the number of ranges supported by the channel, the function
 191 <function><link linkend="func-ref-comedi-find-range">comedi_find_range</link></function>
 192 to search for a suitable range, or the function
 193 <function><link linkend="func-ref-comedi-get-range">comedi_get_range</link></function>
 194 to get the details of a supported range.
 195 </para>
 196
 197 <para>
 198 The <parameter class="function">aref</parameter> parameter specifies an
 199 analog reference to use:
 200 <constant><link linkend="aref-ground">AREF_GROUND</link></constant>,
 201 <constant><link linkend="aref-common">AREF_COMMON</link></constant>,
 202 <constant><link linkend="aref-diff">AREF_DIFF</link></constant>, or
 203 <constant><link linkend="aref-other">AREF_OTHER</link></constant>.
 204 Use the function
 205 <function><link linkend="func-ref-comedi-get-subdevice-flags">comedi_get_subdevice_flags</link></function>
 206 to see which analog references are supported by the subdevice.
 207 </para>
 208
 209 <para>
 210 In the opposite direction, single samples can be written to an analog output
 211 channel using the function
 212 <function><link linkend="func-ref-comedi-data-write">comedi_data_write</link></function>:
 213
 214 <funcsynopsis><funcprototype>
 215 <funcdef>int <function>comedi_data_write</function></funcdef>
 216 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
 217 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
 218 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
 219 <paramdef>unsigned int <parameter>range</parameter></paramdef>
 220 <paramdef>unsigned int <parameter>aref</parameter></paramdef>
 221 <paramdef>lsampl_t <parameter>data</parameter></paramdef>
 222 </funcprototype></funcsynopsis>
 223 </para>
 224
 225 <para>
 226 Raw data values read or written by the above functions
 227 are unsigned integers less than, or equal to, the maximum sample value
 228 of the channel, which can be determined using the function
 229 <function><link linkend="func-ref-comedi-get-maxdata">comedi_get_maxdata</link></function>:
 230
 231 <funcsynopsis><funcprototype>
 232 <funcdef>lsampl_t <function>comedi_get_maxdata</function></funcdef>
 233 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
 234 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
 235 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
 236 </funcprototype></funcsynopsis>
 237
 238 Conversion between raw data values and uncalibrated physical units can
 239 be performed by the functions
 240 <function><link linkend="func-ref-comedi-to-phys">comedi_to_phys</link></function>
 241 and <function><link linkend="func-ref-comedi-from-phys">comedi_from_phys</link></function>:
 242
 243 <funcsynopsis><funcprototype>
 244 <funcdef>double <function>comedi_to_phys</function></funcdef>
 245 <paramdef>lsampl_t <parameter>data</parameter></paramdef>
 246 <paramdef>comedi_range *<parameter>range</parameter></paramdef>
 247 <paramdef>lsampl_t <parameter>maxdata</parameter></paramdef>
 248 </funcprototype></funcsynopsis>
 249
 250 <funcsynopsis><funcprototype>
 251 <funcdef>lsampl_t <function>comedi_from_phys</function></funcdef>
 252 <paramdef>double <parameter>data</parameter></paramdef>
 253 <paramdef>comedi_range *<parameter>range</parameter></paramdef>
 254 <paramdef>lsampl_t <parameter>maxdata</parameter></paramdef>
 255 </funcprototype></funcsynopsis>
 256 </para>
 257
 258 <para>
 259 There are some data structures in these commands that are not fully
 260 self-explanatory:
 261 <itemizedlist>
 262
 263 <listitem>
 264 <para>
 265 <type><link linkend="ref-type-comedi-t">comedi_t</link></type>: this data structure
 266 contains all information that a user program has to know about an
 267 <emphasis>open</emphasis> &comedi; device. The programmer doesn't have
 268 to fill in this data structure manually: it gets filled in by opening
 269 the device.
 270 </para>
 271 </listitem>
 272
 273 <listitem>
 274 <para>
 275 <type><link linkend="ref-type-lsampl-t">lsampl_t</link></type>: this
 276 <quote>data structure</quote> represents one single sample. On most
 277 architectures, it's nothing more than a 32 bits value. Internally,
 278 &comedi; does some conversion from raw sample data to
 279 <quote>correct</quote> integers. This is called <quote>data
 280 munging</quote>.
 281 </para>
 282 </listitem>
 283
 284 <listitem>
 285 <para>
 286 <type><link linkend="ref-type-comedi-range">comedi_range</link></type>:
 287 this holds the minimum and maximum physical values for a gain range supported
 288 by a channel of a subdevice, and specifies the units. This can be used in
 289 combination with the channel's <quote>maxdata</quote> value to convert between
 290 unsigned integer sample values (of type
 291 <type><link linkend="ref-type-lsampl-t">lsampl_t</link></type> or
 292 <type><link linkend="ref-type-sampl-t">sampl_t</link></type>) and physical
 293 units in a nominal (uncalibrated) way using the
 294 <function><link linkend="func-ref-comedi-to-phys">comedi_to_phys</link></function>
 295 and
 296 <function><link linkend="func-ref-comedi-from-phys">comedi_from_phys</link></function>
 297 functions. Use the
 298 <function><link linkend="func-ref-comedi-get-maxdata">comedi_get_maxdata</link></function>
 299 function to get the <quote>maxdata</quote> value for the channel.
 300 </para>
 301 <para>
 302 Most functions specify the range to be used for a channel by a zero-based
 303 index into the list of ranges supported by the channel. Depending on the
 304 device and subdevice, different channels on the subdevice may or may not
 305 share the same list of ranges, that is, ranges may or may not be
 306 channel-specific. (The <constant>SDF_RANGETYPE</constant> subdevice flag
 307 indicates whether ranges are channel-specific.)
 308 </para>
 309 </listitem>
 310
 311 </itemizedlist>
 312 </para>
 313 <para>
 314 Each single acquisition by, for example,
 315 <function><link linkend="func-ref-comedi-data-read">comedi_data_read</link></function>
 316 requires quite some overhead, because all the arguments of the
 317 function call are checked. If multiple acquisitions must be done on
 318 the same channel, this overhead can be avoided by using a function
 319 that can read more than one sample,
 320 <function><link linkend="func-ref-comedi-data-read-n">comedi_data_read_n</link></function>:
 321
 322 <funcsynopsis><funcprototype>
 323 <funcdef>int <function>comedi_data_read_n</function></funcdef>
 324 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
 325 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
 326 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
 327 <paramdef>unsigned int <parameter>range</parameter></paramdef>
 328 <paramdef>unsigned int <parameter>aref</parameter></paramdef>
 329 <paramdef>lsampl_t *<parameter>data</parameter></paramdef>
 330 <paramdef>unsigned int <parameter>n</parameter></paramdef>
 331 </funcprototype></funcsynopsis>
 332
 333 The number of samples, <parameter class="function">n</parameter>, is
 334 limited by the &comedi; implementation (to a maximum of 100 samples),
 335 because the call is blocking.
 336 </para>
 337 <para>
 338 The start of the a single data acquisition can also be delayed by a specified
 339 number of nano-seconds using the function
 340 <function><link linkend="func-ref-comedi-data-read-delayed">comedi_data_read_delayed</link></function>:
 341
 342 <funcsynopsis><funcprototype>
 343 <funcdef>int <function>comedi_data_read_delayed</function></funcdef>
 344 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
 345 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
 346 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
 347 <paramdef>unsigned int <parameter>range</parameter></paramdef>
 348 <paramdef>unsigned int <parameter>aref</parameter></paramdef>
 349 <paramdef>lsampl_t *<parameter>data</parameter></paramdef>
 350 <paramdef>unsigned int <parameter>nano_sec</parameter></paramdef>
 351 </funcprototype></funcsynopsis>
 352 </para>
 353
 354 <para>
 355 All these read and write acquisition functions are implemented on top
 356 of the generic <link linkend="instructions">instruction</link>
 357 command.
 358 </para>
 359
 360 </section>
 361
 362 </section>
 363
 364
 365 <section id="instructions">
 366 <title>
 367 Instructions for multiple acquisitions
 368 </title>
 369 <para>
 370 The <emphasis>instruction</emphasis> is one of the most generic,
 371 overloaden and flexible functions in the &comedi; API. It is used to
 372 execute a multiple of identical acquisitions on the same channel, but
 373 also to perform a
 374 <link linkend="instructionsconfiguration">configuration</link> of a
 375 channel.
 376 <anchor id="anchor.instruction.list"/>
 377 An <emphasis>instruction list</emphasis> is a list of instructions,
 378 possibly on different channels. Both instructions and instructions
 379 lists are executed <emphasis>synchronously</emphasis>, i.e., while
 380 <emphasis role="strong">blocking</emphasis> the calling process.
 381 This is one of the limitations of instructions; the other one is that
 382 they cannot code an acquisition involving timers or external events.
 383 These limits are eliminated by the
 384 <link linkend="commandsstreaming">command</link> acquisition
 385 primitive.
 386 </para>
 387
 388
 389 <section id="comediinsnstructure">
 390 <title>
 391 The instruction data structure
 392 </title>
 393 <para>
 394 All the information needed to execute an instruction is stored in the
 395 <type><link linkend="ref-type-comedi-insn">comedi_insn</link></type>
 396 data structure:
 397 <programlisting>
 398 typedef struct <anchor id="insn-data-structure"/>comedi_insn_struct {
 399   <anchor id="insn-data-structure-insn"/>unsigned int insn;      // integer encoding the type of acquisition
 400                           // (or configuration)
 401   unsigned int n;         // number of elements in data array
 402   <link linkend="ref-type-lsampl-t">lsampl_t</link> <anchor id="insn-data-structure-data"/>*data;         // pointer to data buffer
 403   unsigned int subdev;    // subdevice
 404   unsigned int <anchor id="insn-data-structure-chanspec"/><link linkend="ref-macro-CR-PACK">chanspec</link>; // encoded channel specification
 405   unsigned int unused[3];
 406 } comedi_insn;
 407 </programlisting>
 408 Because of the large flexibility of the instruction function, many
 409 types of instruction do not need to fill in all fields, or attach
 410 different meanings to the same field. But the current implementation
 411 of &comedi; requires the
 412 <structfield><link linkend="insn-data-structure-data">data</link></structfield>
 413 field to be at least one byte long.
 414 </para>
 415
 416 <para>
 417 The <structfield><link linkend="insn-data-structure-insn">insn</link></structfield> member of the
 418 <link linkend="insn-data-structure">instruction data structure</link>
 419 determines the type of acquisition executed in the corresponding
 420 instruction:
 421 <itemizedlist>
 422
 423 <listitem>
 424 <para>
 425 <constant>INSN_READ</constant>: the instruction executes a read on an
 426 analog channel.
 427 </para>
 428 </listitem>
 429
 430 <listitem>
 431 <para>
 432 <constant>INSN_WRITE</constant>: the instruction executes a write on an
 433 analog channel.
 434 </para>
 435 </listitem>
 436
 437 <listitem>
 438 <para>
 439 <constant>INSN_BITS</constant>: indicates that the instruction must
 440 read or write values on multiple digital I/O channels.
 441 </para>
 442 </listitem>
 443
 444 <listitem>
 445 <para>
 446 <constant>INSN_GTOD</constant>: the instruction performs a
 447 <quote>Get Time Of Day</quote> acquisition.
 448 </para>
 449 </listitem>
 450
 451 <listitem>
 452 <para>
 453 <constant>INSN_WAIT</constant>: the instruction blocks for a specified
 454 number of nanoseconds.
 455 </para>
 456 </listitem>
 457
 458 </itemizedlist>
 459 </para>
 460
 461 </section>
 462
 463
 464 <section id="instructionexecution">
 465 <title>
 466 Instruction execution
 467 </title>
 468 <para>
 469 Once an instruction data structure has been filled in, the
 470 corresponding instruction is executed with the function
 471 <function><link linkend="func-ref-comedi-do-insn">comedi_do_insn</link></function>:
 472
 473 <funcsynopsis><funcprototype>
 474 <funcdef>int <function>comedi_do_insn</function></funcdef>
 475 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
 476 <paramdef>comedi_insn *<parameter>instruction</parameter></paramdef>
 477 </funcprototype></funcsynopsis>
 478
 479 Many &comedi; instructions are shortcuts that relieve the programmer
 480 from explicitly filling in the data structure and calling the
 481 <function><link linkend="func-ref-comedi-do-insn">comedi_do_insn</link></function>
 482 function.
 483 </para>
 484 <para>
 485 A list of instructions can be executed in one function call using the function
 486 <function><link linkend="func-ref-comedi-do-insnlist">comedi_do_insnlist</link></function>:
 487
 488 <funcsynopsis><funcprototype>
 489 <funcdef>int <function>comedi_do_insnlist</function></funcdef>
 490 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
 491 <paramdef>comedi_insnlist *<parameter>list</parameter></paramdef>
 492 </funcprototype></funcsynopsis>
 493
 494 The parameter <parameter class="function">list</parameter> is a pointer to a
 495 <type><link linkend="insnlist-data-structure">comedi_insnlist</link></type>
 496 data structure holding a pointer to an array of <type>comedi_insn</type>
 497 and the number of instructions in the list:
 498 <programlisting>
 499 typedef struct <anchor id="insnlist-data-structure"/>comedi_insnlist_struct {
 500   unsigned int n_insns;
 501   comedi_insn *insns;
 502 } comedi_insnlist;
 503 </programlisting>
 504 </para>
 505 <para>
 506 The number of instructions in the list is limited in the
 507 implementation, because instructions are executed
 508 <emphasis>synchronously</emphasis>, i.e., the call blocks until the
 509 whole instruction (list) has finished.
 510 </para>
 511
 512 </section>
 513
 514 </section>
 515
 516
 517 <section id="instructionsconfiguration">
 518 <title>
 519 Instructions for configuration
 520 </title>
 521 <para>
 522 <xref linkend="instructions"/> explains how instructions are used to do
 523 <emphasis>acquisition</emphasis> on channels. This section explains
 524 how they are used to <emphasis>configure</emphasis> a subdevice.
 525 There are various sorts of configurations, and the
 526 specific information for each different configuration possibility is
 527 to be specified via the
 528 <structfield><link linkend="insn-data-structure-data">data</link></structfield>
 529 buffer of the
 530 <link linkend="insn-data-structure">instruction data structure</link>.
 531 (So, the pointer to a
 532 <type><link linkend="ref-type-lsampl-t">lsampl_t</link></type>
 533 is misused as a pointer to an array with board-specific information.)
 534 </para>
 535
 536 <para>
 537 Using <constant>INSN_CONFIG</constant> as the
 538 <structfield><link linkend="insn-data-structure-insn">insn</link></structfield>
 539 member in an
 540 <link linkend="insn-data-structure">instruction data structure</link>
 541 indicates that the instruction will
 542 <emphasis>not perform acquisition</emphasis> on a
 543 channel, but will <emphasis>configure</emphasis> that channel.
 544 The
 545 <structfield><link linkend="ref-macro-CR-PACK">chanspec</link></structfield>
 546 member in the
 547 <type><link linkend="insn-data-structure-chanspec">comedi_insn</link></type>
 548 data structure, contains the channel to be configured.
 549 The zeroth element of the data array
 550 is always an id that specifies
 551 what type of configuration instruction is being performed.  The
 552 meaning of rest of the elements in the data array
 553 depend on the configuration instruction id.
 554 Some of the
 555 possible ids are summarised in the table below, along with the
 556 meanings of the data array elements for
 557 each type of configuration instruction.
 558 </para>
 559
 560 <informaltable>
 561 <tgroup cols='4' align='left'>
 562 <colspec colwidth='4*' />
 563 <colspec colwidth='4*' />
 564 <colspec colwidth='1*' />
 565 <colspec colwidth='4*' />
 566 <thead>
 567 <row>
 568 <entry>data[0]</entry>
 569 <entry>Description</entry>
 570 <entry>n (number of elements in data array)</entry>
 571 <entry>Meanings of data[1], ..., data[n-1]</entry>
 572 </row>
 573 </thead>
 574 <tbody>
 575 <row>
 576 <entry><constant>INSN_CONFIG_DIO_INPUT</constant></entry>
 577 <entry>
 578 Configure a DIO line as input.  It is easier to use
 579 <function><link linkend="func-ref-comedi-dio-config">comedi_dio_config</link></function>
 580 than to use this configuration instruction directly.
 581 </entry>
 582 <entry>1</entry>
 583 <entry>
 584 n/a
 585 </entry>
 586 </row>
 587 <row>
 588 <entry><constant>INSN_CONFIG_DIO_OUTPUT</constant></entry>
 589 <entry>
 590 Configure a DIO line as output.  It is easier to use
 591 <function><link linkend="func-ref-comedi-dio-config">comedi_dio_config</link></function>
 592 than to use this configuration instruction directly.
 593 </entry>
 594 <entry>1</entry>
 595 <entry>
 596 n/a
 597 </entry>
 598 </row>
 599 <row>
 600 <entry><constant>INSN_CONFIG_ALT_SOURCE</constant></entry>
 601 <entry>
 602 Select an alternate input source.  This instruction is used by calibration
 603 programs to configure analog input channels
 604 which can be redirected to read internal calibration
 605 references.  You need to set the <constant>CR_ALT_SOURCE</constant> flag in the chanspec
 606 when reading to actually read from the configured alternate input source.
 607 If you are using <function>comedi_data_read</function>, then the channel parameter can be
 608 bitwise or'd with the <constant>CR_ALT_SOURCE</constant> flag.
 609 </entry>
 610 <entry>2</entry>
 611 <entry>
 612 data[1]: alternate input source.
 613 </entry>
 614 </row>
 615 <row>
 616 <entry><constant>INSN_CONFIG_BLOCK_SIZE</constant></entry>
 617 <entry>
 618 Specify block size for asynchonous command data.
 619 When performing streaming input, many boards accumulate
 620 samples in internal fifos and transfer them to the host
 621 computer in chunks.  Some drivers let you suggest a size in bytes for how big a
 622 the chunks should be.  This lets you tune how often the host computer is
 623 interrupted with a new chunk of data.
 624 </entry>
 625 <entry>2</entry>
 626 <entry>
 627 data[1]: The desired block size in bytes.  The actual configured block size is
 628 writen back to data[1] after the instruction completes.  This instruction
 629 acts purely as a query if the block size is set to zero.
 630 </entry>
 631 </row>
 632 <row>
 633 <entry><constant>INSN_CONFIG_DIO_QUERY</constant></entry>
 634 <entry>
 635 Queries the configuration of a DIO line to see if it is an input or output.
 636 It is probably easier to use the comedilib function
 637 <function><link linkend="func-ref-comedi-dio-get-config">comedi_dio_get_config</link></function>
 638 than to use this instruction directly.
 639 </entry>
 640 <entry>2</entry>
 641 <entry>
 642 data[1]: The instruction sets this element to either
 643 <constant>COMEDI_INPUT</constant> or <constant>COMEDI_OUTPUT</constant>.
 644 </entry>
 645 </row>
 646 </tbody>
 647 </tgroup>
 648 </informaltable>
 649
 650 <para>
 651 See the comedilib demo program <filename>demo/choose_clock.c</filename> for an example
 652 of using a configuration instruction.
 653 </para>
 654
 655 </section>
 656
 657
 658 <section id="inttrigconfiguration">
 659 <title>
 660 Instruction for internal triggering
 661 </title>
 662 <para>
 663 This special instruction has
 664 <anchor id="insn-inttrig"/><constant>INSN_INTTRIG</constant> as the
 665 <structfield><link linkend="insn-data-structure-insn">insn</link></structfield>
 666 member in its
 667 <link linkend="insn-data-structure">instruction data structure</link>.
 668 Its execution causes an
 669 <link linkend="trig-int-start-src">internal triggering event</link>. This
 670 event can, for example, cause the device driver to start a conversion,
 671 or to stop an ongoing acquisition. The exact meaning of the triggering
 672 depends on the card and its particular driver.
 673 </para>
 674 <para>
 675 The
 676 <structfield><link linkend="insn-data-structure-data">data</link></structfield>[0] element of the
 677 <constant>INSN_INTTRIG</constant> instruction is reserved for future use,
 678 and should be set to <literal>0</literal>.
 679 </para>
 680
 681 </section>
 682
 683
 684 <section id="commandsstreaming">
 685 <title>
 686 Commands for streaming acquisition
 687 </title>
 688
 689 <para>
 690 The most powerful &comedi; acquisition primitive is the
 691 <emphasis>command</emphasis>. It's powerful because, with one single
 692 command, the programmer launches:
 693 <itemizedlist>
 694
 695 <listitem>
 696 <para>
 697 a possibly infinite <emphasis>sequence of acquisitions</emphasis>,
 698 </para>
 699 </listitem>
 700
 701 <listitem>
 702 <para>
 703 accompanied with various <emphasis>callback</emphasis> functionalities
 704 (DMA, interrupts, driver-specific callback functions),
 705 </para>
 706 </listitem>
 707
 708 <listitem>
 709 <para>
 710 for <emphasis>any number of channels</emphasis>,
 711 </para>
 712 </listitem>
 713
 714 <listitem>
 715 <para>
 716 with an <emphasis>arbitrary order</emphasis> of channels in each scan
 717 (possibly even with repeated channels per scan),
 718 </para>
 719 </listitem>
 720
 721 <listitem>
 722 <para>
 723 and with various scan <emphasis>triggering sources</emphasis>,
 724 external (i.e., hardware pulses) as well as internal (i.e., pulses
 725 generated on the DAQ card itself, or generated by a
 726 <link linkend="inttrigconfiguration">software trigger instruction</link>).
 727 </para>
 728 </listitem>
 729
 730 </itemizedlist>
 731 This command functionality exists in the &comedi; API, because various
 732 data acquisition devices have the capability to perform this kind of
 733 complex acquisition, driven by either on-board or
 734 off-board timers and triggers.
 735 </para>
 736
 737 <para>
 738 A command specifies a particular data
 739 <link linkend="fig-acq-seq">acquisition sequence</link>, which
 740 consists of a number of <emphasis>scans</emphasis>, and each scan is
 741 comprised of a number of <emphasis>conversions</emphasis>, which
 742 usually corresponds to a single A/D or D/A conversion. So, for
 743 example, a scan could consist of sampling channels 1, 2 and 3 of a
 744 particular device, and this scan should be repeated 1000 times, at
 745 intervals of 1 millisecond apart.
 746 </para>
 747 <para>
 748 The command function is complementary to the
 749 <link linkend="instructionsconfiguration">configuration instruction</link>
 750 function: each channel in the command's
 751 <structfield><link linkend="command-data-struct-chanlist">chanlist</link></structfield>
 752 should first be configured by an appropriate instruction.
 753 </para>
 754
 755
 756 <section id="executingcommand">
 757 <title>
 758 Executing a command
 759 </title>
 760
 761 <para>
 762 A command is executed by the function
 763 <function><link linkend="func-ref-comedi-command">comedi_command</link></function>:
 764
 765 <funcsynopsis><funcprototype>
 766 <funcdef>int <function>comedi_command</function></funcdef>
 767 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
 768 <paramdef>comedi_cmd *<parameter>command</parameter></paramdef>
 769 </funcprototype></funcsynopsis>
 770
 771 The following sections explain the meaning of the
 772 <type><link linkend="ref-type-comedi-cmd">comedi_cmd</link></type> data structure.
 773 Filling in this structure can be quite complicated, and
 774 requires good knowledge about the exact functionalities of the DAQ
 775 card.  So, before launching a command, the application programmer is
 776 adviced to check whether this complex command data structure can be
 777 successfully parsed. So, the typical sequence for executing a command is
 778 to first send the command through
 779 <function><link linkend="func-ref-comedi-command-test">comedi_command_test</link></function>
 780 once or twice.  The test will check that the command is valid for the
 781 particular device, and often makes some adjustments to the command
 782 arguments, which can then be read back by the user to see the actual
 783 values used.
 784 </para>
 785 <para>
 786 A &comedi; program can find out on-line what the command capabilities
 787 of a specific device are, by means of the
 788 <function><link linkend="func-ref-comedi-get-cmd-src-mask">comedi_get_cmd_src_mask</link></function>
 789 function.
 790 </para>
 791
 792 </section>
 793
 794
 795 <section id="comedicmdstructure">
 796 <title>
 797 The command data structure
 798 </title>
 799 <para>
 800 The command executes according to the information about the requested
 801 acquisition, which is stored in the
 802 <type><link linkend="ref-type-comedi-cmd">comedi_cmd</link></type>
 803 <anchor id="command-data-struct"/>data structure:
 804 <programlisting>
 805 typedef struct comedi_cmd_struct comedi_cmd;
 806
 807 struct comedi_cmd_struct {
 808   unsigned int subdev;         // which subdevice to sample
 809   unsigned int <anchor id="command-data-struct-flags"/>flags;          // encode some configuration possibilities
 810                                // of the command execution; e.g.,
 811                                // whether a callback routine is to be
 812                                // called at the end of the command
 813
 814   unsigned int <anchor id="command-data-struct-start-src"/>start_src;      // event to make the acquisition start
 815   unsigned int <anchor id="command-data-struct-start-arg"/>start_arg;      // parameters that influence this start
 816
 817   unsigned int <anchor id="command-data-struct-scan-begin-src"/>scan_begin_src; // event to make a particular scan start
 818   unsigned int <anchor id="command-data-struct-scan-begin-arg"/>scan_begin_arg; // parameters that influence this start`
 819
 820   unsigned int <anchor id="command-data-struct-convert-src"/>convert_src;    // event to make a particular conversion start
 821   unsigned int <anchor id="command-data-struct-convert-arg"/>convert_arg;    // parameters that influence this start
 822
 823   unsigned int <anchor id="command-data-struct-scan-end-src"/>scan_end_src;   // event to make a particular scan terminate
 824   unsigned int <anchor id="command-data-struct-scan-end-arg"/>scan_end_arg;   // parameters that influence this termination
 825
 826   unsigned int <anchor id="command-data-struct-stop-src"/>stop_src;       // what make the acquisition terminate
 827   unsigned int <anchor id="command-data-struct-stop-arg"/>stop_arg;       // parameters that influence this termination
 828
 829   unsigned int <anchor id="command-data-struct-chanlist"/>*chanlist;      // pointer to list of channels to be sampled
 830   unsigned int <anchor id="command-data-struct-chanlist-len"/>chanlist_len;   // number of channels to be sampled
 831
 832   sampl_t *<anchor id="command-data-struct-data"/>data;               // address of buffer
 833   unsigned int <anchor id="command-data-struct-data-len"/>data_len;       // number of samples to acquire
 834 };
 835 </programlisting>
 836 The start and end of the whole command acquisition sequence, and the
 837 start and end of each scan and of each conversion, is triggered by a
 838 so-called <emphasis>event</emphasis>. More on these in
 839 <xref linkend="comedicmdsources"/>.
 840 </para>
 841
 842 <para>
 843 The <parameter class="function">subdev</parameter> member of the
 844 <type><link linkend="ref-type-comedi-cmd">comedi_cmd</link></type> structure is
 845 the index of the subdevice the command is intended for.  The
 846 <function><link linkend="func-ref-comedi-find-subdevice-by-type">comedi_find_subdevice_by_type</link></function>
 847 function can be useful in discovering the index of your desired subdevice.
 848 </para>
 849
 850 <para>
 851 The <structfield><link linkend="command-data-struct-chanlist">chanlist</link></structfield>
 852 member of the
 853 <type><link linkend="ref-type-comedi-cmd">comedi_cmd</link></type> data
 854 structure should point to an array whose number of elements is
 855 specified by
 856 <structfield><link linkend="command-data-struct-chanlist-len">chanlist_len</link></structfield>
 857 (this will generally be the same as the
 858 <structfield><link linkend="command-data-struct-scan-end-arg">scan_end_arg</link></structfield>).
 859 The
 860 <structfield><link linkend="command-data-struct-chanlist">chanlist</link></structfield>
 861 specifies the sequence of channels and gains (and analog references)
 862 that should be stepped through for each scan.  The elements of the
 863 <structfield><link linkend="command-data-struct-chanlist">chanlist</link></structfield> array should be
 864 initialized by <quote>packing</quote> the channel, range and reference
 865 information together with the
 866 <function><link linkend="ref-macro-CR-PACK">CR_PACK</link></function>
 867 macro.
 868 </para>
 869
 870 <para>
 871 The <structfield><link linkend="command-data-struct-data">data</link></structfield> and
 872 <structfield><link linkend="command-data-struct-data-len">data_len</link></structfield>
 873 members can be safely ignored when issueing commands from a user-space
 874 program.  They only have meaning when a command is sent from a
 875 <emphasis role="strong">kernel</emphasis> module using the
 876 <systemitem>kcomedilib</systemitem> interface, in which case they specify
 877 the buffer where the driver should write/read its data to/from.
 878 </para>
 879
 880 <para>
 881 The final member of the
 882 <type><link linkend="command-data-struct">comedi_cmd</link></type> structure is the
 883 <structfield><link linkend="command-data-struct-flags">flags</link></structfield> field,
 884 i.e., bits in a word that can be bitwise-or'd together. The meaning of
 885 these bits are explained in
 886 <xref linkend="comedicmdflags"/>.
 887 </para>
 888
 889 </section>
 890
 891
 892 <section id="comedicmdsources">
 893 <title>
 894 The command trigger events
 895 <anchor id="source.trigger.anchor"/>
 896 </title>
 897 <para>
 898 A command is a very versatile acquisition instruction, in the sense
 899 that it offers lots of possibilities to let different hardware and
 900 software sources determine when acquisitions are started, performed,
 901 and stopped. More specifically, the command
 902 <link linkend="command-data-struct">data structure</link>
 903 has <emphasis>five</emphasis> types of events: start the
 904 <link linkend="acquisitionterminology">acquisition</link>,
 905 start a <link linkend="scan">scan</link>, start a
 906 <link linkend="conversion">conversion</link>, stop a scan, and stop
 907 the acquisition.  Each event can be given its own
 908 <emphasis><link linkend="source.trigger.anchor">source</link></emphasis>
 909 (the <parameter class="function">&hellip;_src</parameter> members in the
 910 <type><link linkend="ref-type-comedi-cmd">comedi_cmd</link></type> data
 911 structure). And each event source can have a corresponding
 912 argument (the <parameter class="function">&hellip;_arg</parameter> members of
 913 the <type><link linkend="ref-type-comedi-cmd">comedi_cmd</link></type> data
 914 structure) whose meaning depends on the type of source trigger.
 915 For example, to specify an external digital line <quote>3</quote> as a
 916 source (in general, <emphasis>any</emphasis> of the five event
 917 sources), you would use
 918 <parameter>src</parameter>=<constant><link linkend="trig-ext">TRIG_EXT</link></constant>
 919 and <parameter>arg</parameter>=<literal>3</literal>.
 920 </para>
 921 <para>
 922 The following paragraphs discuss in somewhat more detail the trigger
 923 event sources(<parameter class="function">&hellip;_src</parameter>), and the
 924 corresponding arguments (<parameter class="function">&hellip;_arg</parameter>).
 925 </para>
 926 <para>
 927 The start of an acquisition is controlled by the
 928 <structfield><link linkend="command-data-struct-start-src">start_src</link></structfield> events.
 929 The available options are:
 930 <itemizedlist>
 931
 932 <listitem>
 933 <para>
 934 <anchor id="trig-now-start-src"/>
 935 <constant>TRIG_NOW</constant>: the <quote>start</quote> event occurs
 936 <structfield><link linkend="command-data-struct-start-arg">start_arg</link></structfield>
 937 nanoseconds after the command is set up. Currently, only
 938 <structfield><link linkend="command-data-struct-start-arg">start_arg</link></structfield>=<literal>0</literal> is
 939 supported.
 940 </para>
 941 </listitem>
 942
 943 <listitem>
 944 <para>
 945 <anchor id="trig-follow-start-src"/>
 946 <constant>TRIG_FOLLOW</constant>:  (For an output device.) The <quote>start</quote>
 947 event occurs when data is written to the buffer.
 948 </para>
 949 </listitem>
 950
 951 <listitem>
 952 <para>
 953 <anchor id="trig-ext-start-src"/>
 954 <constant>TRIG_EXT</constant>: the <quote>start</quote> event occurs when an
 955 external trigger signal occurs; e.g., a rising edge of a digital line.
 956 <structfield><link linkend="command-data-struct-start-arg">start_arg</link></structfield>
 957 chooses the particular digital line.
 958 </para>
 959 </listitem>
 960
 961 <listitem>
 962 <para>
 963 <anchor id="trig-int-start-src"/>
 964 <constant>TRIG_INT</constant>: the <quote>start</quote> event occurs on a &comedi;
 965 internal signal, which is typically caused by an
 966 <constant><link linkend="insn-inttrig">INSN_INTTRIG</link></constant>
 967 instruction.
 968 </para>
 969 </listitem>
 970
 971 </itemizedlist>
 972 The start of the beginning of each
 973 <link linkend="scan">scan</link> is controlled by the
 974 <structfield><link linkend="command-data-struct-scan-begin-src">scan_begin_src</link></structfield> events.
 975 The available options are:
 976 <itemizedlist>
 977
 978 <listitem>
 979 <para>
 980 <anchor id="trig-timer-start-scan"/>
 981 <constant>TRIG_TIMER</constant>: <quote>scan begin</quote>
 982 events occur periodically.  The time between <quote>scan begin</quote>
 983 events is
 984 <structfield><link linkend="command-data-struct-scan-begin-arg">scan_begin_arg</link></structfield>
 985 nanoseconds.
 986 </para>
 987 </listitem>
 988
 989 <listitem>
 990 <para>
 991 <anchor id="trig-follow-start-scan"/>
 992 <constant>TRIG_FOLLOW</constant>:  The <quote>scan begin</quote>
 993 event occurs immediately after a <quote>scan end</quote>
 994 event occurs.
 995 </para>
 996 </listitem>
 997
 998 <listitem>
 999 <para>
1000 <anchor id="trig-ext-start-scan"/>
1001 <constant>TRIG_EXT</constant>: the <quote>scan begin</quote>
1002 event occurs when an external trigger signal
1003 occurs; e.g., a rising edge of a digital line.
1004 <structfield><link linkend="command-data-struct-scan-begin-arg">scan_begin_arg</link></structfield>
1005 chooses the particular digital line.
1006 </para>
1007 </listitem>
1008
1009 </itemizedlist>
1010 The
1011 <structfield><link linkend="command-data-struct-scan-begin-arg">scan_begin_arg</link></structfield>
1012 used here may not be supported exactly by the device, but it
1013 will be adjusted to the nearest supported value by
1014 <function><link linkend="func-ref-comedi-command-test">comedi_command_test</link></function>.
1015 </para>
1016 <para>
1017 The timing between each sample in a
1018 <link linkend="scan">scan</link> is controlled by the
1019 <structfield><link linkend="command-data-struct-convert-src">convert_src</link></structfield>
1020 events.
1021 The available options are:
1022 <itemizedlist>
1023
1024 <listitem>
1025 <para>
1026 <anchor id="convert-trig-timer"/>
1027 <anchor id="trig-timer"/>
1028 <constant>TRIG_TIMER</constant>: the conversion events occur periodically.
1029 The time between <quote>convert</quote> events is
1030 <structfield><link linkend="command-data-struct-convert-arg">convert_arg</link></structfield>
1031 nanoseconds.
1032 </para>
1033 </listitem>
1034
1035 <listitem>
1036 <para>
1037 <anchor id="convert-trig-ext"/>
1038 <anchor id="trig-ext"/>
1039 <constant>TRIG_EXT</constant>: the conversion events occur when an
1040 external trigger signal occurs, e.g., a rising edge of a digital line.
1041 <structfield><link linkend="command-data-struct-convert-arg">convert_arg</link></structfield>
1042 chooses the particular digital line.
1043 </para>
1044 </listitem>
1045
1046 <listitem>
1047 <para>
1048 <anchor id="convert-trig-now"/>
1049 <anchor id="trig-now"/>
1050 <constant>TRIG_NOW</constant>: All conversion events in a
1051 <link linkend="scan">scan</link> occur simultaneously.
1052 </para>
1053 </listitem>
1054
1055 </itemizedlist>
1056 The <emphasis>end</emphasis> of each scan is almost always specified
1057 by setting the
1058 <structfield><link linkend="command-data-struct-scan-end-src">scan_end_src</link></structfield>
1059 event to
1060 <constant><link linkend="trig-count">TRIG_COUNT</link></constant>,
1061 with the argument being the same as the number of channels in the
1062 <structfield><link linkend="command-data-struct-chanlist">chanlist</link></structfield>.  You
1063 could probably find a device that allows something else, but it would
1064 be strange.
1065 </para>
1066 <para>
1067 The end of an
1068 <link linkend="acquisitionterminology">acquisition</link> is
1069 controlled by
1070 <structfield><link linkend="command-data-struct-stop-src">stop_src</link></structfield> event.
1071 The available options are:
1072 <itemizedlist>
1073
1074 <listitem>
1075 <para>
1076 <anchor id="acquisition-end-trig-count"/>
1077 <anchor id="trig-count"/>
1078 <constant>TRIG_COUNT</constant>: stop the acquisition after
1079 <structfield><link linkend="command-data-struct-stop-arg">stop_arg</link></structfield>
1080 scans.
1081 </para>
1082 </listitem>
1083
1084 <listitem>
1085 <para>
1086 <anchor id="acquisition-end-trig-none"/>
1087 <anchor id="trig-none"/>
1088 <constant>TRIG_NONE</constant>: perform continuous acquisition,
1089 until stopped using
1090 <function><link linkend="func-ref-comedi-cancel">comedi_cancel</link></function>.
1091 </para>
1092 <para>
1093 Its <structfield>stop_arg</structfield> argument is reserved and should be set to <literal>0</literal>.
1094 (<quote>Reserved</quote>
1095 means that unspecified things could happen if it is set to something
1096 else but <literal>0</literal>.)
1097 </para>
1098 </listitem>
1099
1100 </itemizedlist>
1101 There are a couple of less usual or not yet implemented events:
1102 <itemizedlist>
1103
1104 <listitem>
1105 <para>
1106 <anchor id="trig-time"/>
1107 <constant>TRIG_TIME</constant>:
1108 cause an event to occur at a particular time.
1109 </para>
1110 <para>
1111 (This event source is reserved for future use.)
1112 </para>
1113 </listitem>
1114
1115 <listitem>
1116 <para>
1117 <anchor id="trigother-event"/>
1118 <constant>TRIG_OTHER</constant>: driver specific event trigger.
1119 </para>
1120 <para>
1121 This event can be useful as any of the trigger sources.  Its exact
1122 meaning is driver specific, because it implements a feature that
1123 otherwise does not fit into the generic &comedi; command interface.
1124 Configuration of <constant>TRIG_OTHER</constant> features are done by
1125 <constant><link linkend="instructionsconfiguration">INSN_CONFIG</link></constant>
1126 instructions.
1127 </para>
1128 <para>
1129 The argument is reserved and should be set to <literal>0</literal>.
1130 </para>
1131 </listitem>
1132
1133 </itemizedlist>
1134 Not all event sources are applicable to all events.  Supported
1135 trigger sources for specific events depend significantly on your
1136 particular device, and even more on the current state of its device
1137 driver. The
1138 <function><link linkend="func-ref-comedi-get-cmd-src-mask">comedi_get_cmd_src_mask</link></function>
1139 function is useful for determining what trigger sources a subdevice
1140 supports.
1141 </para>
1142
1143 </section>
1144
1145
1146 <section id="comedicmdflags">
1147 <title>
1148 The command flags
1149 <anchor id="source.flags.anchor"/>
1150 </title>
1151
1152 <para>
1153 The
1154 <structfield><link linkend="command-data-struct-flags">flags</link></structfield>
1155 field in the
1156 <link linkend="ref-type-comedi-cmd">command data structure</link>
1157 is used to specify some <quote>behaviour</quote> of the acquisitions in
1158 a command.
1159 The meaning of the field is as follows:
1160 <itemizedlist>
1161
1162 <listitem>
1163 <para>
1164 <anchor id="trig-rt"/>
1165 <constant>TRIG_RT</constant>: ask the driver to use a
1166 <emphasis role="strong">hard real-time</emphasis> interrupt handler.
1167 This will reduce latency in handling interrupts from your data
1168 aquisition
1169 hardware.  It can be useful if you are sampling at high frequency, or
1170 if your hardware has a small onboard data buffer.  You must have a
1171 real-time kernel (<ulink url="http://www.rtai.org">RTAI</ulink> or
1172 <ulink url="http://www.rtlinux-gpl.org/">RTLinux/GPL</ulink>)
1173 and must compile &comedi; with real-time support, or this flag will do
1174 nothing.
1175 </para>
1176 </listitem>
1177
1178 <listitem>
1179 <para>
1180 <anchor id="trig-wake-eos"/>
1181 <constant>TRIG_WAKE_EOS</constant>:
1182 where <quote>EOS</quote> stands for <quote>End of Scan</quote>. Some
1183 drivers will change their behaviour when this flag is set, trying to
1184 transfer data at the end of every scan (instead of, for example,
1185 passing data in chunks whenever the board's hardware data buffer is
1186 half full).  This flag may degrade a driver's performance at high
1187 frequencies, because the end of a scan is, in general, a much more
1188 frequent event than the filling up of the data buffer.
1189 </para>
1190 </listitem>
1191
1192 <listitem>
1193 <para>
1194 <anchor id="trig-round-nearest"/>
1195 <constant>TRIG_ROUND_NEAREST</constant>:
1196 round to nearest supported timing period, the default.
1197 This flag (as well as the following three), indicates how timing
1198 arguments should be rounded if the hardware cannot achieve the exact
1199 timing requested.
1200 </para>
1201 </listitem>
1202
1203 <listitem>
1204 <para>
1205 <anchor id="trig-round-down"/>
1206 <constant>TRIG_ROUND_DOWN</constant>: round period down.
1207 </para>
1208 </listitem>
1209
1210 <listitem>
1211 <para>
1212 <anchor id="trig-round-up"/>
1213 <constant>TRIG_ROUND_UP</constant>: round period up.
1214 </para>
1215 </listitem>
1216
1217 <listitem>
1218 <para>
1219 <anchor id="trig-round-up-next"/>
1220 <constant>TRIG_ROUND_UP_NEXT</constant>:
1221 this one doesn't do anything, and I don't know what it was intended
1222 to do&hellip;?
1223 </para>
1224 </listitem>
1225
1226 <listitem>
1227 <para>
1228 <anchor id="trig-dither"/>
1229 <constant>TRIG_DITHER</constant>: enable dithering? Dithering is
1230 a software technique to smooth the influence of discretization
1231 <quote>noise</quote>.
1232 </para>
1233 </listitem>
1234
1235 <listitem>
1236 <para>
1237 <anchor id="trig-deglitch"/>
1238 <constant>TRIG_DEGLITCH</constant>: enable deglitching?
1239 Another <quote>noise</quote> smoothing technique.
1240 </para>
1241 </listitem>
1242
1243 <listitem>
1244 <para>
1245 <anchor id="trig-write"/>
1246 <constant>TRIG_WRITE</constant>:
1247 write to bidirectional devices.  Could be useful, in principle, if
1248 someone wrote a driver that supported commands for a digital I/O
1249 device that could do either input or output.
1250 </para>
1251 </listitem>
1252
1253 <listitem>
1254 <para>
1255 <anchor id="trig-bogus"/>
1256 <constant>TRIG_BOGUS</constant>: do the motions?
1257 </para>
1258 </listitem>
1259
1260 <listitem>
1261 <para>
1262 <anchor id="trig-other"/>
1263 <constant>TRIG_CONFIG</constant>: perform configuration, not triggering.
1264 This is a legacy of the deprecated
1265 <type><link linkend="ref-type-comedi-trig">comedi_trig_struct</link></type>
1266 data structure, and has no function at present.
1267 </para>
1268 </listitem>
1269
1270 </itemizedlist>
1271 </para>
1272
1273 </section>
1274
1275 <section>
1276 <title>
1277 Anti-aliasing
1278 </title>
1279 <para>
1280 If you wish to aquire accurate waveforms, it is vital that you use an
1281 anti-alias filter.  An anti-alias filter is a low-pass filter used to
1282 remove all    frequencies higher than the Nyquist frequency (half your sampling rate)
1283 from your analog input signal
1284 before you convert it to digital.  If you fail to filter your input signal,
1285 any high frequency components in the original analog signal will create
1286 artifacts in your recorded    digital waveform that cannot be corrected.
1287 </para>
1288 <para>
1289 For example, suppose you are sampling an analog input channel at a rate of
1290 1000 Hz.  If you were to apply a 900 Hz sine wave to the input, you
1291 would find that your
1292 sampling rate is not high enough to faithfully record the 900 Hz input,
1293 since it is above your Nyquist frequency of 500 Hz.  Instead, what you
1294 will see in your recorded digital waveform is a 100 Hz sine wave!  If you
1295 don't use an anti-alias filter, it is impossible to tell whether the 100
1296 Hz sine wave you see in your digital signal was really produced by a
1297 100 Hz input signal, or a 900 Hz signal aliased to 100 Hz, or a 1100 Hz
1298 signal, etc.
1299 </para>
1300 <para>
1301 In practice, the cutoff frequency for the anti-alias filter is usually
1302 set 10% to 20% below the Nyquist frequency due to fact that real filters
1303 do not have infinitely sharp cutoffs.
1304 </para>
1305 </section>
1306 </section>
1307
1308
1309 <section id="slowlyvarying">
1310 <title>
1311 Slowly-varying inputs
1312 </title>
1313
1314 <para>
1315 <emphasis role="strong">Note: The functions described here use an old
1316 feature that is no longer implemented by the &comedi;
1317 kernel layer. THEY WILL NOT WORK!</emphasis>
1318 </para>
1319
1320 <para>
1321 Sometimes, your input channels change slowly enough that
1322 you are able to average many successive input values to get a
1323 more accurate measurement of the actual value.  In general,
1324 the more samples you average, the better your estimate
1325 gets, roughly by a factor of
1326 <function>sqrt<parameter>number_of_samples</parameter></function>.
1327 Obviously, there are limitations to this:
1328 </para>
1329
1330 <itemizedlist>
1331
1332 <listitem>
1333 <para>
1334 you are ultimately limited by <quote>Spurious Free Dynamic
1335 Range</quote>. This SFDR is one of the popular measures to quantify how
1336 much noise a signal carries. If you take a Fourier transform of your
1337 signal, you will see several <quote>peaks</quote> in the transform: one
1338 or more of the fundamental harmonics of the measured signal, and lots
1339 of little <quote>peaks</quote> (called <quote>spurs</quote>) caused by
1340 noise. The SFDR is then the difference between the amplitude of the
1341 fundamental harmonic and of the largest spur (at frequencies below
1342 half of the Nyquist frequency of the DAQ sampler!).
1343 </para>
1344 </listitem>
1345
1346 <listitem>
1347 <para>
1348 you need to have <emphasis>some</emphasis> noise on the input channel,
1349 otherwise you will be averaging the same number <literal>N</literal>
1350 times. (Of course, this only holds if the noise is large enough to
1351 cause at least a one-bit discretization.)
1352 </para>
1353 </listitem>
1354
1355 <listitem>
1356 <para>
1357 the more noise you have, the greater your SFDR, but it
1358 takes many more samples to compensate for the increased
1359 noise.
1360 </para>
1361 </listitem>
1362
1363 <listitem>
1364 <para>
1365 if you feel the need to average samples for, for example, two seconds,
1366 your signal will need to be <emphasis>very</emphasis> slowly-varying,
1367 i.e., not varying more than your target uncertainty for the entire two
1368 seconds.
1369 </para>
1370 </listitem>
1371
1372 </itemizedlist>
1373
1374 <para>
1375 As you might have guessed, the &comedi; library has functions
1376 to help you in your quest to accurately measure slowly varying
1377 inputs:
1378
1379 <funcsynopsis><funcprototype>
1380 <funcdef>int <function>comedi_sv_init</function></funcdef>
1381 <paramdef>comedi_sv_t *<parameter>sv</parameter></paramdef>
1382 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
1383 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
1384 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
1385 </funcprototype></funcsynopsis>
1386
1387 The above function <function><link linkend="func-ref-comedi-sv-init">comedi_sv_init</link></function> initializes the
1388 <type><link linkend="ref-type-comedi-sv-t">comedi_sv_t</link></type> data structure, used
1389 to do the averaging acquisition:
1390 <programlisting>
1391 typedef struct comedi_sv_struct {
1392   <link linkend="ref-type-comedi-t">comedi_t</link> *dev;
1393   unsigned int subdevice;
1394   unsigned int chan;
1395
1396   /* range policy */
1397   int range;
1398   int aref;
1399
1400   /* number of measurements to average (for analog inputs) */
1401   int n;
1402
1403   lsampl_t maxdata;
1404 } comedi_sv_t;
1405 </programlisting>
1406
1407 The actual acquisition is done with the function
1408 <function><link linkend="func-ref-comedi-sv-measure">comedi_sv_measure</link></function>:
1409
1410 <funcsynopsis><funcprototype>
1411 <funcdef>int <function>comedi_sv_measure</function></funcdef>
1412 <paramdef>comedi_sv_t *<parameter>sv</parameter></paramdef>
1413 <paramdef>double *<parameter>data</parameter></paramdef>
1414 </funcprototype></funcsynopsis>
1415
1416 The number of samples over which the function
1417 <function>comedi_sv_measure</function> averages is limited by the
1418 implementation (currently the limit is 100 samples).
1419 </para>
1420
1421 <para>
1422 One typical use for this function is the measurement of thermocouple
1423 voltages.
1424 And the &comedi; self-calibration utility also uses these functions.
1425 On some hardware, it is possible to tell it to measure an
1426 internal stable voltage reference, which is typically going
1427 to be very slowly varying; on the kilosecond time scale
1428 or more.  So, it is reasonable to measure millions of samples,
1429 to get a very accurate measurement of the A/D converter output
1430 value that corresponds to the voltage reference.  Sometimes,
1431 however, this is overkill, since there is no need to
1432 perform a part-per-million calibration to a standard that
1433 is only accurate to a part-per-thousand.
1434 </para>
1435
1436 </section>
1437
1438 <section id="experimentalfunctionality">
1439 <title>
1440 Experimental functionality
1441 </title>
1442
1443 <para>
1444 The following subsections document functionality that has not yet
1445 matured. Most of this functionality has even not been implemented yet
1446 in any single device driver. This information is included here, in
1447 order to stimulate discussion about their API, and to encourage
1448 pioneering implementations.
1449 </para>
1450
1451 <section id="digitalinputcombining">
1452 <title>
1453 Digital input combining machines
1454 </title>
1455
1456 <para>
1457 (<emphasis role="strong">Status: experimental (i.e., no driver implements
1458 this yet)</emphasis>)
1459 </para>
1460 <para>
1461 When one or several digital inputs are used to modify an output
1462 value, either an accumulator or a single digital line or bit,
1463 a bitfield structure is typically used in the &comedi; interface.
1464 The digital inputs have two properties, <quote>sensitive</quote> inputs
1465 and <quote>modifier</quote> inputs.  Edge transitions on sensitive
1466 inputs cause changes in the output signal, whereas modifier inputs
1467 change the effect of edge transitions on sensitive inputs.  Note that
1468 inputs can be both modifier inputs and sensitive inputs.
1469 </para>
1470
1471 <para>
1472 For simplification purposes, it is assumed that multiple digital
1473 inputs do not change simultaneously.
1474 </para>
1475
1476 <para>
1477 The combined state of the modifier inputs determine a modifier
1478 state.  For each combination of modifier state and sensitive
1479 input, there is a set of bits that determine the effect on the
1480 output value due to positive or negative transitions of the
1481 sensitive input.  For each transition direction, there are two
1482 bits defined as follows:
1483
1484 <variablelist spacing="compact">
1485  <varlistentry>
1486   <term>00</term>
1487   <listitem>transition is ignored.</listitem>
1488  </varlistentry>
1489  <varlistentry>
1490   <term>01</term>
1491   <listitem>accumulator is incremented, or output is set.</listitem>
1492  </varlistentry>
1493  <varlistentry>
1494   <term>10</term>
1495   <listitem>accumulator is decremented, or output is cleared.</listitem>
1496  </varlistentry>
1497  <varlistentry>
1498   <term>11</term>
1499   <listitem>reserved.</listitem>
1500  </varlistentry>
1501 </variablelist>
1502
1503 For example, a simple digital follower is specified by the bit
1504 pattern 01 10, because it sets the output on positive transitions
1505 of the input, and clears the output on negative transitions.  A
1506 digital inverter is similarily 10 01.  These systems have only
1507 one sensitive input.
1508 </para>
1509
1510 <para>
1511 As another example, a simple up counter, which increments on
1512 positive transitions of one input, is specified by 01 00.  This
1513 system has only one sensitive input.
1514 </para>
1515
1516 <para>
1517 When multiple digital inputs are used, the inputs are divided
1518 into two types, inputs which cause changes in the accumulator, and
1519 those that only modify the meaning of transitions on other inputs.
1520 Modifier inputs do not require bitfields, but there needs to be
1521 a bitfield of length 4*(2^(N-1)) for each edge sensitive input,
1522 where N is the total number of inputs.  Since N is usually 2 or
1523 3, with only one edge sensitive input, the scaling issues are
1524 not significant.
1525 </para>
1526
1527 </section>
1528
1529
1530 <section id="analogconversion">
1531 <title>
1532 Analog filtering configuration
1533 </title>
1534
1535 <para>
1536 <emphasis role="strong">(Status: design (i.e., no driver implements
1537 this yet).)</emphasis>
1538 </para>
1539
1540 <para>
1541 The <structfield><link linkend="insn-data-structure-insn">insn</link></structfield>
1542 field of the
1543 <link linkend="insn-data-structure">instruction data structure</link>
1544 has not been assigned yet.
1545 </para>
1546 <para>
1547 The <structfield><link linkend="insn-data-structure-chanspec">chanspec</link></structfield> field
1548 of the <link linkend="insn-data-structure">instruction data
1549 structure</link> is ignored.
1550 </para>
1551
1552 <para>
1553 Some devices have the capability to add white noise (dithering) to
1554 analog input measurement.  This additional noise can then be averaged
1555 out, to get a more accurate measurement of the input signal.  It
1556 should not be assumed that channels can be separately configured.
1557 A simple design can use 1 bit to turn this feature on/off.
1558 </para>
1559
1560 <para>
1561 Some devices have the capability of changing the glitch characteristics
1562 of analog output subsytems.  The default (off) case should be where
1563 the average settling time is lowest.  A simple design can use 1 bit
1564 to turn this feature on/off.
1565 </para>
1566
1567 <para>
1568 Some devices have a configurable analog filters as part of the analog
1569 input stage.  A simple design can use 1 bit to enable/disable the
1570 filter.  Default is disabled, i.e., the filter being bypassed, or if
1571 the choice is between two filters, the filter with the largest
1572 bandwidth.
1573 </para>
1574 </section>
1575
1576 <section id="waveformgeneration">
1577 <title>
1578 Analog Output Waveform Generation
1579 </title>
1580
1581 <para>
1582 <emphasis role="strong">(Status: design (i.e., no driver implements
1583 this yet).)</emphasis>
1584 </para>
1585 <para>
1586 The <structfield><link linkend="insn-data-structure-insn">insn</link></structfield> field of the
1587 <link linkend="insn-data-structure">instruction data structure</link>
1588 has not been assigned yet.
1589 </para>
1590 <para>
1591 The <structfield><link linkend="insn-data-structure-chanspec">chanspec</link></structfield> field
1592 of the <link linkend="insn-data-structure">instruction data
1593 structure</link> is ignored.
1594 </para>
1595
1596 <para>
1597 Some devices have the ability to cyclicly loop through samples kept in
1598 an on-board analog output FIFO.  This config should allow the user to
1599 enable/disable this mode.
1600 </para>
1601
1602 <para>
1603 This config should allow the user to configure the number of samples
1604 to loop through.  It may be necessary to configure the channels used.
1605 </para>
1606
1607 </section>
1608
1609 <section id="extendedtriggering">
1610 <title>
1611 Extended Triggering
1612 </title>
1613 <para>
1614 <emphasis role="strong">(Status: alpha.)</emphasis>
1615 </para>
1616
1617 <para>
1618 The <structfield><link linkend="insn-data-structure-insn">insn</link></structfield> field of the
1619 <link linkend="insn-data-structure">instruction data structure</link>
1620 has not been assigned yet.
1621 </para>
1622 <para>
1623 The <structfield><link linkend="insn-data-structure-chanspec">chanspec</link></structfield> field
1624 of the <link linkend="insn-data-structure">instruction data
1625 structure</link> is ignored.
1626 </para>
1627
1628 <para>
1629 This section covers common information for all extended
1630 triggering configuration, and doesn't describe a particular
1631 type of extended trigger.
1632 </para>
1633
1634 <para>
1635 Extended triggering is used to configure triggering engines that
1636 do not fit into commands.  In a typical programming sequence, the
1637 application will use
1638 <link linkend="instructionsconfiguration">configuration instructions</link>
1639 to configure an extended trigger, and a
1640 <link linkend="commandsstreaming">command</link>,
1641 specifying
1642 <constant><link linkend="trig-other">TRIG_OTHER</link></constant>
1643 as one of the trigger sources.
1644 </para>
1645
1646 <para>
1647 Extended trigger configuration should be designed in such a way
1648 that the user can probe for valid parameters, similar to how
1649 command testing works.  An extended trigger configuration instruction
1650 should not configure the hardware directly, rather, the configuration
1651 should be saved until the subsequent command is issued.  This
1652 allows more flexibility for future interface changes.
1653 </para>
1654
1655 <para>
1656 It has not been decided whether the configuration stage should return a
1657 token that is then used as the trigger argument in the command.
1658 Using tokens is one method to satisfy the problem that extended
1659 trigger configurations may have subtle compatiblity issues with
1660 other trigger sources/arguments that can only be determined at
1661 command test time.  Passing all stages of a command test should
1662 only be allowed with a properly configured extended trigger.
1663 </para>
1664
1665 <para>
1666 Extended triggers must use
1667 <structfield><link linkend="insn-data-structure-data">data</link></structfield>[1] as flags.  The
1668 upper 16 bits are reserved and used only for flags that are common to
1669 all extended triggers.  The lower 16 bits may be defined by the
1670 particular type of extended trigger.
1671 </para>
1672
1673 <para>
1674 Various types of extended triggers must use
1675 <structfield><link linkend="insn-data-structure-data">data</link></structfield>[1] to know which
1676 event the extended trigger will be assigned to in the command
1677 structure.  The possible values are an OR'd mask of the following:
1678 </para>
1679
1680 <itemizedlist>
1681   <listitem>
1682     <para>
1683 <constant>COMEDI_EV_START</constant>
1684     </para>
1685   </listitem>
1686   <listitem>
1687     <para>
1688 <constant>COMEDI_EV_SCAN_BEGIN</constant>
1689     </para>
1690   </listitem>
1691   <listitem>
1692     <para>
1693 <constant>COMEDI_EV_CONVERT</constant>
1694     </para>
1695   </listitem>
1696   <listitem>
1697     <para>
1698 <constant>COMEDI_EV_SCAN_END</constant>
1699     </para>
1700   </listitem>
1701   <listitem>
1702     <para>
1703 <constant>COMEDI_EV_STOP</constant>
1704     </para>
1705   </listitem>
1706 </itemizedlist>
1707
1708 </section>
1709
1710 <section id="analogtriggering">
1711 <title>
1712 Analog Triggering
1713 </title>
1714 <para>
1715 <emphasis role="strong">
1716 (Status: alpha. The <filename>ni_mio_common.c</filename> driver
1717 implements this feature.)
1718 </emphasis>
1719 </para>
1720
1721 <para>
1722 The <structfield><link linkend="insn-data-structure-insn">insn</link></structfield> field of the
1723 <link linkend="insn-data-structure">instruction data structure</link>
1724 has not been assigned yet.
1725 </para>
1726 <para>
1727 The <structfield><link linkend="insn-data-structure-chanspec">chanspec</link></structfield> field
1728 of the <link linkend="insn-data-structure">instruction data
1729 structure</link> is ignored.
1730 </para>
1731
1732 <para>
1733 The <structfield><link linkend="insn-data-structure-data">data</link></structfield> field
1734 of the <link linkend="insn-data-structure">instruction data
1735 structure</link> is used as follows:
1736 <variablelist spacing="compact">
1737  <varlistentry>
1738   <term>data[1]</term>
1739   <listitem>trigger and combining machine configuration.</listitem>
1740  </varlistentry>
1741  <varlistentry>
1742   <term>data[2]</term>
1743   <listitem>analog triggering signal chanspec.</listitem>
1744  </varlistentry>
1745  <varlistentry>
1746   <term>data[3]</term>
1747   <listitem>primary analog level.</listitem>
1748  </varlistentry>
1749  <varlistentry>
1750   <term>data[4]</term>
1751   <listitem>secondary analog level.</listitem>
1752  </varlistentry>
1753 </variablelist>
1754 </para>
1755 <para>
1756 Analog triggering is described by a digital combining machine that
1757 has two sensitive digital inputs.  The sensitive digital inputs are
1758 generated by configurable analog comparators.  The analog comparators
1759 generate a digital 1 when the analog triggering signal is greater
1760 than the comparator level.  The digital inputs are not modifier
1761 inputs.  Note, however, there is an effective modifier due to the
1762 restriction that the primary analog comparator level must be less
1763 than the secondary analog comparator level.
1764 </para>
1765
1766 <para>
1767 If only one analog comparator signal is used, the combining machine
1768 for the secondary input should be set to ignored, and the secondary
1769 analog level should be set to <literal>0</literal>.
1770 </para>
1771
1772 <para>
1773 The interpretation of the chanspec and voltage levels is device
1774 dependent, but should correspond to similar values of the analog
1775 input subdevice, if possible.
1776 </para>
1777
1778 <para>
1779 Notes:  Reading range information is not addressed.  This makes it
1780 difficult to convert comparator voltages to data values.
1781 </para>
1782
1783 <para>
1784 Possible extensions: A parameter that specifies the necessary time
1785 that the set condition has to be true before the trigger is generated.
1786 A parameter that specifies the necessary time that the reset condition
1787 has to be true before the state machine is reset.
1788 </para>
1789
1790 </section>
1791
1792 <section id="bitfieldmatching">
1793 <title>
1794 Bitfield Pattern Matching Extended Trigger
1795 </title>
1796 <para>
1797 <emphasis role="strong">
1798 (Status: design. No driver implements this feature yet.)
1799 </emphasis>
1800 </para>
1801
1802 <para>
1803 The <structfield><link linkend="insn-data-structure-insn">insn</link></structfield> field of the
1804 <link linkend="insn-data-structure">instruction data structure</link>
1805 has not been assigned yet.
1806 </para>
1807 <para>
1808 The <structfield><link linkend="insn-data-structure-chanspec">chanspec</link></structfield> field
1809 of the <link linkend="insn-data-structure">instruction data
1810 structure</link> is ignored.
1811 </para>
1812
1813 <para>
1814 The <structfield><link linkend="insn-data-structure-data">data</link></structfield> field
1815 of the <link linkend="insn-data-structure">instruction data
1816 structure</link> is used as follows:
1817 </para>
1818 <variablelist spacing="compact">
1819  <varlistentry>
1820   <term>data[1]</term>
1821   <listitem>trigger flags.</listitem>
1822  </varlistentry>
1823  <varlistentry>
1824   <term>data[2]</term>
1825   <listitem>mask.</listitem>
1826  </varlistentry>
1827  <varlistentry>
1828   <term>data[3]</term>
1829   <listitem>pattern.</listitem>
1830  </varlistentry>
1831 </variablelist>
1832
1833 <para>
1834 The pattern matching trigger issues a trigger when all of a specifed
1835 set of input lines match a specified pattern.  If the device allows,
1836 the input lines should correspond to the input lines of a digital input
1837 subdevice, however, this will necessarily be device dependent.  Each
1838 possible digital line that can be matched is assigned a bit in the
1839 mask and pattern.  A bit set in the mask indicates that the
1840 input line must match the corresponding bit in the pattern.
1841 A bit cleared in the mask indicates that the input line is ignored.
1842 </para>
1843
1844 <para>
1845 Notes: This only allows 32 bits in the pattern/mask, which may be
1846 too few.  Devices may support selecting different sets of lines from
1847 which to match a pattern.
1848 </para>
1849
1850 <para>
1851 Discovery: The number of bits can be discovered by setting the mask
1852 to all 1's.  The driver must modify this value and return
1853 <constant>-EAGAIN</constant>.
1854 </para>
1855
1856 </section>
1857
1858 <section id="countertimer">
1859 <title>
1860 Counter configuration
1861 </title>
1862 <para>
1863 <emphasis role="strong">
1864 (Status: design. No driver implements this feature yet.)
1865 </emphasis>
1866 </para>
1867
1868 <para>
1869 The <structfield><link linkend="insn-data-structure-insn">insn</link></structfield> field of the
1870 <link linkend="insn-data-structure">instruction data structure</link>
1871 has not been assigned yet.
1872 </para>
1873 <para>
1874 The <structfield><link linkend="insn-data-structure-chanspec">chanspec</link></structfield> field
1875 of the <link linkend="insn-data-structure">instruction data
1876 structure</link> is used to specify which counter to use. (I.e., the
1877 counter is a &comedi; channel.)
1878 </para>
1879
1880 <para>
1881 The <structfield><link linkend="insn-data-structure-data">data</link></structfield> field
1882 of the <link linkend="insn-data-structure">instruction data
1883 structure</link> is used as follows:
1884 </para>
1885 <variablelist spacing="compact">
1886  <varlistentry>
1887   <term>data[1]</term>
1888   <listitem>trigger configuration.</listitem>
1889  </varlistentry>
1890  <varlistentry>
1891   <term>data[2]</term>
1892   <listitem>primary input chanspec.</listitem>
1893  </varlistentry>
1894  <varlistentry>
1895   <term>data[3]</term>
1896   <listitem>primary combining machine configuration.</listitem>
1897  </varlistentry>
1898  <varlistentry>
1899   <term>data[4]</term>
1900   <listitem>secondary input chanspec.</listitem>
1901  </varlistentry>
1902  <varlistentry>
1903   <term>data[5]</term>
1904  <listitem>secondary combining machine configuration.</listitem>
1905  </varlistentry>
1906  <varlistentry>
1907   <term>data[6]</term>
1908   <listitem>latch configuration.</listitem>
1909  </varlistentry>
1910 </variablelist>
1911
1912 <para>
1913 Note that this configuration is only useful if the counting has to be
1914 done in <emphasis>software</emphasis>. Many cards offer configurable
1915 counters in hardware; e.g., general purpose timer cards can be
1916 configured to act as pulse generators, frequency counters, timers,
1917 encoders, etc.
1918 </para>
1919 <para>
1920 Counters can be operated either in synchronous mode (using
1921 <constant><link linkend="insn-read">INSN_READ</link></constant>)
1922 or asynchronous mode (using
1923 <link linkend="commandsstreaming">commands</link>), similar to analog
1924 input subdevices.
1925 The input signal for both modes is the accumulator.
1926 Commands on counter subdevices are almost always specified using
1927 <structfield><link linkend="command-data-struct-scan-begin-src">scan_begin_src</link></structfield>
1928 = <constant><link linkend="trigother-event">TRIG_OTHER</link></constant>,
1929 with the counter configuration also serving as the extended configuration for
1930 the <quote>scan begin</quote> source.
1931 </para>
1932
1933 <para>
1934 Counters are made up of an accumulator and a combining machine that
1935 determines when the accumulator should be incremented or decremented
1936 based on the values of the input signals.  The combining machine
1937 optionally determines when the accumulator should be latched and
1938 put into a buffer.  This feature is used in asynchronous mode.
1939 </para>
1940
1941 <para>
1942 Note: How to access multiple pieces of data acquired at each event?
1943 </para>
1944
1945 </section>
1946
1947 <section id="auxcounter">
1948 <title>
1949 One source plus auxiliary counter configuration
1950 </title>
1951 <para>
1952 <emphasis role="strong">
1953 (Status: design. No driver implements this feature yet.)
1954 </emphasis>
1955 </para>
1956
1957 <para>
1958 The <structfield><link linkend="insn-data-structure-insn">insn</link></structfield> field of the
1959 <link linkend="insn-data-structure">instruction data structure</link>
1960 has not been assigned yet.
1961 </para>
1962 <para>
1963 The <structfield><link linkend="insn-data-structure-chanspec">chanspec</link></structfield> field
1964 of the <link linkend="insn-data-structure">instruction data
1965 structure</link> is used to &hellip;
1966 </para>
1967
1968 <para>
1969 The <structfield><link linkend="insn-data-structure-data">data</link></structfield> field
1970 of the <link linkend="insn-data-structure">instruction data
1971 structure</link> is used as follows:
1972 </para>
1973
1974 <para>
1975 <variablelist spacing="compact">
1976  <varlistentry>
1977   <term>data[1]</term>
1978   <listitem>
1979 is flags, including the flags for the command triggering
1980 configuration.  If a command is not subsequently issued on the
1981 subdevice, the command triggering portion of the flags are ignored.
1982   </listitem>
1983  </varlistentry>
1984  <varlistentry>
1985   <term>data[2]</term>
1986   <listitem>
1987 determines the mode of operation.  The mode of operation
1988 is actually a bitfield that encodes what to do for various
1989 transitions of the source signals.
1990   </listitem>
1991  </varlistentry>
1992  <varlistentry>
1993   <term>data[3]</term>
1994   <term>data[4]</term>
1995   <listitem>
1996 determine the primary source for the counter, similar to the
1997 <structfield><link linkend="command-data-struct-scan-begin-src">&hellip;_src</link></structfield> and the
1998 <structfield><link linkend="command-data-struct-scan-begin-arg">&hellip;_arg</link></structfield> fields
1999 used in the
2000 <link linkend="command-data-struct">command data structure</link>.
2001   </listitem>
2002  </varlistentry>
2003 </variablelist>
2004 </para>
2005
2006 <para>
2007 Notes: How to specify which events cause a latch and push, and what
2008 should get latched?
2009 </para>
2010
2011 </section>
2012
2013 <section id="RTSI">
2014 <title>
2015 National instruments RTSI trigger bus
2016 </title>
2017 <para>
2018 A number of NI boards support the RTSI (Real Time System Integration) bus.
2019 It's primary use is to synchronize multiple DAQ cards.
2020 On PXI boards, the RTSI lines correspond to the PXI trigger lines 0 to 7.  PCI
2021 boards use cables to connect to their RTSI ports.
2022 The RTSI bus consists of 8 digital signal lines numbered 0 to 7 that are bi-directional.
2023 Each of these signal lines
2024 can be configured as an input or output, and the signal appearing on the output
2025 of each line can be configured to one of several internal board timing signals
2026 (although on older boards RTSI line 7 can only be used for the clock signal).
2027 The <systemitem>ni_pcimio</systemitem>, <systemitem>ni_atmio</systemitem>, and
2028 <systemitem>ni_mio_cs</systemitem> drivers expose the RTSI bus
2029 as a digital I/O subdevice (subdevice number 10).
2030 </para>
2031 <para>
2032 The functions <function>comedi_dio_config</function> and
2033 <function>comedi_dio_get_config</function> can be used on
2034 the RTSI subdevice to
2035 set/query the direction (input or output) of each of the RTSI lines individually.
2036 </para>
2037 <para>
2038 The subdevice also supports the
2039 <constant>INSN_CONFIG_SET_CLOCK_SRC</constant> and
2040 <constant>INSN_CONFIG_GET_CLOCK_SRC</constant> configuration
2041 instructions, which can be
2042 used to configure/query what source the board uses to synchronize its
2043 master clock to.  The various possibilities are defined in the <filename>comedi.h</filename>
2044 header file:
2045 </para>
2046 <informaltable>
2047 <tgroup cols='2' align='left'>
2048 <thead>
2049 <row>
2050 <entry>Clock Source</entry>
2051 <entry>Description</entry>
2052 </row>
2053 </thead>
2054 <tbody>
2055 <row>
2056 <entry><constant>NI_MIO_INTERNAL_CLOCK</constant></entry>
2057 <entry>
2058 Use the board's internal oscillator.
2059 </entry>
2060 </row>
2061 <row>
2062 <entry><constant>NI_MIO_RTSI_CLOCK</constant></entry>
2063 <entry>
2064 Use the RTSI line 7 as the master clock.  This source is
2065 only supported on pre-m-series boards.  The newer m-series boards
2066 use <function>NI_MIO_PLL_RTSI_CLOCK</function> instead.
2067 </entry>
2068 </row>
2069 <row>
2070 <entry><constant>NI_MIO_PLL_PXI_STAR_TRIGGER_CLOCK</constant></entry>
2071 <entry>
2072 Only available for newer m-series PXI boards.  Synchronizes the board's
2073 phased-locked loop (which runs at 80MHz) to the PXI star trigger
2074 line.
2075 </entry>
2076 </row>
2077 <row>
2078 <entry><constant>NI_MIO_PLL_PXI10_CLOCK</constant></entry>
2079 <entry>
2080 Only available for newer m-series PXI boards.
2081 Synchronizes the board's
2082 phased-locked loop (which runs at 80MHz) to the 10 MHz PXI backplane
2083 clock.
2084 </entry>
2085 </row>
2086 <row>
2087 <entry>
2088 <function>NI_MIO_PLL_RTSI_CLOCK<parameter>n</parameter></function>
2089 </entry>
2090 <entry>
2091 Only available for newer m-series boards.
2092 The function returns a clock source which will cause the board's
2093 phased-locked loop (which runs at 80MHz) to syncronize to the RTSI
2094 line specified in the function argument.
2095 </entry>
2096 </row>
2097 </tbody>
2098 </tgroup>
2099 </informaltable>
2100
2101 <para>
2102 For all clock sources except <constant>NI_MIO_INTERNAL_CLOCK</constant>
2103 and <constant>NI_MIO_PLL_PXI10_CLOCK</constant>,
2104 you should pass the period of the clock your are feeding to the board when
2105 using <constant>INSN_CONFIG_SET_CLOCK_SRC</constant>.
2106 </para>
2107 <para>
2108 Finally, the configuration instructions
2109 <constant>INSN_CONFIG_SET_ROUTING</constant> and
2110 <constant>INSN_CONFIG_GET_ROUTING</constant>
2111 can be used to select/query which internal signal
2112 will appear on a given RTSI output line.  The header file <filename>comedi.h</filename> defines
2113 the following signal sources which can be routed to an RTSI line:
2114 </para>
2115
2116 <informaltable>
2117 <tgroup cols='2' align='left'>
2118 <thead>
2119 <row>
2120 <entry>Signal Source</entry>
2121 <entry>Description</entry>
2122 </row>
2123 </thead>
2124 <tbody>
2125 <row>
2126 <entry><constant>NI_RTSI_OUTPUT_ADR_START1</constant></entry>
2127 <entry>
2128 ADR_START1, an analog input start signal.  See the NI's
2129 DAQ-STC Technical Reference Manual for more information.
2130 </entry>
2131 </row>
2132 <row>
2133 <entry><constant>NI_RTSI_OUTPUT_ADR_START2</constant></entry>
2134 <entry>
2135 ADR_START2, an analog input stop signal.  See the NI's
2136 DAQ-STC Technical Reference Manual for more information.
2137 </entry>
2138 </row>
2139 <row>
2140 <entry><constant>NI_RTSI_OUTPUT_SCLKG</constant></entry>
2141 <entry>
2142 SCLKG, a sample clock signal.  See the NI's
2143 DAQ-STC Technical Reference Manual for more information.
2144 </entry>
2145 </row>
2146 <row>
2147 <entry><constant>NI_RTSI_OUTPUT_DACUPDN</constant></entry>
2148 <entry>
2149 DACUPDN, a dac update signal.  See the NI's
2150 DAQ-STC Technical Reference Manual for more information.
2151 </entry>
2152 </row>
2153 <row>
2154 <entry><constant>NI_RTSI_OUTPUT_DA_START1</constant></entry>
2155 <entry>
2156 DA_START1, an analog output start signal.  See the NI's
2157 DAQ-STC Technical Reference Manual for more information.
2158 </entry>
2159 </row>
2160 <row>
2161 <entry><constant>NI_RTSI_OUTPUT_G_SRC0</constant></entry>
2162 <entry>
2163 G_SRC0, the source signal to general purpose counter 0.  See the NI's
2164 DAQ-STC Technical Reference Manual for more information.
2165 </entry>
2166 </row>
2167 <row>
2168 <entry><constant>NI_RTSI_OUTPUT_G_GATE0</constant></entry>
2169 <entry>
2170 G_GATE0, the gate signal to general purpose counter 0.  See the NI's
2171 DAQ-STC Technical Reference Manual for more information.
2172 </entry>
2173 </row>
2174 <row>
2175 <entry><constant>NI_RTSI_OUTPUT_RGOUT0</constant></entry>
2176 <entry>
2177 RGOUT0, the output signal of general purpose counter 0.  See the NI's
2178 DAQ-STC Technical Reference Manual for more information.
2179 </entry>
2180 </row>
2181 <row>
2182 <entry>
2183 <function>NI_RTSI_OUTPUT_RTSI_BRD<parameter>n</parameter></function>
2184 </entry>
2185 <entry>
2186 RTSI_BRD0 though RTSI_BRD3 are four internal signals which can
2187 have various other signals routed to them in turn.  Currently, comedi
2188 provides no way to configure the signals routed to the RTSI_BRD lines.
2189 See the NI's DAQ-STC Technical Reference Manual for more information.
2190 </entry>
2191 </row>
2192 <row>
2193 <entry><constant>NI_RTSI_OUTPUT_RTSI_OSC</constant></entry>
2194 <entry>
2195 The RTSI clock signal.  On pre-m-series boards, this signal is always
2196 routed to RTSI line 7, and cannot be routed to lines 0 through 6.  On
2197 m-series boards, any RTSI line can be configured to output the clock
2198 signal.
2199 </entry>
2200 </row>
2201 </tbody>
2202 </tgroup>
2203 </informaltable>
2204
2205 <para>
2206 The RTSI bus pins may be used as trigger inputs for many of the
2207 &comedi; trigger functions. To use the RTSI bus pins, set the source to be
2208 <constant>TRIG_EXT</constant> and the source argument using the return values
2209 from the <function>NI_EXT_RTSI<parameter>n</parameter></function> function (or similarly the
2210 <function>NI_EXT_PFI<parameter>n</parameter></function> function if you want
2211 to trigger from a PFI line).  The <constant>CR_EDGE</constant> and
2212 <constant>CR_INVERT</constant> flags may
2213 also be set on the trigger source argument to specify edge and
2214 falling edge/low level triggering.
2215
2216 </para>
2217 <para>
2218 An example to set up a device as a master is given below.
2219 </para>
2220
2221 <programlisting><![CDATA[
2222 void comediEnableMaster(comedi_t *dev){
2223         comedi_insn   configCmd;
2224         lsampl_t      configData[2];
2225         int           ret;
2226         unsigned int  d = 0;
2227         static const unsigned rtsi_subdev = 10;
2228         static const unsigned rtsi_clock_line = 7;
2229
2230         /* Route RTSI clock to line 7 (not needed on pre-m-series boards since their
2231            clock is always on line 7). */
2232         memset(&configCmd, 0, sizeof(configCmd));
2233         memset(&configData, 0, sizeof(configData));
2234         configCmd.insn = INSN_CONFIG;
2235         configCmd.subdev = rtsi_subdev;
2236         configCmd.chanspec = rtsi_clock_line;
2237         configCmd.n = 2;
2238         configCmd.data = configData;
2239         configCmd.data[0] = INSN_CONFIG_SET_ROUTING;
2240         configCmd.data[1] = NI_RTSI_OUTPUT_RTSI_OSC;
2241         ret = comedi_do_insn(dev, &configCmd);
2242         if(ret < 0){
2243                 comedi_perror("comedi_do_insn: INSN_CONFIG");
2244                 exit(1);
2245         }
2246         // Set clock RTSI line as output
2247         ret = comedi_dio_config(dev, rtsi_subdev, rtsi_clock_line, INSN_CONFIG_DIO_OUTPUT);
2248         if(ret < 0){
2249                 comedi_perror("comedi_dio_config");
2250                 exit(1);
2251         }
2252
2253         /* Set routing of the 3 main AI RTSI signals and their direction to output.
2254            We're reusing the already initialized configCmd instruction here since
2255            it's mostly the same. */
2256         configCmd.chanspec = 0;
2257         configCmd.data[1] =  NI_RTSI_OUTPUT_ADR_START1;
2258         ret = comedi_do_insn(dev, &configCmd);
2259         if(ret < 0){
2260                 comedi_perror("comedi_do_insn: INSN_CONFIG");
2261                 exit(1);
2262         }
2263         ret = comedi_dio_config(dev, rtsi_subdev, 0, INSN_CONFIG_DIO_OUTPUT);
2264         if(ret < 0){
2265                 comedi_perror("comedi_dio_config");
2266                 exit(1);
2267         }
2268
2269         configCmd.chanspec = 1;
2270         configCmd.data[1] =  NI_RTSI_OUTPUT_ADR_START2;
2271         ret = comedi_do_insn(dev, &configCmd);
2272         if(ret < 0){
2273                 comedi_perror("comedi_do_insn: INSN_CONFIG");
2274                 exit(1);
2275         }
2276         ret = comedi_dio_config(dev, rtsi_subdev, 1, INSN_CONFIG_DIO_OUTPUT);
2277         if(ret < 0){
2278                 comedi_perror("comedi_dio_config");
2279                 exit(1);
2280         }
2281
2282         configCmd.chanspec = 2;
2283         configCmd.data[1] =  NI_RTSI_OUTPUT_SCLKG;
2284         ret = comedi_do_insn(dev, &configCmd);
2285         if(ret < 0){
2286                 comedi_perror("comedi_do_insn: INSN_CONFIG");
2287                 exit(1);
2288         }
2289         ret = comedi_dio_config(dev, rtsi_subdev, 2, INSN_CONFIG_DIO_OUTPUT);
2290         if(ret < 0){
2291                 comedi_perror("comedi_dio_config");
2292                 exit(1);
2293         }
2294 }
2295 ]]></programlisting>
2296
2297 <para>
2298 An example to slave a m-series device from this master follows.  A pre-m-series
2299 device would need to use <constant>NI_MIO_RTSI_CLOCK</constant> for
2300 the clock source instead.  In
2301 your code, you may also wish to configure the master device to use the
2302 external clock source instead of using its internal clock directly (for
2303 best syncronization).
2304 </para>
2305 <programlisting><![CDATA[
2306 void comediEnableSlave(comedi_t *dev){
2307         comedi_insn   configCmd;
2308         lsampl_t      configData[3];
2309         int           ret;
2310         unsigned int  d = 0;;
2311         static const unsigned rtsi_subdev = 10;
2312         static const unsigned rtsi_clock_line = 7;
2313
2314         memset(&configCmd, 0, sizeof(configCmd));
2315         memset(&configData, 0, sizeof(configData));
2316         configCmd.insn = INSN_CONFIG;
2317         configCmd.subdev = rtsi_subdev;
2318         configCmd.chanspec = 0;
2319         configCmd.n = 3;
2320         configCmd.data = configData;
2321         configCmd.data[0] = INSN_CONFIG_SET_CLOCK_SRC;
2322         configCmd.data[1] = NI_MIO_PLL_RTSI_CLOCK(rtsi_clock_line);
2323         configCmd.data[2] = 100;        /* need to give it correct external clock period */
2324         ret = comedi_do_insn(dev, &configCmd);
2325         if(ret < 0){
2326                 comedi_perror("comedi_do_insn: INSN_CONFIG");
2327                 exit(1);
2328         }
2329         /* configure RTSI clock line as input */
2330         ret = comedi_dio_config(dev, rtsi_subdev, rtsi_clock_line, INSN_CONFIG_DIO_INPUT);
2331         if(ret < 0){
2332                 comedi_perror("comedi_dio_config");
2333                 exit(1);
2334         }
2335         /* Configure RTSI lines we are using for AI signals as inputs. */
2336         ret = comedi_dio_config(dev, rtsi_subdev, 0, INSN_CONFIG_DIO_INPUT);
2337         if(ret < 0){
2338                 comedi_perror("comedi_dio_config");
2339                 exit(1);
2340         }
2341         ret = comedi_dio_config(dev, rtsi_subdev, 1, INSN_CONFIG_DIO_INPUT);
2342         if(ret < 0){
2343                 comedi_perror("comedi_dio_config");
2344                 exit(1);
2345         }
2346         ret = comedi_dio_config(dev, rtsi_subdev, 2, INSN_CONFIG_DIO_INPUT);
2347         if(ret < 0){
2348                 comedi_perror("comedi_dio_config");
2349                 exit(1);
2350         }
2351 }
2352
2353 int comediSlaveStart(comedi_t *dev){
2354         comedi_cmd     cmd;
2355         unsigned int   nChannels = 8;
2356         double         sampleRate = 50000;
2357         unsigned int   chanList[8];
2358         int            i;
2359
2360         // Setup chan list
2361         for(i = 0; i < nChannels; i++){
2362                 chanList[i] = CR_PACK(i, 0, AREF_GROUND);
2363         }
2364         // Set up command
2365         memset(&cmd, 0, sizeof(cmd));
2366         ret = comedi_get_cmd_generic_timed(dev, subdevice, &cmd,
2367                 (int)(1e9/(nChannels * sampleRate)));
2368         if(ret<0){
2369                 printf("comedi_get_cmd_generic_timed failed\n");
2370                 return ret;
2371         }
2372         cmd.chanlist        = chanList;
2373         cmd.chanlist_len    = nChannels;
2374         cmd.scan_end_arg    = nChannels;
2375         cmd.start_src        = TRIG_EXT;
2376         cmd.start_arg        = CR_EDGE | NI_EXT_RTSI(0);
2377         cmd.convert_src    = TRIG_EXT;
2378         cmd.convert_arg    = CR_INVERT | CR_EDGE | NI_EXT_RTSI(2);
2379         cmd.stop_src        = TRIG_NONE;
2380
2381         ret = comedi_command(dev0, &cmd0);
2382         if(ret<0){
2383                 printf("comedi_command failed\n");
2384                 return ret;
2385         }
2386         return 0;
2387 }
2388 ]]></programlisting>
2389
2390
2391 </section>
2392
2393 </section>
2394
2395 </section>
2396