doc/reference.sgml

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