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