384 lines
13 KiB
HTML
384 lines
13 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
|
|
<TITLE>Comedi Documentation: Comedilib reference</TITLE>
|
|
<LINK HREF="comedilib-5.html" REL=previous>
|
|
<LINK HREF="comedilib.html#toc6" REL=contents>
|
|
</HEAD>
|
|
<BODY>
|
|
Next
|
|
<A HREF="comedilib-5.html">Previous</A>
|
|
<A HREF="comedilib.html#toc6">Contents</A>
|
|
<HR>
|
|
<H2><A NAME="s6">6. Comedilib reference</A></H2>
|
|
|
|
<P>Reference of structures:
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
typedef struct comedi_t_struct comedi_t;
|
|
|
|
typedef struct{
|
|
double min;
|
|
double max;
|
|
unsigned int unit;
|
|
}comedi_range;
|
|
|
|
typedef 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;
|
|
|
|
lsampl_t maxdata;
|
|
}comedi_sv_t;
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
<P>
|
|
<H2><A NAME="ss6.1">6.1 comedi_loglevel()</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>int comedi_loglevel(int loglevel);
|
|
<P>
|
|
<P>
|
|
<P>This function affects the output of debugging and error messages
|
|
from comedlib. By increasing the loglevel, additional debugging
|
|
information will be printed. This function returns the previous
|
|
loglevel. Some debugging information will only be printed if
|
|
comedilib was compiled with this debugging information included.
|
|
The loglevel can also be affected by the environment
|
|
variable COMEDI_LOGLEVEL. The meaning of the loglevels is as
|
|
follows:
|
|
<P>COMEDILIB_LOGLEVEL=0
|
|
<P>Comedilib prints nothing.
|
|
<P>COMEDILIB_LOGLEVEL=1 (default)
|
|
<P>Comedilib only prints error messages when there is a
|
|
self-consistency error.
|
|
<P>COMEDILIB_LOGLEVEL=2
|
|
<P>Comedilib prints an error message whenever an invalid
|
|
parameter is passed to comedilib.
|
|
<P>COMEDILIB_LOGLEVEL=3
|
|
<P>Comedilib prints an error message whenever an error is generated
|
|
in the comedilib library or is generated in the C library when
|
|
called by comedilib.
|
|
<P>COMEDILIB_LOGLEVEL=4
|
|
<P>Comedilib prints a lot of debugging messages.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss6.2">6.2 comedi_open</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>comedi_t *comedi_open(char *fn);
|
|
<P>Opens a comedi device specified by the filename fn. Returns NULL
|
|
on error. Returns a handle that is given as a parameter to other
|
|
comedilib functions.
|
|
<P>You are not supposed to have access to the structure comedi_t.
|
|
<P>void comedi_close(comedi_t *it);
|
|
<P>Closes a device previously opened by comedi_open().
|
|
<P>void comedi_perror(const char *s);
|
|
char *comedi_strerror(int errnum);
|
|
int comedi_errno(void);
|
|
<P>When a comedilib function fails, it usually returns -1 or
|
|
NULL, depending on the return type. An internal library
|
|
variable stores an error number, which can be retrieved with
|
|
<CODE>comedi_errno()</CODE>. This error number can be
|
|
converted to a human-readable form by the functions
|
|
<CODE>comedi_perror()</CODE> and <CODE>comedi_strerror()</CODE>.
|
|
<P>These functions are intended to mimic the behavior of the
|
|
standard C library functions <CODE>perror()</CODE>,
|
|
<CODE>strerror</CODE>, and <CODE>errno()</CODE>. In particular,
|
|
comedilib functions sometimes return an error that is generated
|
|
inside the C library; the comedi error message in this case
|
|
is the same as the C library.
|
|
<P>The function <CODE>comedi_perror()</CODE> prints an error
|
|
message to stderr. The error message consists of the
|
|
argument string, a colon, a space, a description of the error
|
|
condition, and a new line.
|
|
<P>The function <CODE>comedi_strerror()</CODE> returns a pointer to a
|
|
character string
|
|
describing the comedilib error <CODE>errnum</CODE>. The persistence
|
|
of the returned pointer is undefined, and should not be trusted
|
|
after the next comedilib call. An unrecognized error number will
|
|
return a pointer to the string "undefined error", or similar.
|
|
<P>The function <CODE>comedi_errno()</CODE>
|
|
returns an integer describing the most recent comedilib error. This
|
|
integer may be used as the <CODE>errnum</CODE> parameter for
|
|
<CODE>comedi_strerror()</CODE>.
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss6.3">6.3 comedi_fileno()</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>int comedi_fileno(comedi_t *it);
|
|
<P>The function <CODE>comedi_fileno</CODE>
|
|
returns the integer descriptor for the handle <CODE>it</CODE>. If
|
|
<CODE>it</CODE> is an invalid <CODE>comedi_t</CODE> pointer, the function
|
|
returns -1 and sets the appropriate comedilib error value.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss6.4">6.4 comedi_get_n_subdevices()</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>int comedi_get_n_subdevices(comedi_t *it);
|
|
<P>The function <CODE>comedi_get_n_subdevices</CODE> returns the
|
|
number of subdevices associated with the comedi descriptor
|
|
<CODE>it</CODE>, or -1 if there is an error.
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss6.5">6.5 comedi_get_version_code()</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>int comedi_get_version_code(comedi_t *it);
|
|
<P>The function <CODE>comedi_get_version_code()</CODE> returns the
|
|
version code of the currently running comedi module. The version
|
|
code is of the form 0x010203, which is the version code for
|
|
version 1.2.3.
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss6.6">6.6 comedi_get_driver_name()</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>char *comedi_get_driver_name(comedi_t *it);
|
|
<P>The function <CODE>comedi_get_driver_name</CODE> returns a pointer
|
|
to a string containing the name of the driver being used by comedi
|
|
for the comedi device represented by <CODE>it</CODE>. This pointer is
|
|
valid until the comedi descriptor <CODE>it</CODE> is closed. This
|
|
function returns NULL if there is an error.
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss6.7">6.7 comedi_get_board_name()</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>char *comedi_get_board_name(comedi_t *it);
|
|
<P>The function <CODE>comedi_get_board_name</CODE> returns a pointer
|
|
to a string containing the name of the device. This pointer is
|
|
valid until the comedi descriptor <CODE>it</CODE> is closed. This
|
|
function returns NULL if there is an error.
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss6.8">6.8 comedi_get_subdevice_type()</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>int comedi_get_subdevice_type(comedi_t *it,unsigned int subdevice);
|
|
<P>The function <CODE>comedi_get_subdevice_type()</CODE> returns an
|
|
integer describing the type of subdevice that belongs to the comedi
|
|
device <CODE>it</CODE> and has the index <CODE>subdevice</CODE>. The
|
|
function returns -1 is there is an error.
|
|
<P>Valid subdevice types are:
|
|
<P>
|
|
<UL>
|
|
<LI><CODE>COMEDI_SUBD_UNUSED</CODE>
|
|
Subdevice has no functionality, i.e., a place-holder.</LI>
|
|
<LI><CODE>COMEDI_SUBD_AI</CODE> Analog input</LI>
|
|
<LI><CODE>COMEDI_SUBD_AO</CODE> Analog output</LI>
|
|
<LI><CODE>COMEDI_SUBD_DI</CODE> Digital input</LI>
|
|
<LI><CODE>COMEDI_SUBD_DO</CODE> Digital output</LI>
|
|
<LI><CODE>COMEDI_SUBD_DIO</CODE>
|
|
Digital input/output. Channels are configurable as to whether they
|
|
are inputs or outputs.</LI>
|
|
<LI><CODE>COMEDI_SUBD_COUNTER</CODE> Counter</LI>
|
|
<LI><CODE>COMEDI_SUBD_TIMER</CODE> Timer</LI>
|
|
<LI><CODE>COMEDI_SUBD_MEMORY</CODE>
|
|
Memory, e.g., EEPROM or dual-ported RAM</LI>
|
|
<LI><CODE>COMEDI_SUBD_CALIB</CODE>
|
|
Calibration DACs</LI>
|
|
<LI><CODE>COMEDI_SUBD_PROC</CODE>
|
|
Processor or DSP</LI>
|
|
</UL>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss6.9">6.9 comedi_find_subdevice_by_type()</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>int comedi_find_subdevice_by_type(comedi_t *it,int type,unsigned int start_subdevice)
|
|
<P>The function <CODE>comedi_find_subdevice_by_type</CODE> tries to
|
|
locate a subdevice belonging to comedi device <CODE>it</CODE>,
|
|
having type <CODE>type</CODE>, starting with the subdevice
|
|
<CODE>start_subdevice</CODE>. If it finds the requested subdevice,
|
|
it returns its index. If it does not locate the requested
|
|
subdevice, it returns -1 and sets the comedi error number to
|
|
"subdevice not found". If there is an error, the function
|
|
returns -1 and sets the appropriate error.
|
|
<P>For subdevice types, see the manual page for the function
|
|
<CODE>comedi_get_subdevice_type()</CODE>.
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss6.10">6.10 comedi_get_n_channels()</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>
|
|
<P>int comedi_get_n_channels(comedi_t *it,unsigned int subdevice);
|
|
<P>The function <CODE>comedi_get_n_channels()</CODE> returns the number
|
|
of channels of the subdevice belonging to the comedi device <CODE>it</CODE>
|
|
and having index <CODE>subdevice</CODE>. This function returns -1 on error.
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss6.11">6.11 comedi_get_maxdata()</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>lsampl_t comedi_get_maxdata(comedi_t *it,unsigned int subdevice,unsigned int chan);
|
|
<P>The function <CODE>comedi_get_maxdata()</CODE> returns the maximum
|
|
valid data value for channel <CODE>chan</CODE> of subdevice
|
|
<CODE>subdevice</CODE> belonging to the comedi device <CODE>it</CODE>
|
|
This function returns 0 on error.
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss6.12">6.12 comedi_get_rangetype()</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>int comedi_get_rangetype(comedi_t *it,unsigned int subdevice,unsigned int chan);
|
|
<P>The function <CODE>comedi_get_rangetype()</CODE> returns an integer
|
|
that represents the number of range specifications available for a
|
|
particular channel, as well as a conversion table to convert sample
|
|
values to/from physical units. The macro
|
|
<CODE>RANGE_LENGTH(rangetype)</CODE>
|
|
can be used to determine the number of range specifications for a given
|
|
range type.
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss6.13">6.13 comedi_get_range()</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>comedi_range * comedi_get_range(comedi_t *it,unsigned int subdevice,unsigned int chan,unsigned int range);
|
|
<P>The function <CODE>comedi_get_range</CODE> returns a pointer to a
|
|
comedi_range structure that contains information that can be used to
|
|
convert sample values to or from physical units. The pointer is valid
|
|
until the comedi device <CODE>it</CODE> is closed. If there is an
|
|
error, NULL is returned.
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss6.14">6.14 comedi_trigger()</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>int comedi_trigger(comedi_t *it,comedi_trig *trig);
|
|
<P>The function <CODE>comedi_trigger()</CODE> instructs comedi to
|
|
perform the command specified by the trigger structure
|
|
<CODE>trig</CODE>. Results depend on the particular command
|
|
being issued. If there is an error, -1 is returned.
|
|
<P>Complete information about comedi commands is given in the
|
|
manual page comedi(8).
|
|
<P>double comedi_to_phys(lsampl_t data,comedi_range *rng,lsampl_t maxdata);
|
|
lsampl_t comedi_from_phys(double data,comedi_range *rng,lsampl_t maxdata);
|
|
<P>The functions <CODE>comedi_to_phys()</CODE> and
|
|
<CODE>comedi_from_phys()</CODE> convert sample values to/from physical
|
|
units. The parameter <CODE>rng</CODE> represents the conversion
|
|
information to use, and the parameter <CODE>maxdata</CODE> represents
|
|
the maximum possible data value for the channel that the data was read/
|
|
will be written to.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss6.15">6.15 comedi_data_read()</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>int comedi_data_read(comedi_t *it,unsigned int subd,unsigned int chan,
|
|
unsigned int range,unsigned int aref,lsampl_t *data);
|
|
int comedi_data_write(comedi_t *it,unsigned int subd,unsigned int chan,
|
|
unsigned int range,unsigned int aref,lsampl_t data);
|
|
<P>These functions read or write a single sample on the channel that
|
|
is specified by the comedi device <CODE>it</CODE>, the
|
|
subdevice <CODE>subd</CODE>, and the channel <CODE>chan</CODE>.
|
|
For the operation,
|
|
the device is configured to use range specification
|
|
<CODE>range</CODE> and (if appropriate) analog reference type
|
|
<CODE>aref</CODE>. Analog reference types that are not supported
|
|
by the device are silently ignored.
|
|
<P>The function <CODE>comedi_data_read()</CODE> reads one data value from
|
|
the specified channel and places the
|
|
data value that is read in the location pointed to by
|
|
<CODE>data</CODE>.
|
|
<P>The function <CODE>comedi_data_write()</CODE> writes the data value
|
|
specified by the argument <CODE>data</CODE> to
|
|
the specified channel.
|
|
<P>On sucess, these functions return 0. If there is an error, -1 is
|
|
returned.
|
|
<P>Valid analog reference numbers are:
|
|
<P>
|
|
<UL>
|
|
<LI>AREF_GROUND Reference to analog ground</LI>
|
|
<LI>AREF_COMMON Reference to analog common</LI>
|
|
<LI>AREF_DIFF Differential reference</LI>
|
|
<LI>AREF_OTHER Board-specific meaning</LI>
|
|
</UL>
|
|
<P>Valid data values used by these functions is an unsigned integer
|
|
less than or equal to <CODE>maxdata</CODE>, which is channel-dependent.
|
|
Conversion of these data values to physical units can be performed
|
|
by <CODE>comedi_to_phys()</CODE> and <CODE>comedi_from_phys()</CODE>.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss6.16">6.16 comedi_sv_init()</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
int comedi_sv_init(comedi_sv_t *it,comedi_t *dev,unsigned int subd,unsigned int chan);
|
|
int comedi_sv_update(comedi_sv_t *it);
|
|
int comedi_sv_measure(comedi_sv_t *it,double *data);
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
<P>The special functions <CODE>comedi_sv_*()</CODE> are designed to
|
|
make it easy to accurately measure slowly varying analog inputs.
|
|
A slowly
|
|
varying input is one that is effectively constant over the course
|
|
of approximately 100 A/D conversions. However, since these
|
|
conversions can sometimes be pre-empted by scheduling, for most
|
|
purposes, a slowly varying signal should be effectively constant
|
|
for greater than 20 ms (the default Linux timeslice).
|
|
<P>By averaging many A/D conversions of a relatively constant
|
|
signal, it is possible to get a better measurement of the signal
|
|
than a single A/D conversion. In general, the uncertainty of the
|
|
measurement decreases as the square root of the number of samples.
|
|
This is limited by the rate that which the signal varies, and
|
|
ultimately by the spurious free dynamic range of the A/D converter.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss6.17">6.17 comedi_get_timer()</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
int comedi_get_timer(comedi_t *it,unsigned int subdev,double freq,unsigned int *trigvar,
|
|
double *actual_freq);
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<HR>
|
|
Next
|
|
<A HREF="comedilib-5.html">Previous</A>
|
|
<A HREF="comedilib.html#toc6">Contents</A>
|
|
</BODY>
|
|
</HTML>
|