stv0g/comedilib
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity
comedilib/doc/funcref
Frank Mori Hess 34b9800e40 Added const qualifiers to some char* return values. Added new 
experimental comedi_dio_bitfield2() function which works with
> 32 channels.  Only works properly with ni_65xx currently.
Will post a request for review by any interested
parties to list before I bother making the rest of the drivers
work with it.
2006-10-17 18:19:29 +00:00

1285 lines
49 KiB
Text
Raw Blame History

Function: comedi_close -- close a Comedi device
Retval: int
Param: comedi * device
Description:
Close a device previously opened by comedi_open().
Returns:
If sucessful, comedi_close returns 0. On failure, -1 is returned.
Function: comedi_open -- open a Comedi device
Retval: comedi_t *
Param: const char * filename
Description:
Open a Comedi device specified by the file filename.
Returns:
If sucessful, comedi_open returns a pointer to a valid comedi_t
structure. This structure is transparent; the pointer should not
be dereferenced by the application. NULL is returned on failure.
Function: comedi_loglevel -- change Comedilib logging properties
Retval: int
Param: int loglevel
Description:
This function affects the output of debugging and error messages
from Comedilib. By increasing the loglevel, additional debugging
information will be printed. Error and debugging messages are
printed to the stream stderr.
The default loglevel can be set by using the environment variable
COMEDI_LOGLEVEL. The default loglevel is 1.
In order to conserve resources, some debugging information is
disabled by default when Comedilib is compiled.
The meaning of the loglevels is as follows:
COMEDI_LOGLEVEL=0 Comedilib prints nothing.
COMEDI_LOGLEVEL=1 (default) Comedilib prints error messages when
there is a self-consistency error (i.e., an internal bug.)
COMEDI_LOGLEVEL=2 Comedilib prints an error message when an invalid
parameter is passed.
COMEDI_LOGLEVEL=3 Comedilib prints an error message whenever an
error is generated in the Comedilib library or in the C library,
when called by Comedilib.
COMEDI_LOGLEVEL=4 Comedilib prints a lot of junk.
Returns:
This function returns the previous loglevel.
Function: comedi_perror -- print a Comedilib error message
Retval: void
Param: const char * s
Description:
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
comedi_errno(). This error number can be converted to a
human-readable form by the functions comedi_perror()
and comedi_strerror().
These functions are intended to mimic the behavior of the
standard C library functions perror(), strerror(), and errno.
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.
The function comedi_perror() 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.
Function: comedi_strerror -- return string describing Comedilib error code
Retval: char *
Param: int errnum
Description:
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
comedi_errno(). This error number can be converted to a
human-readable form by the functions comedi_perror()
and comedi_strerror().
These functions are intended to mimic the behavior of the
standard C library functions perror(), strerror(), and errno.
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.
The function comedi_strerror() returns a pointer to a
character string
describing the Comedilib error errnum. 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.
Function: comedi_errno -- number of last Comedilib error
Retval: int
Param: void
Description:
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
comedi_errno(). This error number can be converted to a
human-readable form by the functions comedi_perror()
and comedi_strerror().
These functions are intended to mimic the behavior of the
standard C library functions perror(), strerror(), and errno.
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.
The function comedi_errno() returns an integer describing
the most recent comedilib error. This integer may be used
as the errnum parameter for comedi_strerror().
Note that comedi_errno() is deliberately different than the
variable errno. This is to overcome difficulties in making
errno thread-safe.
Function: comedi_fileno -- integer descriptor of Comedilib device
Retval: int
Param: comedi_t * device
Description:
The function comedi_fileno returns the integer descriptor for
the device dev. This descriptor can then be used as the
file descriptor parameter of read(), write(), etc.
This function is intended to mimic the standard C library
function fileno(). If dev is an invalid comedi_t
pointer, the function returns -1 and sets the appropriate
Comedilib error value.
Function: comedi_get_n_subdevices -- number of subdevices
Retval: int
Param: comedi_t * device
Description:
Returns the number of subdevices belonging to the Comedi
device referenced by the parameter device.
Function: comedi_get_version_code -- Comedi version code
Retval: int
Param: comedi_t * device
Description:
Returns the Comedi kernel module version code. A valid Comedi
device referenced by the parameter device is necessary to
communicate with the kernel module. On error, -1 is returned.
The version code is encoded as a bitfield of three 8-bit
numbers. For example, 0x00073d is the version code for
version 0.7.61.
This function is of limited usefulness. A typical
mis-application of this function is to use it to determine
if a certain feature is supported. If the application needs
to know of the existence of a particular feature, an existence
test function should be written and put in the Comedilib source.
Function: comedi_get_driver_name -- Comedi driver name
Retval: char *
Param: comedi_t * device
Description:
The function comedi_get_driver_name returns a pointer
to a string containing the name of the driver being used by comedi
for the comedi device represented by device. This pointer is
valid until the device is closed. This function returns NULL
if there is an error.
Function: comedi_get_board_name -- Comedi device name
Retval: char *
Param: comedi_t * device
Description:
The function comedi_get_board_name returns a pointer
to a string containing the name of the device. This pointer is
valid until the comedi descriptor it is closed. This
function returns NULL if there is an error.
Function: comedi_get_subdevice_type -- type of subdevice
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Description:
The function comedi_get_subdevice_type() returns an
integer describing the type of subdevice that belongs to the comedi
device device and has the index subdevice. The
function returns -1 if there is an error.
XXX Subdevice type table
Function: comedi_find_subdevice_by_type -- search for subdevice type
Retval: int
Param: comedi_t * device
Param: int type
Param: unsigned int start_subdevice
Description:
The function comedi_find_subdevice_by_type() tries to
locate a subdevice belonging to comedi device device,
having type type, starting with the subdevice
start_subdevice. If it finds a subdevice with the requested
type, it returns its index. If it does not locate the requested
subdevice, it returns -1 and sets the Comedilib error number to
XXX "subdevice not found". If there is an error, the function
returns -1 and sets the appropriate error.
Function: comedi_get_read_subdevice -- find streaming input subdevice
Retval: int
Param: comedi_t * device
Description:
The function comedi_get_read_subdevice() returns the subdevice
that allows streaming input for device dev. If no subdevice
supports streaming input, -1 is returned and the Comedilib error
number is set to XXX "subdevice not found".
Function: comedi_get_write_subdevice -- find streaming output subdevice
Retval: int
Param: comedi_t * device
Description:
The function comedi_get_write_subdevice() returns the subdevice
that allows streaming output for device dev. If no subdevice
supports streaming output, -1 is returned and the Comedilib error
number is set to XXX "subdevice not found".
Function: comedi_get_subdevice_flags -- properties of subdevice
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Description:
This function returns a bitfield describing the capabilities of
the specified subdevice. If there is an error, -1 is returned,
and the Comedilib error value is set.
<table COLSEP="1" ROWSEP="1" ORIENT="port" PGWIDE="1">
<title>subdevice flags</title>
<tgroup COLS="3" ALIGN="left" >
<thead>
<row>
<entry>Subdevice Flag</entry>
<entry>Value (hexadecimal)</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>SDF_BUSY</entry>
<entry>0x00000001</entry>
<entry>The subdevice is busy performing an asynchronous command. A subdevice being "busy"
is slightly different from the "running" state flagged by SDF_RUNNING. A "running" subdevice
is always "busy", but a "busy" subdevice is not necessarily "running". For example, suppose an
analog input command has been completed by the hardware, but there are still samples in
Comedi's buffer waiting to be read out. In this case, the subdevice is not "running", but
is still "busy" until all the samples are read out or comedi_cancel() is called.</entry>
</row>
<row>
<entry>SDF_BUSY_OWNER</entry>
<entry>0x00000002</entry>
<entry>The subdevice is "busy", and the command it is running was started by the current process.</entry>
</row>
<row>
<entry>SDF_LOCKED</entry>
<entry>0x00000004</entry>
<entry>The subdevice has been locked by comedi_lock().</entry>
</row>
<row>
<entry>SDF_LOCK_OWNER</entry>
<entry>0x00000008</entry>
<entry>The subdevice is locked, and was locked by the current process.</entry>
</row>
<row>
<entry>SDF_MAXDATA</entry>
<entry>0x00000010</entry>
<entry>The maximum data value for the subdevice depends on the channel.</entry>
</row>
<row>
<entry>SDF_FLAGS</entry>
<entry>0x00000020</entry>
<entry>The subdevice flags depend on the channel (unfinished/broken support in library).</entry>
</row>
<row>
<entry>SDF_RANGETYPE</entry>
<entry>0x00000040</entry>
<entry>The range type depends on the channel.</entry>
</row>
<row>
<entry>SDF_CMD</entry>
<entry>0x00001000</entry>
<entry>The subdevice supports asynchronous commands.</entry>
</row>
<row>
<entry>SDF_SOFT_CALIBRATED</entry>
<entry>0x00002000</entry>
<entry>The subdevice relies on the host to do calibration in software.
Software calibration coefficients are determined by the comedi_soft_calibrate
utility. See the description of the comedi_get_softcal_converter() function
for more information.
</entry>
</row>
<row>
<entry>SDF_READABLE</entry>
<entry>0x00010000</entry>
<entry>The subdevice can be read (e.g. analog input).</entry>
</row>
<row>
<entry>SDF_WRITABLE</entry>
<entry>0x00020000</entry>
<entry>The subdevice can be written to (e.g. analog output).</entry>
</row>
<row>
<entry>SDF_INTERNAL</entry>
<entry>0x00040000</entry>
<entry>The subdevice does not have externally visible lines.</entry>
</row>
<row>
<entry>SDF_GROUND</entry>
<entry>0x00100000</entry>
<entry>The subdevice supports AREF_GROUND.</entry>
</row>
<row>
<entry>SDF_COMMON</entry>
<entry>0x00200000</entry>
<entry>The subdevice supports AREF_COMMON.</entry>
</row>
<row>
<entry>SDF_DIFF</entry>
<entry>0x00400000</entry>
<entry>The subdevice supports AREF_DIFF.</entry>
</row>
<row>
<entry>SDF_OTHER</entry>
<entry>0x00800000</entry>
<entry>The subdevice supports AREF_OTHER</entry>
</row>
<row>
<entry>SDF_DITHER</entry>
<entry>0x01000000</entry>
<entry>The subdevice supports dithering (via the CR_ALT_FILTER chanspec flag).</entry>
</row>
<row>
<entry>SDF_DEGLITCH</entry>
<entry>0x02000000</entry>
<entry>The subdevice supports deglitching (via the CR_ALT_FILTER chanspec flag).</entry>
</row>
<row>
<entry>SDF_RUNNING</entry>
<entry>0x08000000</entry>
<entry>An asynchronous command is running. You can use this flag to poll for the completion of an
output command.</entry>
</row>
<row>
<entry>SDF_LSAMPL</entry>
<entry>0x10000000</entry>
<entry>The subdevice uses the 32 bit lsampl_t type instead of the 16 bit sampl_t for
asynchronous command data.</entry>
</row>
<row>
<entry>SDF_PACKED</entry>
<entry>0x20000000</entry>
<entry>The subdevice uses bitfield samples for asynchronous command data,
one bit per channel (otherwise it uses
one sampl_t or lsampl_t per channel). Commonly used for digital subdevices.</entry>
</row>
</tbody>
</tgroup>
</table>
Function: comedi_get_n_channels -- number of subdevice channels
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Description:
The function comedi_get_n_channels() returns the number
of channels of the subdevice belonging to the comedi device device
and having index subdevice. This function returns -1 on error and
the Comedilib error value is set.
Function: comedi_range_is_chan_specific -- range information depends on channel
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Description:
If each channel of the specified subdevice has different range
information, this function returns 1. Otherwise, this function
returns 0. On error, this function returns -1.
Function: comedi_maxdata_is_chan_specific -- maximum sample depends on channel
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Description:
If each channel of the specified subdevice has different maximum
sample values, this function returns 1. Otherwise, this function
returns 0. On error, this function returns -1.
Function: comedi_get_maxdata -- maximum sample of channel
Retval: lsampl_t
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int channel
Description:
The function comedi_get_maxdata() returns the maximum
valid data value for channel <parameter>channel</parameter> of subdevice
<parameter>subdevice</parameter> belonging to the comedi device
<parameter>device</parameter>.
Returns:
The maximum valid sample value, or 0 on error.
Function: comedi_get_n_ranges -- number of ranges of channel
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int channel
Description:
The function comedi_get_n_ranges() returns the number
of ranges of the channel chan belonging to the subdevice
of the comedi device device. This function returns -1 on error.
Function: comedi_get_range -- range information of channel
Retval: comedi_range *
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int channel
Param: unsigned int range
Description:
The function comedi_get_range() 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 device is closed. If there is an
error, NULL is returned.
Function: comedi_find_range -- search for range
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int channel
Param: unsigned int unit
Param: double min
Param: double max
Description:
The function comedi_find_range() tries to
locate the optimal (smallest) range for the channel chan
belonging to a subdevice of the comedi device device,
that includes both min and max in units.
If a matching range is found, the index of the matching range is
returned. If no matching range is available, the function returns
-1.
Function: comedi_get_buffer_size -- streaming buffer size of subdevice
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Description:
The function comedi_get_buffer_size() returns the size (in bytes)
of the streaming buffer for the subdevice specified by device and
subdevice. On error, -1 is returned.
Function: comedi_get_max_buffer_size -- maximum streaming buffer size
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Description:
The function comedi_get_max_buffer_size() returns the maximum
allowable size (in bytes) of the streaming buffer for the subdevice
specified by device and subdevice. Changing the maximum buffer
size requires appropriate privileges. On error, -1 is returned.
Function: comedi_set_buffer_size -- streaming buffer size of subdevice
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int size
Description:
The function comedi_set_buffer_size() changes the size of the
streaming buffer for the subdevice specified by device and subdevice.
The parameter size must be a multiple of the virtual memory page
size.
The virtual memory page size can be determined using
sysconf(_SC_PAGE_SIZE).
Function: comedi_trigger -- perform streaming input/output (deprecated)
Retval: int
Param: comedi_t * device
Param: comedi_trig * trig
Status: deprecated
Description:
The function comedi_trigger() instructs Comedi to
perform the command specified by the trigger structure trig.
The return value depends on
the particular trig being issued. If there is an
error, -1 is returned.
Function: comedi_do_insnlist -- perform multiple instructions
Retval: int
Param: comedi_t * device
Param: comedi_insnlist * list
Description:
The function comedi_do_insnlist() performs multiple Comedi
instructions as part of one system call. In addition, Comedi
attempts to perform the instructions atomically, that is, on
standard Linux kernels, no process preemption should occur
during the instructions. However, the process may be preempted
before or after the group of instructions.
This function can be used to avoid the overhead of multiple
system calls, or to ensure that multiple instructions occur
without significant delay between them.
Preemption may occur if any of the instructions or the data
arrays of any of the instructions exist in non-resident or
copy-on-write pages.
Returns:
The function comedi_do_insnlist() returns the number of
sucessfully completed instructions. Error information for
the unsucessful instruction is not available. If there is
an error before the first instruction can be executed, -1
is returned.
Function: comedi_do_insn -- perform instruction
Retval: int
Param: comedi_t * device
Param: comedi_insn * instruction
Description:
The function comedi_do_insn() performs a single instruction.
If sucessful, comedi_do_insn() returns the number of samples
measured, which may be less than the number of requested
samples. Comedi limits the number of requested samples in
order to enforce fairness among processes. If there is an
error, -1 is returned.
Function: comedi_lock -- subdevice reservation
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Description:
The function comedi_lock() reserves a subdevice for use by the
current process. While the lock is held, no other process is
allowed to read, write, or configure that subdevice, although
other processes can read information about the subdevice. The
lock is released when comedi_unlock() is called, or the device
is closed.
Returns:
If sucessful, 0 is returned. If there is an error,
-1 is returned.
Function: comedi_unlock -- subdevice reservation
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Description:
The function comedi_unlock() released a subdevice lock acquired
by comedi_lock(). If sucessful, 0 is returned, otherwise -1.
Function: comedi_to_phys -- convert sample to physical units
Retval: double
Param: lsampl_t data
Param: comedi_range * range
Param: lsampl_t maxdata
Description:
Converts data given in sample values (lsampl_t, between 0 and
maxdata) into physical units (double). The parameter range
represents the conversion information to use, and the parameter
maxdata represents the maximum possible data value for the
channel that the data was read.
Conversion of endpoint sample values, that is, sample values
equal to 0 or maxdata, is affected by the Comedilib out-of-range
behavior. If the out-of-range behavior is set to COMEDI_OOR_NAN,
endpoint values are converted to NAN. If the out-of-range
behavior is set to COMEDI_OOR_NUMBER, the endpoint values are
converted similarly to other values.
If there is an error, NAN is returned.
Function: comedi_to_physical -- convert sample to physical units
Retval: double
Param: lsampl_t data
Param: const comedi_polynomial_t *conversion_polynomial
Description:
Converts <parameter>data</parameter> given in Comedi's integer
sample values (lsampl_t, between 0 and
maxdata) into physical units (double). The
<parameter>conversion_polynomial</parameter>
parameter is obtained from either comedi_get_hardcal_converter()
or comedi_get_softcal_converter(). No range checking of the
input <parameter>data</parameter> is performed. It is up to
you to check for <parameter>data</parameter> values of
0 or maxdata if you want to detect possibly out-of-range readings.
This function is intended to supplant comedi_to_phys(), and was
introduced in order to support software calibrations.
Returns:
Physical value corresponding to the input sample value.
Function: comedi_from_phys -- convert physical units to sample
Retval: lsampl_t
Param: double data
Param: comedi_range * range
Param: lsampl_t maxdata
Description:
Converts data given in physical units (data) into sample values
(lsampl_t, between 0 and maxdata). The parameter rng
represents the conversion information to use, and the parameter
maxdata represents the maximum possible data value for the
channel that the data will be written to.
Conversion is not affected by out-of-range behavior. Out-of-range
data parameters are silently truncated to the range 0 to maxdata.
Function: comedi_from_physical -- convert physical units to sample
Retval: lsampl_t
Param: double data
Param: const comedi_polynomial_t *conversion_polynomial
Description:
Converts <parameter>data</parameter> given in physical units into Comedi's
integer sample values
(lsampl_t, between 0 and maxdata). The <parameter>conversion_polynomial</parameter>
parameter is obtained from either comedi_get_hardcal_converter()
or comedi_get_softcal_converter(). The result will be rounded
using the C library's current rounding direction.
No range checking of the input
<parameter>data</parameter> is performed. It is up to you to insure
your data is within the limits of the output range you are using.
This function is intended to supplant comedi_from_phys(), and was
introduced in order to support software calibrations.
Returns:
Comedi sample value corresponding to input physical value.
Function: comedi_data_read -- read single sample from channel
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int channel
Param: unsigned int range
Param: unsigned int aref
Param: lsampl_t * data
Description:
Reads a single sample on the channel specified by the Comedi
device device, the subdevice subdevice, and the channel channel.
For the A/D conversion (if appropriate),
the device is configured to use range specification
range and (if appropriate) analog reference type
aref. Analog reference types that are not supported
by the device are silently ignored.
The function comedi_data_read() reads one data value from
the specified channel and places the data value in the
location pointed to by data.
WARNING: comedi_data_read() does not do any pausing to
allow multiplexed analog inputs to settle before
performing an analog to digital conversion. If you are
switching between different channels and need to allow
your analog input to settle for an accurate reading,
use comedi_data_read_delayed(), or set the
input channel at an earlier time with
comedi_data_read_hint().
On sucess, comedi_data_read() returns 1 (the number of samples
read). If there is an error, -1 is returned.
Data values returned by this function are unsigned integers
less than or equal to the maximum sample value of the channel,
which can be determined using the function comedi_get_maxdata().
Conversion of data values to physical units can be performed
by the function comedi_to_phys().
Function: comedi_data_read_delayed -- read single sample from channel after delaying for specified settling time
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int channel
Param: unsigned int range
Param: unsigned int aref
Param: lsampl_t * data
Param: unsigned int nanosec
Description:
Similar to comedi_data_read() except it will wait for the
specified number of nanoseconds between setting the input
channel and taking a sample. For analog inputs, most
boards have a single
analog to digital converter which is multiplexed to be
able to read multiple channels. If the input is not allowed
to settle after the multiplexer switches channels, the
reading will be inaccurate. This function is useful
for allowing a multiplexed analog input to settle
when switching channels.
Although the settling time is specified in nanoseconds, the
actual settling time will be rounded up to the nearest
microsecond.
Function: comedi_data_read_hint -- tell driver which channel/range/aref you are going to read from next
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int channel
Param: unsigned int range
Param: unsigned int aref
Description:
Used to prepare an analog input for a subsequent call to
comedi_data_read(). It is not necessary to use this
function, but it can be useful for eliminating inaccuaracies
caused by insufficient settling times when switching the
channel
or gain on an analog input. This function sets an analog input
to the channel, range, and aref specified but does not
perform an actual analog to digital conversion.
Alternatively, one can simply use comedi_data_read_delayed(),
which sets up the
input, pauses to allow settling, then performs a conversion.
Function: comedi_data_write -- write single sample to channel
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int channel
Param: unsigned int range
Param: unsigned int aref
Param: lsampl_t data
Description:
Writes a single sample on the channel that is specified by the
Comedi device device, the subdevice subdevice, and the channel
channel. If appropriate, the device is configured to use range
specification range and analog reference type aref. Analog
reference types that are not supported by the device are
silently ignored.
The function comedi_data_write() writes the data value specified
by the parameter data to the specified channel.
On sucess, comedi_data_write() returns 1 (the number of samples
written). If there is an error, -1 is returned.
Function: comedi_dio_config -- change input/output properties of channel
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int channel
Param: unsigned int direction
Description:
The function comedi_dio_config() configures individual channels
in a digital I/O subdevice to be either input or output, depending
on the value of parameter direction. Valid directions are
COMEDI_INPUT or COMEDI_OUTPUT.
Depending on the capabilities of the hardware device, multiple
channels may be grouped together to determine direction. In this
case, a single call to comedi_dio_config() for any channel in the
group will affect the entire group.
If sucessful, 1 is returned, otherwise -1.
Function: comedi_dio_get_config -- query input/output properties of channel
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int channel
Param: unsigned int * direction
Description:
The function comedi_dio_get_config() querys the configuration of
an individual channel
in a digital I/O subdevice (see comedi_dio_config()).
On success, the variable specified by the "direction" pointer will
be set to either COMEDI_INPUT or COMEDI_OUTPUT.
If sucessful, 0 is returned, otherwise -1.
Function: comedi_dio_read -- read single bit from digital channel
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int channel
Param: unsigned int * bit
Description:
The function reads the channel channel belonging to the
subdevice subdevice of device device. The data value that is
read is stored in the location pointed to by bit. This function
is equivalent to comedi_data_read(device,subdevice,channel,0,0,bit).
This function does not require a digital subdevice or a subdevice
with a maximum data value of 1 to work properly.
Return values and errors are the same as comedi_data_read().
Function: comedi_dio_write -- write single bit to digital channel
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int channel
Param: unsigned int bit
Description:
The function writes the value bit to the channel channel belonging
to the subdevice subdevice of device device. This function
is equivalent to comedi_data_write(device,subdevice,channel,0,0,bit).
This function does not require a digital subdevice or a subdevice
with a maximum data value of 1 to work properly.
Return values and errors are the same as comedi_data_write().
Function: comedi_dio_bitfield -- read/write multiple digital channels
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int write_mask
Param: unsigned int * bits
Status: deprecated
Description:
This function is deprecated. Use comedi_dio_bitfield2() instead.
Function: comedi_dio_bitfield2 -- read/write multiple digital channels
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int write_mask
Param: unsigned int * bits
Param: unsigned int base_channel
Description:
The function comedi_dio_bitfield2() allows multiple channels to
be read or written together on a digital input, output,
or configurable digital I/O device.
The parameter <parameter>write_mask</parameter>
and the value pointed to by <parameter>bits</parameter>
are interpreted as bit fields, with the least significant bit
representing channel <parameter>base_channel</parameter>.
For each bit in <parameter>write_mask</parameter> that is
set to 1, the cooresponding bit in <parameter>*bits</parameter>
is written to the digital
output channel. After writing all the output channels, each
channel is read, and the result placed in the approprate bits in
<parameter>*bits</parameter>. The result of
reading an output channel is the last
value written to the output channel.
All the channels may not be read or written at the exact same time.
For example, the driver may need to sequentially write to
several ports in order to set all the digital channels specified
by the <parameter>write_mask</parameter>.
Function: comedi_sv_init -- slowly-varying inputs
Retval: int
Param: comedi_sv_t * sv
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int channel
Status: deprecated
Description:
The function comedi_sv_init() initializes the slow varying Comedi
structure sv to use the device device, the analog input subdevice
subdevice, and the channel channel. The slow varying Comedi
structure is used by comedi_sv_measure() to accurately measure
an analog input by averaging over many samples. The default
number of samples is 100. This function returns 0 on success,
-1 on error.
Function: comedi_sv_update -- slowly-varying inputs
Retval: int
Param: comedi_sv_t * sv
Status: deprecated
Description:
The function comedi_sv_update() updates internal parameters of
the slowly varying Comedi structure sv.
Function: comedi_sv_measure -- slowly-varying inputs
Retval: int
Param: comedi_sv_t * sv
Param: double * data
Status: deprecated
Description:
The function comedi_sv_measure() uses the slowly varying Comedi
structure sv to measure a slowly varying signal. If sucessful,
the result (in physical units) is stored in the location pointed
to by data, and the number of samples is returned. On error, -1
is returned.
Function: comedi_get_cmd_src_mask -- streaming input/output capabilities
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: comedi_cmd * command
Description:
The command capabilities of the subdevice indicated by the parameters
device and subdevice are probed, and the results placed in the
command structure pointed to by the parameter command. The trigger
source elements of the command structure are set to the logical OR
value of possible trigger sources. Other elements in the structure
are undefined. If sucessful, 0 is returned, otherwise -1.
Function: comedi_get_cmd_generic_timed -- streaming input/output capabilities
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: comedi_cmd * command
Param: unsigned int period_ns
Description:
The command capabilities of the subdevice indicated by the parameters
device and subdevice are probed, and the results placed in the
command structure pointed to by the parameter command. The command
structure pointed to by the parameter command is modified to be a
valid command that can be used as a parameter to comedi_command().
The command measures samples at a rate that corresponds to the
period period_ns. The rate is adjusted to a rate that the device
can handle. If sucessful, 0 is returned, otherwise -1.
Function: comedi_cancel -- stop streaming input/output in progress
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Description:
The function comedi_cancel() can be used to stop a Comedi command
previously started by comedi_command() that is still in progress
on the subdevice indicated by the parameters device and subdevice.
This may not return the subdevice to a ready state, since there may
be samples in the buffer that need to be read.
If sucessful, 0 is returned, otherwise -1.
Function: comedi_command -- start streaming input/output
Retval: int
Param: comedi_t * device
Param: comedi_cmd * command
Description:
The function comedi_command() starts streaming input or output. The
command structure pointed to by the parameter command specifies the
acquisition. The command must be able to pass comedi_command_test()
with a return value of 0, or comedi_command() will fail.
For input subdevices, sample values are read using the
function read(). For output subdevices, sample values are written
using the function write().
If sucessful, 0 is returned, otherwise -1.
Function: comedi_command_test -- test streaming input/output configuration
Retval: int
Param: comedi_t * device
Param: comedi_cmd * command
Description:
The function comedi_command_test() tests the command structure pointed
to by the parameter command and returns an integer describing the
testing stages that were sucessfully passed. In addition, if elements
of the command structure are invalid, they may be modified. Source
elements are modified to remove invalid source triggers. Argument
elements are adjusted or rounded to the nearest valid value.
The meanings of the return value are as follows.
0 indicates a valid command.
1 indicates that one of the *_src
members of the command contained an
unsupported trigger. The bits corresponding to the unsupported
triggers are zeroed.
2 indicates that the particular combination
of *_src settings is not supported by the driver, or that
one of the *_src members has the bit corresponding to
multiple trigger sources set at the same time.
3 indicates that one of the *_arg members
of the command is set outside the range of allowable values.
For instance, an argument for a TRIG_TIMER source which
exceeds the board's maximum speed. The invalid *_arg
members will be adjusted to valid values.
4 indicates that one of the *_arg members
required adjustment. For instance, the argument of a
TRIG_TIMER source may have been rounded to the nearest
timing period supported by the board.
5 indicates that some aspect of the
command's chanlist is unsupported by the board. For example,
some board's require that all channels in the chanlist
use the same range.
Function: comedi_poll -- force updating of streaming buffer
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Description:
The function comedi_poll() is used on a subdevice that has a
Comedi command in progress in order to update the streaming buffer.
If supported by the driver, all available samples are copied to
the streaming buffer. These samples may be pending in DMA buffers
or device FIFOs. If sucessful, the number of additional bytes
available is returned. If there is an error, -1 is returned.
Function: comedi_set_max_buffer_size -- streaming buffer size of subdevice
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int max_size
Description:
The function comedi_set_max_buffer_size() changes the maximum
allowable size (in bytes) of the streaming buffer for the subdevice
specified by device and subdevice. Changing the maximum buffer
size requires appropriate privileges. If sucessful, the old buffer
size is returned. On error, -1 is returned.
Function: comedi_get_buffer_contents -- streaming buffer status
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Description:
The function comedi_get_buffer_contents() is used on a subdevice
that has a Comedi command in progress. The number of bytes that
are available in the streaming buffer is returned. If there is
an error, -1 is returned.
Function: comedi_mark_buffer_read -- streaming buffer control
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int num_bytes
Description:
The function comedi_mark_buffer_read() is used on a subdevice
that has a Comedi input command in progress. It should only be used
if you are using a mmap() (as opposed
to calling read() on the device file) to read data from Comedi's buffer,
since Comedi will automatically keep track of how many bytes have been
transferred via read() calls. This function is
used to indicate that the next num_bytes bytes in the buffer
are no longer needed and may be discarded.
If there is an error, -1 is returned.
Function: comedi_mark_buffer_written -- streaming buffer control
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int num_bytes
Description:
The function comedi_mark_buffer_written() is used on a subdevice
that has a Comedi output command in progress. It should only be used
if you are using a mmap() (as opposed to calling write() on the device
file) to write data to Comedi's buffer, since Comedi
will automatically keep track of how many bytes have been
transferred via write() calls. This function is
used to indicate that the next num_bytes bytes in the buffer
are valid and may be sent to the device.
If there is an error, -1 is returned.
Function: comedi_get_buffer_offset -- streaming buffer status
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Description:
The function comedi_get_buffer_offset() is used on a subdevice
that has a Comedi command in progress. This function returns
the offset in bytes of the read pointer in the streaming buffer.
This offset is only useful for memory mapped buffers.
If there is an error, -1 is returned.
Function: comedi_get_timer -- timer information (deprecated)
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: double frequency
Param: unsigned int * trigvar
Param: double * actual_frequency
Status: deprecated
Description:
The function comedi_get_timer converts the frequency frequency
to a number suitable to send to the driver in a comedi_trig
structure. This function remains for compatibility with very
old versions of Comedi, that converted sampling rates to timer
values in the libary. This conversion is now done in the kernel,
and every device has the timer type nanosec_timer, indicating
that timer values are simply a time specified in nanoseconds.
Function: comedi_timed_1chan -- streaming input (deprecated)
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int channel
Param: unsigned int range
Param: unsigned int aref
Param: double frequency
Param: unsigned int num_samples
Param: double * data
Status: deprecated
Description:
Not documented.
Function: comedi_set_global_oor_behavior -- out-of-range behavior
Retval: int
Param: enum comedi_oor_behavior behavior
Status: alpha
Description:
This function changes the Comedilib out-of-range behavior.
This currently affects the behavior of comedi_to_phys() when
converting endpoint sample values, that is, sample values
equal to 0 or maxdata. If the out-of-range behavior is set to
COMEDI_OOR_NAN, endpoint values are converted to NAN. If the
out-of-range behavior is set to COMEDI_OOR_NUMBER, the endpoint
values are converted similarly to other values.
The previous out-of-range behavior is returned.
Function: comedi_apply_calibration -- set hardware calibration from file
Retval: int
Param: comedi_t *device
Param: unsigned int subdevice
Param: unsigned int channel
Param: unsigned int range
Param: unsigned int aref
Param: const char *file_path
Status: alpha
Description:
This function sets the calibration of the specified subdevice
so that it is in proper calibration when using the specified
channel, range and aref. It does so by performing writes
to the appropriate channels of the board's calibration
subdevice(s). Depending on the hardware, the
calibration settings used may or may not depend on the channel,
range, or aref. Furthermore, the calibrations appropriate
for different channel, range, and aref parameters
may not be able to be applied simultaneously.
For example, some boards cannot have their analog inputs calibrated
for more than one input range simultaneously. Applying a calibration for range 1 may
blow away a previously applied calibration for range 0. Or, applying
a calibration for analog input channel 0 may cause the same
calibration to be applied to all the
other analog input channels as well.
Your only guarantee is that calls to comedi_apply_calibration()
on different subdevices will not interfere with each other.
In practice, their are some rules of thumb on how
calibrations behave. No calibrations depend on the aref.
A multiplexed analog input will have calibration settings that
do not depend on the channel, and applying a setting for one
channel will affect
all channels equally. Analog outputs, and analog inputs
with independent a/d converters for each input channel, will have
calibrations settings which do depend on the channel, and the
settings for each channel will be independent of the other
channels.
If you wish to investigate exactly what comedi_apply_calibration()
is doing, you can perform reads on your board's calibration
subdevice to see which calibration channels it is changing.
You can also try to decipher the calibration file directly (it's a
text file).
The file_path parameter can be used
to specify the file which contains the calibration information.
If <parameter>file_path</parameter> is NULL, then comedilib
will use a default
file location. The calibration information used by this function
is generated by the comedi_calibrate program (see its man page).
The functions comedi_parse_calibration_file(),
comedi_apply_parsed_calibration(), and comedi_cleanup_calibration()
provide the same functionality at a slightly lower level.
Returns:
Zero on success, a negative number on failure.
Function: comedi_apply_parsed_calibration -- set calibration from memory
Retval: int
Param: comedi_t * device
Param: unsigned int subdevice
Param: unsigned int channel
Param: unsigned int range
Param: unsigned int aref
Param: const comedi_calibration_t *calibration
Status: alpha
Description:
This function is similar to comedi_apply_calibration()
except the calibration information is read from memory
instead of a file. This function can be more
efficient than comedi_apply_calibration() since the
calibration file does not need to be reparsed with
every call. The <parameter>calibration</parameter> is
obtained by a call to comedi_parse_calibration_file().
Returns:
Zero on success, a negative number on failure.
Function: comedi_cleanup_calibration_file -- free calibration resources
Retval: void
Param: comedi_calibration_t *calibration
Status: alpha
Description:
This function frees the resources associated with a
comedi_calibration_t obtained from
comedi_parse_calibration_file(). <parameter>calibration</parameter>
can not be used again after calling this function.
Function: comedi_get_default_calibration_path -- get default calibration file path
Retval: char*
Param: comedi_t *dev
Status: alpha
Description:
This function returns a string containing a default calibration file
path appropriate for <parameter>dev</parameter>. Memory for the
string is allocated by the function, and should be freed when
the string is no longer needed.
Returns:
A string which contains a file path useable by
comedi_parse_calibration_file(). On error, NULL is returned.
Function: comedi_parse_calibration_file -- load contents of calibration file
Retval: comedi_calibration_t*
Param: const char *file_path
Status: alpha
Description:
This function parses a calibration file (produced by the
comedi_calibrate or comedi_soft_calibrate programs) and returns a pointer
to a comedi_calibration_t which can be passed to the
comedi_apply_parsed_calibration() or comedi_get_softcal_converter()
functions. When you are
finished using the comedi_calibration_t, you should
call comedi_cleanup_calibration() to free the resources
associated with the comedi_calibration_t.
The comedi_get_default_calibration_path() function may
be useful in conjunction with this function.
Returns:
A pointer to parsed calibration information on success, or NULL on failure.
Function: comedi_get_hardcal_converter -- get converter for hardware-calibrated subdevice
Retval: int
Param: comedi_t *dev
Param: unsigned subdevice
Param: unsigned channel
Param: unsigned range
Param: enum comedi_conversion_direction direction
Param: comedi_polynomial_t *converter
Status: alpha
Description:
comedi_get_hardcal_converter() initializes <parameter>converter</parameter> so it can be
passed to either comedi_to_physical() or comedi_from_physical(). The result can be used to
convert data from the specified <parameter>subdevice</parameter>,
<parameter>channel</parameter>, and <parameter>range</parameter>. The <parameter>direction</parameter>
parameter specifies whether <parameter>converter</parameter> will be passed to comedi_to_physical()
or comedi_from_physical().
This function initializes <parameter>converter</parameter> as a simple linear function with no
calibration information, appropriate
for boards which do their gain/offset/nonlinearity corrections in hardware. If your board
needs calibration to be performed in software by the host computer, use comedi_get_softcal_converter()
instead. A subdevice will advertise the fact that it depends on a software calibration
with the SDF_SOFT_CALIBRATED subdevice flag.
The result of this function will only depend on the <parameter>channel</parameter>
parameter if either comedi_range_is_chan_specific() or comedi_maxdata_is_chan_specific()
is true for the specified <parameter>subdevice</parameter>.
Returns:
Zero on success or -1 on failure.
Function: comedi_get_softcal_converter -- get converter for software-calibrated subdevice
Retval: int
Param: unsigned subdevice
Param: unsigned channel
Param: unsigned range
Param: enum comedi_conversion_direction direction
Param: const comedi_calibration_t *parsed_calibration
Param: comedi_polynomial_t *converter
Status: alpha
Description:
comedi_get_softcal_converter() initializes <parameter>converter</parameter> so it can be
passed to either comedi_to_physical() or comedi_from_physical(). The <parameter>converter</parameter>
parameter can then be used to
convert data from the specified <parameter>subdevice</parameter>,
<parameter>channel</parameter>, and <parameter>range</parameter>. The <parameter>direction</parameter>
parameter specifies whether <parameter>converter</parameter> will be passed to comedi_to_physical()
or comedi_from_physical(). The <parameter>parsed_calibration</parameter> parameter contains the
software calibration values for your device, and may be obtained by calling comedi_parse_calibration_file()
on a calibration file generated by the comedi_soft_calibrate program.
This function is only useful for boards that perform their calibrations in software on the host
computer. A subdevice will advertise the fact that it depends on a software calibration
with the SDF_SOFT_CALIBRATED subdevice flag.
Whether or not the result of this function actually depends on the <parameter>channel</parameter>
parameter is
hardware dependent. For example, a multiplexed analog input will typically use the same
calibration for all input channels. Analog outputs will typically use different calibrations
for each output channel.
Software calibrations are implemented as polynomials (up to third order). Since the inverse
of polynomials of order higher than one can't be represented exactly as another polynomial, you
may not be able to get converters for the "reverse" direction. For example, you may be
able to get a converter for an analog input in the COMEDI_TO_PHYSICAL direction, but not
in the COMEDI_FROM_PHYSICAL direction.
Returns:
Zero on success or -1 on failure.
Reference in a new issue View git blame Copy permalink