comedilib/doc/reference.xml

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
	"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % comedilib_entities SYSTEM "comedilib.ent">
%comedilib_entities;
]>

<section id="comedireference" xmlns:xi="http://www.w3.org/2001/XInclude">
	<title>
		&comedi; reference
	</title>

<section id="comedi-comedilib-h">
<title>
Headerfiles: <filename>comedi.h</filename> and <filename>comedilib.h</filename>
</title>

<para>
All <link linkend="writingprograms">application programs</link> must
include the header file <filename>comedilib.h</filename>. (This file
itself includes <filename>comedi.h</filename>.) They contain the full
interface of &comedi;: defines, function prototypes, data structures.
</para>
<para>
The following Sections give more details.
</para>

</section>

<section id="constantsmacros">
<title>
Constants and macros
</title>

<section id="ref-macro-CR-PACK">
<title>
CR_PACK
</title>

<para>
<function>CR_PACK<parameter>chan</parameter><parameter>rng</parameter>
<parameter>aref</parameter></function> is used to initialize the elements of the
<parameter>chanlist</parameter> array in the
<type><link linkend="ref-type-comedi-cmd">comedi_cmd</link></type> data structure,
and the <parameter>chanspec</parameter> member of the
<type><link linkend="ref-type-comedi-insn">comedi_insn</link></type> structure.
</para>
<programlisting>
<![CDATA[
#define CR_PACK(chan,rng,aref)      ( (((aref)&0x3)<<24) | (((rng)&0xff)<<16) | (chan) )
]]>
</programlisting>
<para>
The <parameter>chan</parameter> argument is the channel you wish to
use, with the channel numbering starting at zero.
</para>

<para>
The range <parameter>rng</parameter> is an index, starting at zero,
whose meaning is device dependent.  The
<function><link linkend="func-ref-comedi-get-n-ranges">comedi_get_n_ranges</link></function>
and
<function><link linkend="func-ref-comedi-get-range">comedi_get_range</link></function>
functions are useful in discovering information about the available
ranges.
</para>

<para>
The <parameter>aref</parameter> argument indicates what reference you
want the device to use.  It can be any of the following:
<variablelist>
  <varlistentry>
    <term><constant>AREF_GROUND</constant> <anchor id="aref-ground"/> </term>
    <listitem>
      <para>
        is for inputs/outputs referenced to ground.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><constant>AREF_COMMON</constant> <anchor id="aref-common"/> </term>
    <listitem>
      <para>
	 is for a <quote>common</quote> reference (the low inputs of all the
channels are tied together, but are isolated from ground).
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><constant>AREF_DIFF</constant> <anchor id="aref-diff"/> </term>
    <listitem>
      <para>
    is for differential inputs/outputs.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><constant>AREF_OTHER</constant> <anchor id="aref-other"/> </term>
    <listitem>
      <para>
    is for any reference that does not fit into the above categories.
      </para>
    </listitem>
  </varlistentry>
</variablelist>
Particular drivers may or may not use the AREF flags.  If they are
not supported, they are silently ignored.
</para>
</section>

<section id="ref-macro-CR-PACK-FLAGS">
<title>
CR_PACK_FLAGS
</title>

<para>
<function>CR_PACK_FLAGS<parameter>chan</parameter><parameter>range</parameter>
 <parameter>aref</parameter><parameter>flags</parameter></function>
is similar to
<function><link linkend="ref-macro-CR-PACK">CR_PACK</link></function>
but can be used to combine one or more flag bits (bitwise-ORed together in
the <parameter class="function">flags</parameter> parameter) with the other
parameters.
<programlisting>
<![CDATA[
#define CR_PACK_FLAGS(chan, range, aref, flags) \
        (CR_PACK(chan, range, aref) | ((flags) & CR_FLAGS_MASK))
]]>
</programlisting>
Depending on context, the
<parameter class="function">chan</parameter> parameter might not be a channel;
it could be a trigger source, clock source, gate source etc.  (in which case,
the <parameter class="function">range</parameter> and
<parameter class="function">aref</parameter> parameters would probably be set
to <literal>0</literal>), and the flags would modify the source in some
device-dependant way.
</para>

<para>
The following flag values are defined:
<variablelist>
  <varlistentry>
    <term><constant>CR_ALT_FILTER</constant><anchor id="cr-alt-filter"/></term>
    <term><constant>CR_DITHER</constant></term>
    <term><constant>CR_DEGLITCH</constant></term>
    <listitem>
      <para>
        (all the same) specify that some sort of filtering is to be done
	on the channel, trigger source, etc.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><constant>CR_ALT_SOURCE</constant><anchor id="cr-alt-source"/></term>
    <listitem>
      <para>
        specifies that some alternate source is to be used for the channel
	(usually a calibration source).
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><constant>CR_EDGE</constant><anchor id="cr-edge"/></term>
    <listitem>
      <para>
        is usually combined with a trigger source number to specify that the
	trigger source is edge-triggered if the hardware and driver supports
	both edge-triggering and level-triggering.  If both are supported,
	not asserting this flag specifies level-triggering.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><constant>CR_INVERT</constant><anchor id="cr-invert"/></term>
    <listitem>
      <para>
        specifies that the trigger source, gate source, etc. is to be inverted.
      </para>
    </listitem>
  </varlistentry>
</variablelist>
</para>
</section>

<section id="ref-macro-RANGE-LENGTH">
<title>
RANGE_LENGTH (deprecated)
</title>

<para>
Rangetype values are library-internal tokens that represent an
array of range information structures.  These numbers are primarily
used for communication between the kernel and library.
</para>

<para>
The <function>RANGE_LENGTH<parameter>rangetype</parameter></function>
macro returns the length of the array that is
specified by the <parameter>rangetype</parameter> token.
</para>

<para>
The <function>RANGE_LENGTH</function> macro is deprecated, and should not be used in
new applications.  It is scheduled to be removed from the header
file at version 1.0.  Binary compatibility may be broken for version
1.1.
</para>
</section>

<section id="ref-enum-comedi-conversion-direction">
<title>
enum comedi_conversion_direction
</title>

<para>
<programlisting>
enum comedi_conversion_direction
{
	COMEDI_TO_PHYSICAL,
	COMEDI_FROM_PHYSICAL
};
</programlisting>
</para>
<para>
A <type>comedi_conversion_direction</type> is used to choose between converting data
from Comedi's integer sample values to a physical value
(<constant>COMEDI_TO_PHYSICAL</constant>),
and converting from a physical value to Comedi's integer sample values
(<constant>COMEDI_FROM_PHYSICAL</constant>).
</para>

</section>

<section id="ref-enum-comedi-io-direction">
<title>
enum comedi_io_direction
</title>

<para>
<programlisting>
enum comedi_io_direction
{
	COMEDI_INPUT,
	COMEDI_OUTPUT
};
</programlisting>
</para>
<para>
A <type>comedi_io_direction</type> is used to select between input or output.  For example,
<function><link linkend="func-ref-comedi-dio-config">comedi_dio_config</link></function>
uses the <constant>COMEDI_INPUT</constant> and <constant>COMEDI_OUTPUT</constant> values to specify
whether a configurable digital i/o channel should be configured as an input
or output.
</para>

</section>

<section id="ref-enum-comedi-subdevice-type">
<title>
enum comedi_subdevice_type
</title>

<para>
<programlisting>
enum comedi_subdevice_type {
	COMEDI_SUBD_UNUSED,	/* subdevice is unused by driver */
	COMEDI_SUBD_AI,	/* analog input */
	COMEDI_SUBD_AO,	/* analog output */
	COMEDI_SUBD_DI,	/* digital input */
	COMEDI_SUBD_DO,	/* digital output */
	COMEDI_SUBD_DIO,	/* digital input/output */
	COMEDI_SUBD_COUNTER,	/* counter */
	COMEDI_SUBD_TIMER,	/* timer */
	COMEDI_SUBD_MEMORY,	/* memory, EEPROM, DPRAM */
	COMEDI_SUBD_CALIB,	/* calibration DACs and pots*/
	COMEDI_SUBD_PROC,	/* processor, DSP */
	COMEDI_SUBD_SERIAL,	/* serial IO */
	COMEDI_SUBD_PWM	/* pulse width modulation */
};
</programlisting>
</para>
<para>
The <type>comedi_subdevice_type</type> enumeration specifies the possible values for
a subdevice type.  These values are used by the functions
<function><link linkend="func-ref-comedi-get-subdevice-type">comedi_get_subdevice_type</link></function> and
<function><link linkend="func-ref-comedi-find-subdevice-by-type">comedi_find_subdevice_by_type</link></function>.
</para>

</section>

</section>

<section id="datatypesstructures">
<title>
Data types and structures
</title>
<para>
This Section explains the data structures that users of the &comedi;
API are confronted with:
<programlisting>
typedef struct comedi_devinfo_struct  <link linkend="ref-type-comedi-devinfo">comedi_devinfo</link>;
typedef struct comedi_t_struct        <link linkend="ref-type-comedi-t">comedi_t</link>;
typedef struct sampl_t_struct         <link linkend="ref-type-sampl-t">sampl_t</link>;
typedef struct lsampl_t_struct        <link linkend="ref-type-lsampl-t">lsampl_t</link>;
typedef struct comedi_sv_t_struct     <link linkend="ref-type-comedi-sv-t">comedi_sv_t</link>;
typedef struct comedi_cmd_struct      <link linkend="ref-type-comedi-cmd">comedi_cmd</link>;
typedef struct comedi_insn_struct     <link linkend="ref-type-comedi-insn">comedi_insn</link>;
typedef struct comedi_range_struct    <link linkend="ref-type-comedi-range">comedi_range</link>;
typedef struct comedi_krange_struct   <link linkend="ref-type-comedi-krange">comedi_krange</link>;
typedef struct comedi_insnlist_struct <link linkend="ref-type-comedi-insnlist">comedi_insnlist</link>;
</programlisting>
The data structures used in the implementation of the &comedi; drivers
are described in <xref linkend="driverdatastructures"/>.
</para>


<section id="ref-type-comedi-devinfo">
<title>
comedi_devinfo
</title>

<para>
The data type <type>comedi_devinfo</type> is used to store
information about a device. This structure is usually filled in
automatically when the driver is loaded (<quote>attached</quote>), so
programmers need not access this data structure directly.
<programlisting>
typedef struct comedi_devinfo_struct comedi_devinfo;

struct comedi_devinfo_struct{
  unsigned int version_code;    // version number of the Comedi code
  unsigned int n_subdevs;       // number of subdevices on this device
  char         driver_name[COMEDI_NAMELEN];
  char         board_name[COMEDI_NAMELEN];
  int          read_subdevice;  // index of subdevice whose buffer is read by read(), etc. on file descriptor from comedi_fileno() (negative means none)
  int          write_subdevice; // index of subdevice whose buffer is written by write(), etc. on file descriptor from comedi_fileno() (negatove means none).
  int          unused[30];
};

</programlisting>
</para>

</section>


<section id="ref-type-comedi-t">
<title>
comedi_t
</title>

<para>
The data type <type>comedi_t</type> is used to represent an
open &comedi; device:
<programlisting>
typedef struct comedi_t_struct comedi_t;
</programlisting>
A valid <type>comedi_t</type> pointer is returned by a
successful call to
<function><link linkend="func-ref-comedi-open">comedi_open</link></function>,
and should be used for subsequent access to the device.
It is an opaque type, and pointers to type
<parameter>comedi_t</parameter>
should not be dereferenced by the application.
</para>

</section>


<section id="ref-type-sampl-t">
<title>
sampl_t
</title>

<programlisting>
typedef unsigned short sampl_t;
</programlisting>

<para>
The data type <type>sampl_t</type> is one
of the generic
types used to represent data values in Comedilib.  It is used in a few
places where a data type
shorter than <type><link linkend="ref-type-lsampl-t">lsampl_t</link></type> is
useful.  On most architectures it is a 16-bit, unsigned integer.
</para>

<para>
Most drivers represent data transferred by <function>read</function> and
<function>write</function> functions using <type>sampl_t</type>.
Applications should check the subdevice flag
<constant>SDF_LSAMPL</constant> to determine if the subdevice uses
<type>sampl_t</type> or
<type><link linkend="ref-type-lsampl-t">lsampl_t</link></type>.
</para>

</section>

<section id="ref-type-lsampl-t">
<title>
lsampl_t
</title>

<programlisting>
typedef unsigned int lsampl_t;
</programlisting>

<para>
The data type
<type><link linkend="ref-type-lsampl-t">lsampl_t</link></type>
is the data type typically used to represent
data values in Comedilib.  On most architectures it is a 32-bit,
unsigned integer.
</para>
</section>


<section id="ref-type-comedi-trig">
<title>
comedi_trig (deprecated)
</title>

<programlisting>
typedef struct comedi_trig_struct comedi_trig;

struct comedi_trig_struct{
  unsigned int subdev;   /* subdevice */
  unsigned int mode;  /* mode */
  unsigned int flags;
  unsigned int n_chan;  /* number of channels */
  unsigned int *chanlist;   /* channel/range list */
  <link linkend="ref-type-sampl-t">sampl_t</link> *data;  /* data list, size depends on subd flags */
  unsigned int n;  /* number of scans */
  unsigned int trigsrc;
  unsigned int trigvar;
  unsigned int trigvar1;
  unsigned int data_len;
  unsigned int unused[3];
};
</programlisting>

<para>
The <type>comedi_trig</type> structure is a control structure used by the
<constant>COMEDI_TRIG</constant> ioctl, an older method of communicating
instructions to the driver and hardware.  Use of <type>comedi_trig</type> is
deprecated, and is no longer implemented by the &comedi; kernel layer.
</para>
</section>

<section id="ref-type-comedi-sv-t">
<title>
comedi_sv_t (deprecated)
</title>

<programlisting>
typedef struct comedi_sv_struct comedi_sv_t;

struct comedi_sv_struct{
  comedi_t *dev;
  unsigned int subdevice;
  unsigned int chan;

  /* range policy */
  int range;
  int aref;

  /* number of measurements to average (for ai) */
  int n;

  <link linkend="ref-type-lsampl-t">lsampl_t</link> maxdata;
};
</programlisting>

<para>
The <type>comedi_sv_t</type> structure is used by the <function>comedi_sv_&hellip;</function>
functions to provide a simple method of accurately measuring
slowly varying inputs.  This relies on the <constant>COMEDI_TRIG</constant>
ioctl and is no longer by the &comedi; kernel layer.
</para>
</section>

<section id="ref-type-comedi-cmd">
<title>
comedi_cmd
</title>

<programlisting>
typedef struct comedi_cmd_struct comedi_cmd;

struct comedi_cmd_struct{
  unsigned int subdev;
  unsigned int flags;

  unsigned int start_src;
  unsigned int start_arg;

  unsigned int scan_begin_src;
  unsigned int scan_begin_arg;

  unsigned int convert_src;
  unsigned int convert_arg;

  unsigned int scan_end_src;
  unsigned int scan_end_arg;

  unsigned int stop_src;
  unsigned int stop_arg;

  unsigned int *chanlist;
  unsigned int chanlist_len;

  <link linkend="ref-type-sampl-t">sampl_t</link> *data;
  unsigned int data_len;
};
</programlisting>

<para>
More information on using commands can be found in the
<link linkend="commandsstreaming">command section</link>.
</para>
</section>

<section id="ref-type-comedi-insn">
<title>
comedi_insn
</title>

<programlisting>
typedef struct comedi_insn_struct comedi_insn;

struct comedi_insn_struct{
  unsigned int insn;
  unsigned int n;
  <link linkend="ref-type-lsampl-t">lsampl_t</link>*data;
  unsigned int subdev;
  unsigned int chanspec;
  unsigned int unused[3];
};
</programlisting>

<para>
Comedi instructions are described by the <type>comedi_insn</type> structure.
Applications send instructions to the driver in order to perform
control and measurement operations that are done immediately or
synchronously, i.e., the operations complete before program control
returns to the application.  In particular, instructions cannot
describe acquisition that involves timers or external events.
</para>

<para>
The field insn determines the type of instruction that is sent
to the driver. Valid instruction types are:
</para>

<variablelist>
  <varlistentry>
    <term>
<anchor id="insn-read"/>
<constant>INSN_READ</constant>
    </term>
    <listitem>
      <para>
read values from an input channel
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
<anchor id="insn-write"/>
<constant>INSN_WRITE</constant>
    </term>
    <listitem>
      <para>
write values to an output channel
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
<anchor id="insn-bits"/>
<constant>INSN_BITS</constant>
    </term>
    <listitem>
      <para>
read/write values on multiple digital I/O channels
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
<anchor id="insn-config"/>
<constant>INSN_CONFIG</constant>
    </term>
    <listitem>
      <para>
configure a subdevice
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
<anchor id="insn-gtod"/>
<constant>INSN_GTOD</constant>
    </term>
    <listitem>
      <para>
read a timestamp, identical to <function>gettimeofday</function> except the seconds
and microseconds values are unsigned values of type <type><link linkend="ref-type-lsampl-t">lsampl_t</link></type>.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
<anchor id="insn-wait"/>
<constant>INSN_WAIT</constant>
    </term>
    <listitem>
      <para>
wait a specified number of nanoseconds
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
The number of samples to read or write, or the size of the configuration
structure is specified by the field n, and the buffer for those
samples by data.  The field subdev is the subdevice index
that the instruction is sent to.  The field chanspec specifies
the channel, range, and analog reference (if applicable).
</para>

<para>
Instructions can be sent to drivers using
<function><link linkend="func-ref-comedi-do-insn">comedi_do_insn</link></function>.
Multiple instructions can be sent to drivers in the same system call using
<function><link linkend="func-ref-comedi-do-insnlist">comedi_do_insnlist</link></function>.
</para>
</section>

<section id="ref-type-comedi-range">
<title>
comedi_range
</title>

<programlisting>
typedef struct comedi_range_struct comedi_range;

struct comedi_range_struct{
  double min;
  double max;
  unsigned int unit;
}comedi_range;
</programlisting>

<para>
The <type>comedi_range</type> structure conveys part of the information
necessary to translate sample values to physical units, in particular,
the endpoints of the range and the physical unit type.  The
physical unit type is specified by the field unit, which may
take the values <constant>UNIT_volt</constant> for volts,
<constant>UNIT_mA</constant> for milliamps,
or <constant>UNIT_none</constant> for unitless.  The endpoints are specified by
the fields min and max.
</para>
</section>

<section id="ref-type-comedi-krange">
<title>
comedi_krange
</title>

<programlisting>
typedef struct comedi_krange_struct comedi_krange;

struct comedi_krange_struct{
  int min;
  int max;
  unsigned int flags;
};
</programlisting>

<para>
The <type>comedi_krange</type> structure is used to transfer range information
between the driver and Comedilib, and should not normally be used
by applications.  The structure conveys the same information as the
comedi_range structure, except the fields min and max
are integers, multiplied by a factor of 1000000 compared to the
counterparts in <type>comedi_range</type>.
</para>

<para>
In addition, <systemitem>kcomedilib</systemitem> uses the
<type>comedi_krange</type> structure in place
of the <type>comedi_range</type> structure.
</para>

</section>

<section id="ref-type-comedi-insnlist">
<title>
comedi_insnlist
</title>

<programlisting>
typedef struct comedi_insnlist_struct comedi_insnlist;

struct comedi_insnlist_struct{
  unsigned int n_insns;
  comedi_insn *insns;
};
</programlisting>

<para>
A <type>comedi_insnlist</type> structure is used to communicate
a list of instructions to the driver using the
<function><link linkend="func-ref-comedi-do-insnlist">comedi_do_insnlist</link></function>
function.

</para>

</section>

<section id="ref-type-comedi-polynomial-t">
<title>
comedi_polynomial_t
</title>

<programlisting>
#define COMEDI_MAX_NUM_POLYNOMIAL_COEFFICIENTS 4
typedef struct {
  double coefficients[COMEDI_MAX_NUM_POLYNOMIAL_COEFFICIENTS];
  double expansion_origin;
  unsigned order;
} comedi_polynomial_t;
</programlisting>

<para>
A <type>comedi_polynomial_t</type> holds calibration data for a channel of a
subdevice.  It is initialized by the
<function><link linkend="func-ref-comedi-get-hardcal-converter">comedi_get_hardcal_converter</link></function>
or <function><link linkend="func-ref-comedi-get-softcal-converter">comedi_get_softcal_converter</link></function>
calibration functions and is passed to the
<function><link linkend="func-ref-comedi-to-physical">comedi_to_physical</link></function>
and <function><link linkend="func-ref-comedi-from-physical">comedi_from_physical</link></function>
raw/physical conversion functions.
</para>

</section>

</section>

	<section id="functionreference">
		<title>Functions</title>
			<xi:include href="funcref.xml"/>
			<xi:include href="command_funcref.xml"/>
			<xi:include href="calibration_funcref.xml"/>
			<xi:include href="dio_funcref.xml"/>
			<xi:include href="error_funcref.xml"/>
			<xi:include href="extensions_funcref.xml"/>
			<xi:include href="deprecated_funcref.xml"/>
	</section>
	<xi:include href="bindings.xml"/>
	<xi:include href="drivers.xml"/>
</section>