<article>
<title>Comedi Documentation
-<author>David Schleef, <tt/ds@stm.lbl.gov/
+<author>
+David Schleef <tt/ds@stm.lbl.gov/,
+Frank Hess <tt/fmhess@uiuc.edu/
<sect>Introduction
comedi_t *it;
int chan=0;
lsampl_t data;
-
+
it=comedi_open("/dev/comedi0");
comedi_data_read(it,subdev,chan,range,aref,& data);
Should be understandable. Open the device, get the data,
print it out. This is basically the guts of <tt>demo/inp.c</tt>,
without error checking or fancy options.
-Compile it using
+Compile it using
<tscreen><verb>
cc tut1.c -lcomedi -o tut1
Many data acquisition devices have the capability to directly
control acquisition using either an on-board timer or an external
triggering input. Comedi commands are used to control this kind
-of acquisition. The same structure (comedi_cmd) used to control
-acquisition is used to query the capabilities of a device.
+of acquisition. The <ref id="comedi_cmd" name="comedi_cmd"> structure is
+used to control acquisition and query the capabilities of a device
+(see also <ref id="comedi_command" name="comedi_command()">,
+<ref id="comedi_command_test" name="comedi_command_test()">, and
+<ref id="comedi_get_cmd_src_mask" name="comedi_get_cmd_src_mask()">).
Commands specify a particular data acquisition sequence, which
is comprised of a number of scans. Each scan is comprised of
event.
Each of these 5 types of events are caused by a triggering
-source. The source types are:
+source, specified through the *_src members of the
+<ref id="comedi_cmd" name="comedi_cmd"> structure. The source types are:
<itemize>
-<item>TRIG_NONE don't ever cause event
-<item>TRIG_NOW cause event to occur immediately
-<item>TRIG_FOLLOW (see notes below)
-<item>TRIG_TIME cause event to occur at a particular time
-<item>TRIG_TIMER cause event to occur repeatedly at a specific rate
-<item>TRIG_COUNT cause event when count reaches specific value
-<item>TRIG_EXT external signal causes event
-<item>TRIG_INT internal signal causes event
+<item>TRIG_NONE: don't ever cause an event, sometimes used as a stop_src.
+<item>TRIG_NOW: cause event to occur immediately, the most common start_src.
+It is also used sometimes as a convert_src for 'burst mode' aquisition where
+the individual channels in a scan are scanned through as quickly as possible.
+<item>TRIG_FOLLOW: see notes below, usually used as a scan_begin_src.
+<item>TRIG_TIME: cause event to occur at a particular time
+<item>TRIG_TIMER: cause event to occur repeatedly at a specific rate, often
+used as a scan_begin_src or convert_src.
+<item>TRIG_COUNT: cause event when count reaches specific value, almost always
+used as the scan_end_src and often for stop_src.
+<item>TRIG_EXT: external signal causes event, used as start_src for externally
+triggered conversions, and as scan_begin_src or convert_src for externally paced
+conversions.
+<item>TRIG_INT: internal signal causes event, will probably be used as start_src
+for output commands in the future.
+</itemize>
+
+For every trigger, there is a corresponding
+argument (the *_arg members of the <ref id="comedi_cmd" name="comedi_cmd">
+structure) whose meaning depends on the type of trigger. The meanings
+of the arguments are as follows:
+
+<itemize>
+<item>trigger src = TRIG_NONE: argument has no meaning
+<item>trigger src = TRIG_NOW: argument is the delay in nanoseconds before triggering
+<item>trigger src = TRIG_FOLLOW: argument has no meaning
+<item>trigger src = TRIG_TIME: argument is the time at which to trigger (in what units??),
+but no drivers support this yet.
+<item>trigger src = TRIG_TIMER: argument is the period in nanoseconds between triggers
+<item>trigger src = TRIG_COUNT: argument is the number of 'counts' per trigger.
+For comedi_cmd.stop_arg, this is the number of scans to perform before ending aquisition.
+For comedi_cmd.scan_end_arg, this is the number of conversions to perform per scan.
+<item>trigger src = TRIG_EXT: argument is the digital input channel to trigger on.
+<item>trigger src = TRIG_INT: argument meaning is unknown??
</itemize>
Not all triggers are applicable to all events. Supported triggers
for specific events depends significantly on your particular
-device. In addition, for every trigger type, there is a cooresponding
-argument that specifies the rate, the count, which external signal,
-etc.
+device.
TRIG_FOLLOW is a special type of trigger for scan_begin events that
triggers on the next lower level trigger, in this case, the trigger
for convert events. It may or may not be supported. Later, it may
also be used for start events if you want to chain multiple commands.
-In particular, scan_end events will almost always be triggered on
-TRIG_COUNT, with the argument being the number of channels in the
-scan. (Actually, samples in the scan, since on most boards you can
-measure a single channel multiple times in a scan.) Also, until
-otherwise supported, start events can only be TRIG_NOW.
+The chanlist member of the <ref id="comedi_cmd" name="comedi_cmd">
+structure should point to an array whose number of elements is specificed by chanlist_len
+(this will generally be the same as the scan_end_arg).
+The chanlist specifies the sequence of channels and gains (and analog references)
+that should be stepped through for each scan. The elements of the chanlist array
+should be initialized by packing the channel, range and reference information
+together with the <ref id="CR_PACK" name="CR_PACK(channel, range, aref)"> macro.
+
+The final member of the <ref id="comedi_cmd" name="comedi_cmd"> structure is 'flags'.
+The following flags are valid, and can be bitwise-or'd together.
+
+<itemize>
+<item>TRIG_BOGUS: do the motions??
+<item>TRIG_DITHER: enable dithering??
+<item>TRIG_DEGLITCH: enable deglitching??
+<item>TRIG_RT: ask driver to use a hard real-time interrupt handler. This will
+reduce latency in handling interrupts from your data aquisition hardware. It can
+be useful if you are sampling at high frequency, or if your hardware has a small onboard
+fifo. You must have a real-time kernel (RTAI or RTLinux) and must compile
+comedi with real-time support or this flag will do nothing.
+<item>TRIG_CONFIG: perform configuration, not triggering.
+<item>TRIG_WAKE_EOS: some drivers will change their behaviour when this flag is set,
+trying to transfer data at the end of every scan (instead of, for example, passing
+data in chunks whenever the board's onboard fifo is half full). This flag
+may degrade a driver's performance at higher frequencies.
+<item>TRIG_WRITE: write to bidirectional devices. Could be useful in principle, if someone
+wrote a driver that supported commands for a digital i/o device that could do either
+input or output.
+</itemize>
+There are also a few flags that indicate how timing arguments should be rounded
+if the hardware cannot achieve the exact timing requested.
+<itemize>
+<item>TRIG_ROUND_NEAREST: round to nearest supported timing period, the default.
+<item>TRIG_ROUND_DOWN: round period down.
+<item>TRIG_ROUND_UP: round period up.
+<item>TRIG_ROUND_UP_NEXT: this one doesn't do anything, and I don't know what it was intended
+to do??
+</itemize>
+
+<p>
+
+
+<sect>Libcomedi Reference
+<p>
+
+<sect1>Constants and Macros
+<p>
+
+<sect2>CR_PACK(channel, range, aref)
+<label id="CR_PACK">
+<p>
+
+undocumented
+
+<sect2>RANGE_LENGTH() <it/(deprecated)/
+<p>
+<label id="RANGE_LENGTH">
+
+<tt/RANGE_LENGTH(rangetype)/
+
+<p>
+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.
+
+<p>
+The RANGE_LENGTH() macro returns the length of the array that is
+specified by the rangetype token.
+
+<p>
+The RANGE_LENGTH() 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.
+
+
+<p>
+<sect1>Data Types and Structures
+
+<p>
+<sect2>comedi_t
+<label id="comedi_t">
+
+<p>
+The data type <tt/comedi_t/ is used to represent an open Comedi
+device. A valid <tt/comedi_t/ pointer is returned by a successful
+call to <tt/comedi_open()/, and should be used for subsequent
+access to the device.
+It is a transparent type, and pointers to type <tt/comedi_t/
+should not be dereferenced by the application.
+
+
+<p>
+<sect2>sampl_t
+<label id="sampl_t">
+
+<p>
+The data type <tt/sampl_t/ is one of the generic types used to represent
+data values in libcomedi. It is used in a few places where a shorter
+data type is useful, but is limited to 16 bits on the i386 architecture.
+
+
+<p>
+<sect2>lsampl_t
+<label id="lsampl_t">
+
+<p>
+The data type <tt/lsampl_t/ is one of the generic types used to represent
+data values in libcomedi. It is currently defined to be <tt/unsigned int/.
+
+
+
+
+<p>
+<sect2>comedi_trig_struct <it/(deprecated)/
+<label id="comedi_trig_struct">
+<p>
+
+The <tt/comedi_trig/ structure
+
+<tscreen><verb>
+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 */
+ sampl_t *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];
+}
+</verb></tscreen>
+
+The <tt/comedi_trig/ structure is a control structure used by the
+COMEDI_TRIG ioctl, an older method of communicating
+instructions to the driver and hardware. Use of comedi_trig is
+deprecated, and should not be used in new applications.
+
+<p>
+This structure is defined as part of the Comedi kernel interface.
+
+<p>
+<sect2>comedi_sv_t
+<label id="comedi_sv_t">
+<p>
+
+<tscreen><verb>
+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;
+}
+</verb></tscreen>
+
+The <tt/comedi_sv_t/ structure is used by the <tt/comedi_sv_*()/
+functions to provide a simple method of accurately measuring
+slowly varying inputs. See the relevant section for more
+details.
+
+
+<p>
+<sect2>comedi_cmd
+<label id="comedi_cmd">
+<p>
+
+undocumented
+
+<p>
+Related functions are described in section XXX.
+
+<p>
+This structure is defined as part of the Comedi kernel interface.
+
+<p>
+<sect2>comedi_insn
+<label id="comedi_insn">
+<p>
+
+undocumented
+
+<p>
+Related functions are described in section XXX.
+
+<p>
+This structure is defined as part of the Comedi kernel interface.
+
+
+<p>
+<sect2>comedi_range
+<label id="comedi_range">
+<p>
+
+undocumented
+
+
+
+<sect1>Functions
+<p>
+
+<sect2>comedi_close()
+<label id="comedi_close">
+<p>
+
+<tt>void comedi_close(comedi_t *it);</tt>
+
+<p>
+Closes a device previously opened by comedi_open().
+
+<p>
+The return type of this function will change to <tt/int/, in
+order to match <tt/fclose/.
+
+<p>
+Source: <tt>/lib/comedi.c</tt>
+
+
+<sect2>comedi_command()
+<label id="comedi_command">
+<p>
+
+<tt>int comedi_command(comedi_t *it, comedi_cmd *cmd);</tt>
+<p>
+undocumented
+<p>
+Source: <tt>/lib/comedi.c</tt>
+
+
+<sect2>comedi_command_test()
+<label id="comedi_command_test">
+<p>
+
+<tt>int comedi_command_test(comedi_t *it, comedi_cmd *cmd);</tt>
+<p>
+undocumented
+<p>
+Source: <tt>/lib/comedi.c</tt>
+
+
+<sect2>comedi_data_read()
+<label id="comedi_data_read">
+<p>
+
+<tt>int comedi_data_read(comedi_t *it,unsigned int subd,unsigned int chan,
+ unsigned int range,unsigned int aref,lsampl_t *data);</tt>
+
+<p>
+Reads a single sample on the channel that
+is specified by the comedi device <tt>it</tt>, the
+subdevice <tt>subd</tt>, and the channel <tt>chan</tt>.
+For the A/D conversion (if appropriate),
+the device is configured to use range specification
+<tt>range</tt> and (if appropriate) analog reference type
+<tt>aref</tt>. Analog reference types that are not supported
+by the device are silently ignored.
+
+<p>
+<tt>comedi_data_read()</tt> reads one data value from
+the specified channel and places the
+data value that is read in the location pointed to by
+<tt>data</tt>.
+
+<p>
+On sucess, <tt>comedi_data_read()</tt> returns 0. If there is an
+error, -1 is returned.
+
+<p>
+Valid analog reference numbers are:
+
+<itemize>
+<item>AREF_GROUND Reference to analog ground
+<item>AREF_COMMON Reference to analog common
+<item>AREF_DIFF Differential reference
+<item>AREF_OTHER Board-specific meaning
+</itemize>
+
+Valid data values returned by these function is an unsigned integer
+less than or equal to <tt>maxdata</tt>, which is channel-dependent.
+Conversion of these data value to physical units can be performed
+by <tt><ref id="comedi_to_phys" name =
+"comedi_to_phys()"></tt>.
+
+Source: <tt>/lib/data.c</tt>
+
+
+<sect2>comedi_data_write()
+<p>
+
+<tt>int comedi_data_write(comedi_t *it,unsigned int subd,unsigned int chan,
+ unsigned int range,unsigned int aref,lsampl_t data);</tt>
+
+<p>
+Writes a single sample on the channel that
+is specified by the comedi device <tt/it/, the
+subdevice <tt/subd/, and the channel <tt/chan/.
+For the D/A conversion (if appropriate), the device is
+configured to use range specification
+<tt/range/ and (if appropriate) analog reference type
+<tt/aref/. Analog reference types that are not supported
+by the device are silently ignored.
+
+<tt/comedi_data_write()/ writes the data value
+specified by the argument <tt/data/ to
+the specified channel.
+
+On sucess, <tt>comedi_data_write()</tt> returns 0. If there is an error, -1 is
+returned.
+
+Valid analog reference numbers are:
+
+<itemize>
+<item>AREF_GROUND Reference to analog ground
+<item>AREF_COMMON Reference to analog common
+<item>AREF_DIFF Differential reference
+<item>AREF_OTHER Board-specific meaning
+</itemize>
+
+Valid data values used by these functions is an unsigned integer
+less than or equal to <tt>maxdata</tt>, which is channel-dependent.
+Conversion of physical units to these data value can be performed
+by <tt><ref id="comedi_from_phys" name =
+"comedi_from_phys()"></tt>.
+
+Source: <tt>/lib/data.c</tt>
+
+
+<p>
+<sect2>comedi_dio_bitfield();
+
+<p>
+<tt/int comedi_dio_bitfield(comedi_t *it,unsigned int subd,unsigned
+int write_mask,unsigned int *bits);/
+
+<p>
+The function <tt/comedi_dio_bitfield()/ allows multiple channels to
+be read simultaneously from a digital input or digital I/O device.
+The parameter <tt/write_mask/ and the value pointed to by <tt/bits/
+are interpreted as bit fields, with the least significant bit
+representing channel 0. For each bit in <tt/write_mask/ that is
+set, the cooresponding bit in <tt/*bits/ is written to the digital
+output channel. Each digital input channel is read, and the result
+placed in the approprate bits in <tt/*bits/.
+
+<p>
+The current implementation reads and writes bits using separate
+system calls, which is not ideal. When the kernel driver supports
+simultaneous reading/writing, this will be fixed in the library.
+
+<p>
+It should be noted that it is not possible to access channels
+greater than 31 using this function.
+
+<p>
+Source: <tt>/lib/dio.c</tt>
+
+
+<p>
+<sect2>comedi_dio_config()
+<p>
+<tt/int comedi_dio_config(comedi_t *it,unsigned int subd,unsigned
+int chan,unsigned int dir);/
+
+<p>
+The function <tt/comedi_dio_config/ configures individual channels
+in a digital I/O subdevice to be either input or output, depending
+on the value of parameter <tt/dir/. Depending on the capabilities
+of the hardware device, multiple channels may be affected by
+a single call to <tt/comedi_dio_config/.
+
+
+Valid directions are:
+<itemize>
+<item> COMEDI_INPUT
+<item> COMEDI_OUTPUT
+</itemize>
+
+Source: <tt>/lib/dio.c</tt>
+
+
+<p>
+<sect2>comedi_dio_read()
+<p>
+<tt/int comedi_dio_read(comedi_t *it,unsigned int subd,unsigned int
+chan,unsigned int *bit);/
+
+<p>
+The function reads the status of channel <tt/chan/ belonging to the digital
+input subdevice <tt/subd/ of device <tt/it/. The result, 0 or 1, is stored
+in bit. Returns -1 on failure.
+
+<p>
+This function is equivalent to <tt/comedi_data_read(it,subd,chan,0,0,bit)/.
+
+
+Source: <tt>/lib/dio.c</tt>
+
+<p>
+<sect2>comedi_dio_write()
+<p>
+<tt/int comedi_dio_write(comedi_t *it,unsigned int subd,unsigned
+int chan,unsigned int bit);/
+
+<p>
+The function writes the value of <tt/bit/, 0 or 1, to channel <tt/chan/,
+belonging to the digital output device <tt/subd/ of device <tt/it/. Returns
+-1 on failure.
+
+<p>
+Source: <tt>/lib/dio.c</tt>
+
+<p>
+<sect2>comedi_fileno()
+<p>
+
+<tt/int comedi_fileno(comedi_t *it);/
+<p>
+
+The function <tt/comedi_fileno/
+returns the integer descriptor for the handle <tt/it/. It
+is equivalent to the standard function <tt/fileno/. If
+<tt>it</tt> is an invalid <tt>comedi_t</tt> pointer, the function
+returns -1 and sets the appropriate libcomedi error value.
+
+Source: <tt>/lib/comedi.c</tt>
+
+
+<p>
+<sect2>comedi_find_range()
+<p>
+
+<tt/int comedi_find_range(comedi_t *it, unsigned int subdevice, unsigned
+int chan, unsigned int unit, double min, double max);/
+
+<p>
+The function <tt/comedi_find_range/ tries to
+locate the optimal (smallest) range for the channel <tt>chan</tt>
+belonging to a <tt>subdevice</tt> of the comedi device <tt>it</tt>,
+that includes both <tt>min</tt> and <tt>max</tt> in <tt>units</tt>.
+If it finds a matching range, it returns its index. If no
+matching range is available, it returns -1.
+
+<p>
+Valid units are:
+
+<itemize>
+<item>UNIT_volt
+<item>UNIT_mA
+<item>UNIT_none
+</itemize>
+
+Source: <tt>/lib/range.c</tt>
+
+
+<p>
+<sect2>comedi_errno()
+<label id="comedi_errno">
+<p>
+<tt/int comedi_errno(void);/
+
+<p>
+The function <tt>comedi_errno()</tt>
+returns an integer describing the most recent comedilib error. This
+integer may be used as the <tt>errnum</tt> parameter for
+<tt><ref id="comedi_strerror" name ="comedi_strerror()"></tt>.
+
+When a libcomedi 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
+<tt>comedi_errno()</tt>. This error number can be
+converted to a human-readable form by the functions
+<tt><ref id="comedi_perror" name ="comedi_perror()"></tt>
+ and <tt><ref id="comedi_strerror" name ="comedi_strerror()"></tt>.
+
+These functions are intended to mimic the behavior of the
+standard C library functions <tt>perror()</tt>,
+<tt>strerror</tt>, and <tt>errno()</tt>. In particular,
+libcomedi functions sometimes return an error that is generated
+by the C library; the Comedi error message in this case
+is the same as the C library.
+
+Source: <tt>/lib/error.c</tt>
+
+
+<p>
+<sect2>comedi_find_subdevice_by_type()
+<p>
+
+<tt>int comedi_find_subdevice_by_type(comedi_t *it,int type,unsigned int
+start_subdevice);</tt>
+
+<p>
+The function <tt>comedi_find_subdevice_by_type</tt> tries to
+locate a subdevice belonging to comedi device <tt>it</tt>,
+having type <tt>type</tt>, starting with the subdevice
+<tt>start_subdevice</tt>. 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
+<tt><ref id="comedi_get_subdevice_type" name =
+"comedi_get_subdevice_type()"></tt>.
+
+Source: <tt>/lib/get.c</tt>
+
+
+<p>
+<sect2>comedi_from_phys()<label id="comedi_from_phys">
+<p>
+
+<tt/lsampl_t comedi_from_phys(double data, comedi_range *rng,
+lsampl_t maxdata);/
+
+Converts data given in physical units (<tt/data/) into sample values
+(lsampl_t, between 0 and maxdata). The parameter <tt>rng</tt>
+represents the conversion information to use, and the parameter
+<tt>maxdata</tt> represents the maximum possible data value for the
+channel that the data will be written to.
+
+
+Source: <tt>/lib/range.c</tt>
+
+
+<p>
+<sect2>comedi_get_board_name()
+<p>
+
+<tt/char *comedi_get_board_name(comedi_t *it);/
+
+The function <tt/comedi_get_board_name/ returns a pointer
+to a string containing the name of the device. This pointer is
+valid until the comedi descriptor <tt/it/ is closed. This
+function returns <tt/NULL/ if there is an error.
+
+Source: <tt>/lib/get.c</tt>
+
+
+<sect2>comedi_get_cmd_src_mask()
+<label id="comedi_get_cmd_src_mask">
+<p>
+
+<tt>int comedi_get_cmd_src_mask(comedi_t *dev, unsigned int subdevice,
+comedi_cmd *cmd);</tt>
+
+undocumented
+
+Source: <tt>/lib/cmd.c</tt>
+
+
+<sect2>comedi_get_driver_name()
+<p>
+
+<tt/char *comedi_get_driver_name(comedi_t *it);/
+
+The function <tt/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 <tt/it/. This pointer is
+valid until the comedi descriptor <tt/it/ is closed. This
+function returns <tt/NULL/ if there is an error.
+
+Source: <tt>/lib/get.c</tt>
+
+
+<p>
+<sect2>comedi_get_maxdata()
+<p>
+
+<tt/lsampl_t comedi_get_maxdata(comedi_t *it,unsigned int
+subdevice,unsigned int chan);/
+
+<p>
+The function <tt/comedi_get_maxdata()/ returns the maximum
+valid data value for channel <tt/chan/ of subdevice
+<tt/subdevice/ belonging to the comedi device <tt/it/
+This function returns 0 on error.
+
+Source: <tt>/lib/get.c</tt>
+
+
+<p>
+<sect2>comedi_get_n_channels()
+<p>
+
+<tt/int comedi_get_n_channels(comedi_t *it,unsigned int subdevice);/
+
+The function <tt>comedi_get_n_channels()</tt> returns the number
+of channels of the subdevice belonging to the comedi device <tt>it</tt>
+and having index <tt>subdevice</tt>. This function returns -1 on error.
+
+Source: <tt>/lib/get.c</tt>
+
+
+<p>
+<sect2>comedi_get_n_ranges()
+<p>
+
+<tt>int comedi_get_n_ranges(comedi_t *it,unsigned int subdevice, unsigned int
+chan);</tt>
+
+The function <tt>comedi_get_n_ranges()</tt> returns the number
+of ranges of the channel <tt>chan</tt> belonging to the <tt>subdevice</tt>
+of the comedi device <tt>it</tt>. This function returns -1 on error.
+
+Source: <tt>/lib/range.c</tt>
+
+
+<p>
+<sect2>comedi_get_n_subdevices()
+<p>
+
+<tt>int comedi_get_n_subdevices(comedi_t *it);</tt>
+
+The function <tt>comedi_get_n_subdevices</tt> returns the
+number of subdevices associated with the comedi descriptor
+<tt>it</tt>, or -1 if there is an error.
+
+Source: <tt>/lib/get.c</tt>
+
+
+<p>
+<sect2>comedi_get_range()
+<p>
+
+<tt>comedi_range * comedi_get_range(comedi_t *it,unsigned int subdevice,unsigned int chan,unsigned int
+range);</tt>
+
+The function <tt>comedi_get_range</tt> 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 <tt>it</tt> is closed. If there is an
+error, NULL is returned.
+
+Source: <tt>/lib/get.c</tt>
+
+<p>
+<sect2>comedi_get_rangetype() <it/deprecated/
+<p>
+
+<tt>int comedi_get_rangetype(comedi_t *it,unsigned int subdevice,unsigned int
+chan);</tt>
+
+The function <tt>comedi_get_rangetype()</tt> returns an integer
+that represents the number of range specifications available for a
+particular channel <tt/chan/ of the subdevice <tt/subdevice/, as well as a conversion table to convert sample
+values to/from physical units.
+
+ The macro
+<tt>RANGE_LENGTH(rangetype)</tt>
+can be used to determine the number of range specifications for a given
+range type.
+
+<p>
+This function is deprecated and should not be used in new code.
+
+Source: <tt>/lib/get.c</tt>
+
+<p>
+<sect2>comedi_get_subdevice_type()<label id="comedi_get_subdevice_type">
+<p>
+
+<tt>int comedi_get_subdevice_type(comedi_t *it,unsigned int subdevice);</tt>
+
+The function <tt>comedi_get_subdevice_type()</tt> returns an
+integer describing the type of subdevice that belongs to the comedi
+device <tt>it</tt> and has the index <tt>subdevice</tt>. The
+function returns -1 is there is an error.
+
+Valid subdevice types are:
+
+<itemize>
+<item><tt>COMEDI_SUBD_UNUSED</tt>
+Subdevice has no functionality, i.e., a place-holder.
+<item><tt>COMEDI_SUBD_AI</tt> Analog input
+<item><tt>COMEDI_SUBD_AO</tt> Analog output
+<item><tt>COMEDI_SUBD_DI</tt> Digital input
+<item><tt>COMEDI_SUBD_DO</tt> Digital output
+<item><tt>COMEDI_SUBD_DIO</tt>
+Digital input/output. Channels are configurable as to whether they
+are inputs or outputs.
+<item><tt>COMEDI_SUBD_COUNTER</tt> Counter
+<item><tt>COMEDI_SUBD_TIMER</tt> Timer
+<item><tt>COMEDI_SUBD_MEMORY</tt>
+Memory, e.g., EEPROM or dual-ported RAM
+<item><tt>COMEDI_SUBD_CALIB</tt>
+Calibration DACs
+<item><tt>COMEDI_SUBD_PROC</tt>
+Processor or DSP
+</itemize>
+
+Source: <tt>/lib/get.c</tt>
+
+<p>
+<sect2>comedi_get_timer() <it/(deprecated)/
+<p>
+
+<tt/int comedi_get_timer(comedi_t *it,unsigned int subdev, double
+freq,unsigned int *trigvar, double *actual_freq);/
+
+<p>
+The function <tt>comedi_get_timer</tt> converts the frequency <tt/freq/
+to a number suitable to send to the driver in a <tt/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 <tt/nanosec_timer/, indicating
+that timer values are simply a time specified in nanoseconds.
+
+<p>
+This function is deprecated and should not be used in new applications.
+
+<p>
+Source: <tt>/lib/timer.c</tt>
+
+<p>
+<sect2>comedi_get_version_code()
+<p>
+
+<tt/int comedi_get_version_code(comedi_t *it);/
+
+<p>
+The function <tt/comedi_get_version_code()/ returns the
+version code of the currently running comedi module. The version
+code is of the form 0x01072b, which is the version code for
+version 1.7.43.
+
+<p>
+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 libcomedi source.
+
+Source: <tt>/lib/get.c</tt>
+
+<p>
+<sect2>comedi_loglevel()
+<P>
+
+<tt>int comedi_loglevel(int loglevel);</tt>
+
+<p>
+This function affects the output of debugging and error messages
+from libcomedi. By increasing the loglevel, additional debugging
+information will be printed. This function returns the previous
+loglevel. Error messages and debugging are printed to the
+stream <tt/stderr/. The loglevel can also be affected by the
+environment variable COMEDI_LOGLEVEL.
+
+<p>
+In order to conserve resources, some debugging information is
+disabled when libcomedi is compiled.
+
+<p>The meaning of the loglevels is as follows:
+
+<itemize>
+<item><tt/COMEDILIB_LOGLEVEL=0/
+
+Comedilib prints nothing.
+
+<item><tt/COMEDILIB_LOGLEVEL=1/ (default)
+
+Comedilib only prints error messages when there is a
+self-consistency error (i.e., internal bug).
+
+<item><tt/COMEDILIB_LOGLEVEL=2/
+
+Comedilib prints an error message when an invalid
+parameter is passed to comedilib.
+
+<item><tt/COMEDILIB_LOGLEVEL=3/
+
+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.
+
+<item><tt/COMEDILIB_LOGLEVEL=4/
+
+Comedilib prints a lot of debugging messages.
+
+</itemize>
+
+Bugs: Libcomedi doesn't currently have much debugging information.
+
+Source: <tt>/lib/error.c</tt>
+
+<p>
+<sect2>comedi_open()
+<p>
+
+<tt/comedi_t *comedi_open(char *filename);/
+
+Opens a comedi device specified by the filename <tt/filename/.
+Returns NULL on error. On sucess, it returns a handle that is
+given as a parameter to other libcomedi functions.
+
+<p>
+You are not supposed to have access to the internals of the
+<tt/comedi_t/ structure.
+
+Bugs: Not strictly identical to <tt/fopen/
+
+Source: <tt>/lib/comedi.c</tt>
+
+
+<p>
+<sect2>comedi_perror()<label id="comedi_perror">
+<p>
+
+<tt>void comedi_perror(const char *s);</tt>
+
+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
+<tt><ref id="comedi_errno" name ="comedi_errno()"></tt>.
+ This error number can be
+ converted to a human-readable form by the functions
+<tt>comedi_perror()</tt>
+ and <tt><ref id="comedi_strerror" name ="comedi_strerror()"></tt>.
+
+These functions are intended to mimic the behavior of the
+standard C library functions <tt>perror()</tt>,
+<tt>strerror</tt>, and <tt>errno()</tt>. 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 <tt>comedi_perror()</tt> 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.
+
+Bugs: Does not support internationalization.
+
+Source: <tt>/lib/error.c</tt>
+
+
+<p>
+<sect2>comedi_strerror()<label id="comedi_strerror">
+<p>
+
+<tt>*comedi_strerror(int errnum);</tt>
+
+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
+<tt><ref id="comedi_errno" name ="comedi_errno()"></tt>. This error number can be
+converted to a human-readable form by the functions
+<tt><ref id="comedi_perror" name ="comedi_perror()"></tt>
+ and <tt>comedi_strerror()</tt>.
+
+These functions are intended to mimic the behavior of the
+standard C library functions <tt>perror()</tt>,
+<tt>strerror</tt>, and <tt>errno()</tt>. 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 <tt>comedi_strerror()</tt> returns a pointer to a
+character string
+describing the comedilib error <tt>errnum</tt>. The persistence
+of the returned pointer is undefined, and should not be trusted
+after the next libcomedi call. An unrecognized error number will
+return a pointer to the string "undefined error", or similar.
+
+Bugs: Does not support internationalization.
+
+Source: <tt>/lib/error.c</tt>
+
+
+<p>
+<sect2>comedi_sv_init()
+<p>
+
+<tt/int comedi_sv_init(comedi_sv_t *sv,comedi_t *dev,unsigned int subd,
+unsigned int chan);/
+
+
+<tt/comedi_sv_init/ initializes the slow varying comedi structure
+<tt/sv/ of the device <tt/dev/, the subdevice <tt/subd/ (analog input) and
+the channel <tt/chan/.
+The slow varying comedi structure <tt/sv/ of type <tt><ref id="comedi_sv_t"
+name="comedi_sv_t"</tt>
+specifies the signal measurement. The default number of averaged
+samples is 100. Returns zero on success, -1 on error.
+
+Bugs: comedi_sv_* was very poorly designed.
+Source: <tt>/lib/sv.c</tt>
+<p>
+<sect2>comedi_sv_update()
+<p>
+
+<tt/int comedi_sv_update(comedi_sv_t *sv);/
+
+The function <tt/comedi_sv_update/ updates the slow varying comedi structure
+<tt/sv/.
+Returns zero on success, -1 on error.
+
+Source: <tt>/lib/sv.c</tt>
+
+
+<p>
+<sect2>int comedi_sv_measure()
+<p>
+
+<tt>int comedi_sv_measure(comedi_sv_t *it,double *data);</tt>
+
+<tt/comedi_sv_measure/ measures the slow variing signal. The measurement
+is specified by the slow varying comedi structure <tt/sv/, the result is
+stored in <tt/data/.
+On success returns the number of samples, -1 on error.
+
+Source: <tt>/lib/sv.c</tt>
+
+
+<p>
+<sect2>comedi_to_phys()<label id="comedi_to_phys">
+<p>
+
+<tt/double comedi_to_phys(lsampl_t data, comedi_range *rng,
+lsampl_t maxdata);/
+
+Converts data given in sample values (lsampl_t, between 0 and
+maxdata) into physical units (double). The parameter <tt/rng/
+represents the conversion information to use, and the parameter
+<tt/maxdata/ represents the maximum possible data value for the
+channel that the data was read.
+
+Source: <tt>/lib/range.c</tt>
+
+
+<p>
+<sect2>comedi_trigger() <it/(deprecated)/
+<p>
+
+<tt/int comedi_trigger(comedi_t *it,comedi_trig *trig);/
+
+The function <tt/comedi_trigger/ instructs comedi to
+perform the command specified by the <ref id="comedi_trig_struct" name
+="trigger structure"> <tt/trig/. Results depend on
+the particular command being issued. If there is an
+error, -1 is returned.
+
+Lifetime: removal at 1.0.
+
+Source: <tt>/lib/comedi.c</tt>
+
+
+<p>
+<sect2>comedi_get_subdevice_flags()
+<label id="comedi_get_subdevice_flags">
+<p>
+
+<tt/int comedi_get_subdevice_flags(comedi_t *dev, unsigned int subdevice);/
+
+<p>
+This function returns a bitfield describing the capabilities of the
+specified subdevice. If there is an error, -1 is returned.
+
+<p>The bits are:
+
+<itemize>
+<item>SDF_BUSY subdevice is running a command
+<item>SDF_BUSY_OWNER subdevice is running a command started by
+the file descriptor used by <tt/dev/.
+<item>SDF_LOCKED subdevice is locked
+<item>SDF_LOCKED_OWNER subdevice is locked by the file descriptor used
+by <tt/dev/.
+<item>SDF_MAXDATA maximum data values are channel dependent
+<item>SDF_FLAGS channel flags are channel dependent
+<item>SDF_RANGETYPE range types are channel dependent
+<item>SDF_MODE0 deprecated
+<item>SDF_MODE1 deprecated
+<item>SDF_MODE2 deprecated
+<item>SDF_MODE3 deprecated
+<item>SDF_MODE4 deprecated
+<item>SDF_CMD subdevice supports commands
+<item>SDF_READABLE subdevice can be read from
+<item>SDF_WRITEABLE subdevice can be written to
+<item>SDF_RT deprecated
+<item>SDF_GROUND subdevice is capable of ground analog reference
+<item>SDF_COMMON subdevice is capable of common analog reference
+<item>SDF_DIFF subdevice is capable of differential analog reference
+<item>SDF_OTHER subdevice is capable of other analog reference
+<item>SDF_DITHER subdevice recognizes dither flag
+<item>SDF_DEGLITCH subdevice recognizes deglitch flag
+<item>SDF_MMAP deprecated
+<item>SDF_RUNNING subdevice is acquiring data (i.e., command has not
+completed)
+<item>SDF_LSAMPL subdevice uses samples of type lsampl_t (otherwise
+sampl_t)
+<item>SDF_PACKED subdevice uses bitfield samples (otherwise it uses
+one sample per channel)
+</itemize>
+
+
+
+<p>
+The bit definitions are part of the Comedi kernel interface.
<p>
+<sect2>comedi_range_is_chan_specific()
+<label id="comedi_range_is_chan_specific">
+<p>
+
+<tt/int comedi_range_is_chan_specific(comedi_t *dev,unsigned int subdevice);/
+
+<p>
+If each channel of the specified subdevice has a different range
+specification, this function returns 1. Otherwise, this function
+returns 0. On error, this function returns -1.
+
+
+<p>
+<sect2>Undocumented functions
+<label id="undocumented">
+<p>
+
+
+<itemize>
+<item>comedi_maxdata_is_chan_specific()
+<item>comedi_get_buffer_size()
+<item>comedi_get_max_buffer_size()
+<item>comedi_set_buffer_size()
+<item>comedi_set_max_buffer_size()
+<item>comedi_do_insnlist()
+<item>comedi_do_insn()
+<item>comedi_lock()
+<item>comedi_unlock()
+<item>comedi_get_cmd_src_mask()
+<item>comedi_get_cmd_generic_timed()
+<item>comedi_cancel()
+<item>comedi_command()
+<item>comedi_command_test()
+<item>comedi_poll()
+<item>comedi_get_buffer_contents()
+<item>comedi_mark_buffer_read()
+<item>comedi_get_buffer_offset()
+<item>comedi_set_global_oor_behavior()
+</itemize>
+
+
</article>
projects / comedilib.git / commitdiff