doc/reference.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="comedireference" xmlns:xi="http://www.w3.org/2001/XInclude">
   9         <title>
  10                 &comedi; reference
  11         </title>
  12
  13 <section id="comedi-comedilib-h">
  14 <title>
  15 Headerfiles: <filename>comedi.h</filename> and <filename>comedilib.h</filename>
  16 </title>
  17
  18 <para>
  19 All <link linkend="writingprograms">application programs</link> must
  20 include the header file <filename>comedilib.h</filename>. (This file
  21 itself includes <filename>comedi.h</filename>.) They contain the full
  22 interface of &comedi;: defines, function prototypes, data structures.
  23 </para>
  24 <para>
  25 The following Sections give more details.
  26 </para>
  27
  28 </section>
  29
  30 <section id="constantsmacros">
  31 <title>
  32 Constants and macros
  33 </title>
  34
  35 <section id="ref-macro-CR-PACK">
  36 <title>
  37 CR_PACK
  38 </title>
  39
  40 <para>
  41 <function>CR_PACK<parameter>chan</parameter><parameter>rng</parameter>
  42 <parameter>aref</parameter></function> is used to initialize the elements of the
  43 <parameter>chanlist</parameter> array in the
  44 <type><link linkend="ref-type-comedi-cmd">comedi_cmd</link></type> data structure,
  45 and the <parameter>chanspec</parameter> member of the
  46 <type><link linkend="ref-type-comedi-insn">comedi_insn</link></type> structure.
  47 </para>
  48 <programlisting>
  49 <![CDATA[
  50 #define CR_PACK(chan,rng,aref)      ( (((aref)&0x3)<<24) | (((rng)&0xff)<<16) | (chan) )
  51 ]]>
  52 </programlisting>
  53 <para>
  54 The <parameter>chan</parameter> argument is the channel you wish to
  55 use, with the channel numbering starting at zero.
  56 </para>
  57
  58 <para>
  59 The range <parameter>rng</parameter> is an index, starting at zero,
  60 whose meaning is device dependent.  The
  61 <function><link linkend="func-ref-comedi-get-n-ranges">comedi_get_n_ranges</link></function>
  62 and
  63 <function><link linkend="func-ref-comedi-get-range">comedi_get_range</link></function>
  64 functions are useful in discovering information about the available
  65 ranges.
  66 </para>
  67
  68 <para>
  69 The <parameter>aref</parameter> argument indicates what reference you
  70 want the device to use.  It can be any of the following:
  71 <variablelist>
  72   <varlistentry>
  73     <term><constant>AREF_GROUND</constant> <anchor id="aref-ground"/> </term>
  74     <listitem>
  75       <para>
  76         is for inputs/outputs referenced to ground.
  77       </para>
  78     </listitem>
  79   </varlistentry>
  80   <varlistentry>
  81     <term><constant>AREF_COMMON</constant> <anchor id="aref-common"/> </term>
  82     <listitem>
  83       <para>
  84          is for a <quote>common</quote> reference (the low inputs of all the
  85 channels are tied together, but are isolated from ground).
  86       </para>
  87     </listitem>
  88   </varlistentry>
  89   <varlistentry>
  90     <term><constant>AREF_DIFF</constant> <anchor id="aref-diff"/> </term>
  91     <listitem>
  92       <para>
  93     is for differential inputs/outputs.
  94       </para>
  95     </listitem>
  96   </varlistentry>
  97   <varlistentry>
  98     <term><constant>AREF_OTHER</constant> <anchor id="aref-other"/> </term>
  99     <listitem>
 100       <para>
 101     is for any reference that does not fit into the above categories.
 102       </para>
 103     </listitem>
 104   </varlistentry>
 105 </variablelist>
 106 Particular drivers may or may not use the AREF flags.  If they are
 107 not supported, they are silently ignored.
 108 </para>
 109 </section>
 110
 111 <section id="ref-macro-RANGE-LENGTH">
 112 <title>
 113 RANGE_LENGTH (deprecated)
 114 </title>
 115
 116 <para>
 117 Rangetype values are library-internal tokens that represent an
 118 array of range information structures.  These numbers are primarily
 119 used for communication between the kernel and library.
 120 </para>
 121
 122 <para>
 123 The <function>RANGE_LENGTH<parameter>rangetype</parameter></function>
 124 macro returns the length of the array that is
 125 specified by the <parameter>rangetype</parameter> token.
 126 </para>
 127
 128 <para>
 129 The <function>RANGE_LENGTH</function> macro is deprecated, and should not be used in
 130 new applications.  It is scheduled to be removed from the header
 131 file at version 1.0.  Binary compatibility may be broken for version
 132 1.1.
 133 </para>
 134 </section>
 135
 136 <section id="ref-enum-comedi-conversion-direction">
 137 <title>
 138 enum comedi_conversion_direction
 139 </title>
 140
 141 <para>
 142 <programlisting>
 143 enum comedi_conversion_direction
 144 {
 145         COMEDI_TO_PHYSICAL,
 146         COMEDI_FROM_PHYSICAL
 147 };
 148 </programlisting>
 149 </para>
 150 <para>
 151 A <type>comedi_conversion_direction</type> is used to choose between converting data
 152 from Comedi's integer sample values to a physical value
 153 (<constant>COMEDI_TO_PHYSICAL</constant>),
 154 and converting from a physical value to Comedi's integer sample values
 155 (<constant>COMEDI_FROM_PHYSICAL</constant>).
 156 </para>
 157
 158 </section>
 159
 160 <section id="ref-enum-comedi-io-direction">
 161 <title>
 162 enum comedi_io_direction
 163 </title>
 164
 165 <para>
 166 <programlisting>
 167 enum comedi_io_direction
 168 {
 169         COMEDI_INPUT,
 170         COMEDI_OUTPUT
 171 };
 172 </programlisting>
 173 </para>
 174 <para>
 175 A <type>comedi_io_direction</type> is used to select between input or output.  For example,
 176 <function><link linkend="func-ref-comedi-dio-config">comedi_dio_config</link></function>
 177 uses the <constant>COMEDI_INPUT</constant> and <constant>COMEDI_OUTPUT</constant> values to specify
 178 whether a configurable digital i/o channel should be configured as an input
 179 or output.
 180 </para>
 181
 182 </section>
 183
 184 <section id="ref-enum-comedi-subdevice-type">
 185 <title>
 186 enum comedi_subdevice_type
 187 </title>
 188
 189 <para>
 190 <programlisting>
 191 enum comedi_subdevice_type {
 192         COMEDI_SUBD_UNUSED,     /* subdevice is unused by driver */
 193         COMEDI_SUBD_AI, /* analog input */
 194         COMEDI_SUBD_AO, /* analog output */
 195         COMEDI_SUBD_DI, /* digital input */
 196         COMEDI_SUBD_DO, /* digital output */
 197         COMEDI_SUBD_DIO,        /* digital input/output */
 198         COMEDI_SUBD_COUNTER,    /* counter */
 199         COMEDI_SUBD_TIMER,      /* timer */
 200         COMEDI_SUBD_MEMORY,     /* memory, EEPROM, DPRAM */
 201         COMEDI_SUBD_CALIB,      /* calibration DACs and pots*/
 202         COMEDI_SUBD_PROC,       /* processor, DSP */
 203         COMEDI_SUBD_SERIAL,     /* serial IO */
 204         COMEDI_SUBD_PWM /* pulse width modulation */
 205 };
 206 </programlisting>
 207 </para>
 208 <para>
 209 The <type>comedi_subdevice_type</type> enumeration specifies the possible values for
 210 a subdevice type.  These values are used by the functions
 211 <function><link linkend="func-ref-comedi-get-subdevice-type">comedi_get_subdevice_type</link></function> and
 212 <function><link linkend="func-ref-comedi-find-subdevice-by-type">comedi_find_subdevice_by_type</link></function>.
 213 </para>
 214
 215 </section>
 216
 217 </section>
 218
 219 <section id="datatypesstructures">
 220 <title>
 221 Data types and structures
 222 </title>
 223 <para>
 224 This Section explains the data structures that users of the &comedi;
 225 API are confronted with:
 226 <programlisting>
 227 typedef struct comedi_devinfo_struct  <link linkend="ref-type-comedi-devinfo">comedi_devinfo</link>;
 228 typedef struct comedi_t_struct        <link linkend="ref-type-comedi-t">comedi_t</link>;
 229 typedef struct sampl_t_struct         <link linkend="ref-type-sampl-t">sampl_t</link>;
 230 typedef struct lsampl_t_struct        <link linkend="ref-type-lsampl-t">lsampl_t</link>;
 231 typedef struct comedi_sv_t_struct     <link linkend="ref-type-comedi-sv-t">comedi_sv_t</link>;
 232 typedef struct comedi_cmd_struct      <link linkend="ref-type-comedi-cmd">comedi_cmd</link>;
 233 typedef struct comedi_insn_struct     <link linkend="ref-type-comedi-insn">comedi_insn</link>;
 234 typedef struct comedi_range_struct    <link linkend="ref-type-comedi-range">comedi_range</link>;
 235 typedef struct comedi_krange_struct   <link linkend="ref-type-comedi-krange">comedi_krange</link>;
 236 typedef struct comedi_insnlist_struct <link linkend="ref-type-comedi-insnlist">comedi_insnlist</link>;
 237 </programlisting>
 238 The data structures used in the implementation of the &comedi; drivers
 239 are treated <link linkend="driverdatastructures">elsewhere</link>.
 240 </para>
 241
 242
 243 <section id="ref-type-comedi-devinfo">
 244 <title>
 245 comedi_devinfo
 246 </title>
 247
 248 <para>
 249 The data type <type>comedi_devinfo</type> is used to store
 250 information about a device. This structure is usually filled in
 251 automatically when the driver is loaded (<quote>attached</quote>), so
 252 programmers need not access this data structure directly.
 253 <programlisting>
 254 typedef struct comedi_devinfo_struct comedi_devinfo;
 255
 256 struct comedi_devinfo_struct{
 257   unsigned int version_code;    // version number of the Comedi code
 258   unsigned int n_subdevs;       // number of subdevices on this device
 259   char         driver_name[COMEDI_NAMELEN];
 260   char         board_name[COMEDI_NAMELEN];
 261   int          read_subdevice;  // index of subdevice whose buffer is read by read(), etc. on file descriptor from comedi_fileno() (negative means none)
 262   int          write_subdevice; // index of subdevice whose buffer is written by write(), etc. on file descriptor from comedi_fileno() (negatove means none).
 263   int          unused[30];
 264 };
 265
 266 </programlisting>
 267 </para>
 268
 269 </section>
 270
 271
 272 <section id="ref-type-comedi-t">
 273 <title>
 274 comedi_t
 275 </title>
 276
 277 <para>
 278 The data type <type>comedi_t</type> is used to represent an
 279 open &comedi; device:
 280 <programlisting>
 281 typedef struct comedi_t_struct comedi_t;
 282 </programlisting>
 283 A valid <type>comedi_t</type> pointer is returned by a
 284 successful call to
 285 <function><link linkend="func-ref-comedi-open">comedi_open</link></function>,
 286 and should be used for subsequent access to the device.
 287 It is an opaque type, and pointers to type
 288 <parameter>comedi_t</parameter>
 289 should not be dereferenced by the application.
 290 </para>
 291
 292 </section>
 293
 294
 295 <section id="ref-type-sampl-t">
 296 <title>
 297 sampl_t
 298 </title>
 299
 300 <programlisting>
 301 typedef unsigned short sampl_t;
 302 </programlisting>
 303
 304 <para>
 305 The data type <type>sampl_t</type> is one
 306 of the generic
 307 types used to represent data values in Comedilib.  It is used in a few
 308 places where a data type
 309 shorter than <type><link linkend="ref-type-lsampl-t">lsampl_t</link></type> is
 310 useful.  On most architectures it is a 16-bit, unsigned integer.
 311 </para>
 312
 313 <para>
 314 Most drivers represent data transferred by <function>read</function> and
 315 <function>write</function> functions using <type>sampl_t</type>.
 316 Applications should check the subdevice flag
 317 <constant>SDF_LSAMPL</constant> to determine if the subdevice uses
 318 <type>sampl_t</type> or
 319 <type><link linkend="ref-type-lsampl-t">lsampl_t</link></type>.
 320 </para>
 321
 322 </section>
 323
 324 <section id="ref-type-lsampl-t">
 325 <title>
 326 lsampl_t
 327 </title>
 328
 329 <programlisting>
 330 typedef unsigned int lsampl_t;
 331 </programlisting>
 332
 333 <para>
 334 The data type
 335 <type><link linkend="ref-type-lsampl-t">lsampl_t</link></type>
 336 is the data type typically used to represent
 337 data values in Comedilib.  On most architectures it is a 32-bit,
 338 unsigned integer.
 339 </para>
 340 </section>
 341
 342
 343 <section id="ref-type-comedi-trig">
 344 <title>
 345 comedi_trig (deprecated)
 346 </title>
 347
 348 <programlisting>
 349 typedef struct comedi_trig_struct comedi_trig;
 350
 351 struct comedi_trig_struct{
 352   unsigned int subdev;   /* subdevice */
 353   unsigned int mode;  /* mode */
 354   unsigned int flags;
 355   unsigned int n_chan;  /* number of channels */
 356   unsigned int *chanlist;   /* channel/range list */
 357   <link linkend="ref-type-sampl-t">sampl_t</link> *data;  /* data list, size depends on subd flags */
 358   unsigned int n;  /* number of scans */
 359   unsigned int trigsrc;
 360   unsigned int trigvar;
 361   unsigned int trigvar1;
 362   unsigned int data_len;
 363   unsigned int unused[3];
 364 };
 365 </programlisting>
 366
 367 <para>
 368 The <type>comedi_trig</type> structure is a control structure used by the
 369 <constant>COMEDI_TRIG</constant> ioctl, an older method of communicating
 370 instructions to the driver and hardware.  Use of <type>comedi_trig</type> is
 371 deprecated, and should not be used in new applications.
 372 </para>
 373 </section>
 374
 375 <section id="ref-type-comedi-sv-t">
 376 <title>
 377 comedi_sv_t (deprecated)
 378 </title>
 379
 380 <programlisting>
 381 typedef struct comedi_sv_struct comedi_sv_t;
 382
 383 struct comedi_sv_struct{
 384   comedi_t *dev;
 385   unsigned int subdevice;
 386   unsigned int chan;
 387
 388   /* range policy */
 389   int range;
 390   int aref;
 391
 392   /* number of measurements to average (for ai) */
 393   int n;
 394
 395   <link linkend="ref-type-lsampl-t">lsampl_t</link> maxdata;
 396 };
 397 </programlisting>
 398
 399 <para>
 400 The <type>comedi_sv_t</type> structure is used by the <function>comedi_sv_&hellip;</function>
 401 functions to provide a simple method of accurately measuring
 402 slowly varying inputs.  See the relevant section for more
 403 details.
 404 </para>
 405 </section>
 406
 407 <section id="ref-type-comedi-cmd">
 408 <title>
 409 comedi_cmd
 410 </title>
 411
 412 <programlisting>
 413 typedef struct comedi_cmd_struct comedi_cmd;
 414
 415 struct comedi_cmd_struct{
 416   unsigned int subdev;
 417   unsigned int flags;
 418
 419   unsigned int start_src;
 420   unsigned int start_arg;
 421
 422   unsigned int scan_begin_src;
 423   unsigned int scan_begin_arg;
 424
 425   unsigned int convert_src;
 426   unsigned int convert_arg;
 427
 428   unsigned int scan_end_src;
 429   unsigned int scan_end_arg;
 430
 431   unsigned int stop_src;
 432   unsigned int stop_arg;
 433
 434   unsigned int *chanlist;
 435   unsigned int chanlist_len;
 436
 437   <link linkend="ref-type-sampl-t">sampl_t</link> *data;
 438   unsigned int data_len;
 439 };
 440 </programlisting>
 441
 442 <para>
 443 More information on using commands can be found in the
 444 <link linkend="commandsstreaming">command section</link>.
 445 </para>
 446 </section>
 447
 448 <section id="ref-type-comedi-insn">
 449 <title>
 450 comedi_insn
 451 </title>
 452
 453 <programlisting>
 454 typedef struct comedi_insn_struct comedi_insn;
 455
 456 struct comedi_insn_struct{
 457   unsigned int insn;
 458   unsigned int n;
 459   <link linkend="ref-type-lsampl-t">lsampl_t</link>*data;
 460   unsigned int subdev;
 461   unsigned int chanspec;
 462   unsigned int unused[3];
 463 };
 464 </programlisting>
 465
 466 <para>
 467 Comedi instructions are described by the <type>comedi_insn</type> structure.
 468 Applications send instructions to the driver in order to perform
 469 control and measurement operations that are done immediately or
 470 synchronously, i.e., the operations complete before program control
 471 returns to the application.  In particular, instructions cannot
 472 describe acquisition that involves timers or external events.
 473 </para>
 474
 475 <para>
 476 The field insn determines the type of instruction that is sent
 477 to the driver. Valid instruction types are:
 478 </para>
 479
 480 <variablelist>
 481   <varlistentry>
 482     <term>
 483 <anchor id="insn-read"/>
 484 <constant>INSN_READ</constant>
 485     </term>
 486     <listitem>
 487       <para>
 488 read values from an input channel
 489       </para>
 490     </listitem>
 491   </varlistentry>
 492   <varlistentry>
 493     <term>
 494 <anchor id="insn-write"/>
 495 <constant>INSN_WRITE</constant>
 496     </term>
 497     <listitem>
 498       <para>
 499 write values to an output channel
 500       </para>
 501     </listitem>
 502   </varlistentry>
 503   <varlistentry>
 504     <term>
 505 <anchor id="insn-bits"/>
 506 <constant>INSN_BITS</constant>
 507     </term>
 508     <listitem>
 509       <para>
 510 read/write values on multiple digital I/O channels
 511       </para>
 512     </listitem>
 513   </varlistentry>
 514   <varlistentry>
 515     <term>
 516 <anchor id="insn-config"/>
 517 <constant>INSN_CONFIG</constant>
 518     </term>
 519     <listitem>
 520       <para>
 521 configure a subdevice
 522       </para>
 523     </listitem>
 524   </varlistentry>
 525   <varlistentry>
 526     <term>
 527 <anchor id="insn-gtod"/>
 528 <constant>INSN_GTOD</constant>
 529     </term>
 530     <listitem>
 531       <para>
 532 read a timestamp, identical to <function>gettimeofday</function> except the seconds
 533 and microseconds values are of type <type><link linkend="ref-type-lsampl-t">lsampl_t</link></type>.
 534       </para>
 535     </listitem>
 536   </varlistentry>
 537   <varlistentry>
 538     <term>
 539 <anchor id="insn-wait"/>
 540 <constant>INSN_WAIT</constant>
 541     </term>
 542     <listitem>
 543       <para>
 544 wait a specified number of nanoseconds
 545       </para>
 546     </listitem>
 547   </varlistentry>
 548 </variablelist>
 549
 550 <para>
 551 The number of samples to read or write, or the size of the configuration
 552 structure is specified by the field n, and the buffer for those
 553 samples by data.  The field subdev is the subdevice index
 554 that the instruction is sent to.  The field chanspec specifies
 555 the channel, range, and analog reference (if applicable).
 556 </para>
 557
 558 <para>
 559 Instructions can be sent to drivers using
 560 <function><link linkend="func-ref-comedi-do-insn">comedi_do_insn</link></function>.
 561 Multiple instructions can be sent to drivers in the same system call using
 562 <function><link linkend="func-ref-comedi-do-insnlist">comedi_do_insnlist</link></function>.
 563 </para>
 564 </section>
 565
 566 <section id="ref-type-comedi-range">
 567 <title>
 568 comedi_range
 569 </title>
 570
 571 <programlisting>
 572 typedef struct comedi_range_struct comedi_range;
 573
 574 struct comedi_range_struct{
 575   double min;
 576   double max;
 577   unsigned int unit;
 578 }comedi_range;
 579 </programlisting>
 580
 581 <para>
 582 The <type>comedi_range</type> structure conveys part of the information
 583 necessary to translate sample values to physical units, in particular,
 584 the endpoints of the range and the physical unit type.  The
 585 physical unit type is specified by the field unit, which may
 586 take the values <constant>UNIT_volt</constant> for volts,
 587 <constant>UNIT_mA</constant> for milliamps,
 588 or <constant>UNIT_none</constant> for unitless.  The endpoints are specified by
 589 the fields min and max.
 590 </para>
 591 </section>
 592
 593 <section id="ref-type-comedi-krange">
 594 <title>
 595 comedi_krange
 596 </title>
 597
 598 <programlisting>
 599 typedef struct comedi_krange_struct comedi_krange;
 600
 601 struct comedi_krange_struct{
 602   int min;
 603   int max;
 604   unsigned int flags;
 605 };
 606 </programlisting>
 607
 608 <para>
 609 The <type>comedi_krange</type> structure is used to transfer range information
 610 between the driver and Comedilib, and should not normally be used
 611 by applications.  The structure conveys the same information as the
 612 comedi_range structure, except the fields min and max
 613 are integers, multiplied by a factor of 1000000 compared to the
 614 counterparts in <type>comedi_range</type>.
 615 </para>
 616
 617 <para>
 618 In addition, <systemitem>kcomedilib</systemitem> uses the
 619 <type>comedi_krange</type> structure in place
 620 of the <type>comedi_range</type> structure.
 621 </para>
 622
 623 </section>
 624
 625 <section id="ref-type-comedi-insnlist">
 626 <title>
 627 comedi_insnlist
 628 </title>
 629
 630 <programlisting>
 631 typedef struct comedi_insnlist_struct comedi_insnlist;
 632
 633 struct comedi_insnlist_struct{
 634   unsigned int n_insns;
 635   comedi_insn *insns;
 636 };
 637 </programlisting>
 638
 639 <para>
 640 A <type>comedi_insnlist</type> structure is used to communicate
 641 a list of instructions to the driver using the
 642 <function><link linkend="func-ref-comedi-do-insnlist">comedi_do_insnlist</link></function>
 643 function.
 644
 645 </para>
 646
 647 </section>
 648
 649 <section id="ref-type-comedi-polynomial-t">
 650 <title>
 651 comedi_polynomial_t
 652 </title>
 653
 654 <programlisting>
 655 #define COMEDI_MAX_NUM_POLYNOMIAL_COEFFICIENTS 4
 656 typedef struct {
 657   double coefficients[COMEDI_MAX_NUM_POLYNOMIAL_COEFFICIENTS];
 658   double expansion_origin;
 659   unsigned order;
 660 } comedi_polynomial_t;
 661 </programlisting>
 662
 663 <para>
 664 A <type>comedi_polynomial_t</type> holds calibration data for a channel of a
 665 subdevice.  It is initialized by the
 666 <function><link linkend="func-ref-comedi-get-hardcal-converter">comedi_get_hardcal_converter</link></function>
 667 or <function><link linkend="func-ref-comedi-get-softcal-converter">comedi_get_softcal_converter</link></function>
 668 calibration functions and is passed to the
 669 <function><link linkend="func-ref-comedi-to-physical">comedi_to_physical</link></function>
 670 and <function><link linkend="func-ref-comedi-from-physical">comedi_from_physical</link></function>
 671 raw/physical conversion functions.
 672 </para>
 673
 674 </section>
 675
 676 </section>
 677
 678         <section id="functionreference">
 679                 <title>Functions</title>
 680                         <xi:include href="funcref.xml"/>
 681                         <xi:include href="command_funcref.xml"/>
 682                         <xi:include href="calibration_funcref.xml"/>
 683                         <xi:include href="dio_funcref.xml"/>
 684                         <xi:include href="error_funcref.xml"/>
 685                         <xi:include href="extensions_funcref.xml"/>
 686                         <xi:include href="deprecated_funcref.xml"/>
 687         </section>
 688         <xi:include href="drivers.xml"/>
 689 </section>