%comedilib_entities; ]>

All application programs must include the header file comedilib.h. (This file itself includes comedi.h.) They contain the full interface of &comedi;: defines, function prototypes, data structures. The following Sections give more details.

CR_PACKchanrng aref is used to initialize the elements of the chanlist array in the comedi_cmd data structure, and the chanspec member of the comedi_insn structure. The chan argument is the channel you wish to use, with the channel numbering starting at zero. The range rng is an index, starting at zero, whose meaning is device dependent. The comedi_get_n_ranges and comedi_get_range functions are useful in discovering information about the available ranges. The aref argument indicates what reference you want the device to use. It can be any of the following: AREF_GROUND is for inputs/outputs referenced to ground. AREF_COMMON is for a common reference (the low inputs of all the channels are tied together, but are isolated from ground). AREF_DIFF is for differential inputs/outputs. AREF_OTHER is for any reference that does not fit into the above categories. Particular drivers may or may not use the AREF flags. If they are not supported, they are silently ignored.

CR_PACK_FLAGSchanrange arefflags is similar to CR_PACK but can be used to combine one or more flag bits (bitwise-ORed together in the flags parameter) with the other parameters. Depending on context, the chan parameter might not be a channel; it could be a trigger source, clock source, gate source etc. (in which case, the range and aref parameters would probably be set to 0), and the flags would modify the source in some device-dependant way. The following flag values are defined: CR_ALT_FILTER CR_DITHER CR_DEGLITCH (all the same) specify that some sort of filtering is to be done on the channel, trigger source, etc. CR_ALT_SOURCE specifies that some alternate source is to be used for the channel (usually a calibration source). CR_EDGE is usually combined with a trigger source number to specify that the trigger source is edge-triggered if the hardware and driver supports both edge-triggering and level-triggering. If both are supported, not asserting this flag specifies level-triggering. CR_INVERT specifies that the trigger source, gate source, etc. is to be inverted.

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. The RANGE_LENGTHrangetype macro returns the length of the array that is specified by the rangetype token. 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.

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

enum comedi_io_direction { COMEDI_INPUT, COMEDI_OUTPUT }; A comedi_io_direction is used to select between input or output. For example, comedi_dio_config uses the COMEDI_INPUT and COMEDI_OUTPUT values to specify whether a configurable digital i/o channel should be configured as an input or output.

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

This Section explains the data structures that users of the &comedi; API are confronted with: typedef struct comedi_devinfo_struct comedi_devinfo; typedef struct comedi_t_struct comedi_t; typedef struct sampl_t_struct sampl_t; typedef struct lsampl_t_struct lsampl_t; typedef struct comedi_sv_t_struct comedi_sv_t; typedef struct comedi_cmd_struct comedi_cmd; typedef struct comedi_insn_struct comedi_insn; typedef struct comedi_range_struct comedi_range; typedef struct comedi_krange_struct comedi_krange; typedef struct comedi_insnlist_struct comedi_insnlist; The data structures used in the implementation of the &comedi; drivers are described in .

The data type comedi_devinfo is used to store information about a device. This structure is usually filled in automatically when the driver is loaded (attached), so programmers need not access this data structure directly. typedef struct comedi_devinfo_struct comedi_devinfo; struct comedi_devinfo_struct{ unsigned int version_code; // version number of the Comedi code unsigned int n_subdevs; // number of subdevices on this device char driver_name[COMEDI_NAMELEN]; char board_name[COMEDI_NAMELEN]; int read_subdevice; // index of subdevice whose buffer is read by read(), etc. on file descriptor from comedi_fileno() (negative means none) int write_subdevice; // index of subdevice whose buffer is written by write(), etc. on file descriptor from comedi_fileno() (negatove means none). int unused[30]; };

The data type comedi_t is used to represent an open &comedi; device: typedef struct comedi_t_struct comedi_t; A valid comedi_t pointer is returned by a successful call to comedi_open, and should be used for subsequent access to the device. It is an opaque type, and pointers to type comedi_t should not be dereferenced by the application.

typedef unsigned short sampl_t; The data type sampl_t is one of the generic types used to represent data values in Comedilib. It is used in a few places where a data type shorter than lsampl_t is useful. On most architectures it is a 16-bit, unsigned integer. Most drivers represent data transferred by read and write functions using sampl_t. Applications should check the subdevice flag SDF_LSAMPL to determine if the subdevice uses sampl_t or lsampl_t.

typedef unsigned int lsampl_t; The data type lsampl_t is the data type typically used to represent data values in Comedilib. On most architectures it is a 32-bit, unsigned integer.

typedef struct comedi_trig_struct comedi_trig; struct comedi_trig_struct{ unsigned int subdev; /* subdevice */ unsigned int mode; /* mode */ unsigned int flags; unsigned int n_chan; /* number of channels */ unsigned int *chanlist; /* channel/range list */ 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]; }; The 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 is no longer implemented by the &comedi; kernel layer.

typedef struct comedi_sv_struct comedi_sv_t; struct comedi_sv_struct{ comedi_t *dev; unsigned int subdevice; unsigned int chan; /* range policy */ int range; int aref; /* number of measurements to average (for ai) */ int n; lsampl_t maxdata; }; The comedi_sv_t structure is used by the comedi_sv_… functions to provide a simple method of accurately measuring slowly varying inputs. This relies on the COMEDI_TRIG ioctl and is no longer by the &comedi; kernel layer.

typedef struct comedi_cmd_struct comedi_cmd; struct comedi_cmd_struct{ unsigned int subdev; unsigned int flags; unsigned int start_src; unsigned int start_arg; unsigned int scan_begin_src; unsigned int scan_begin_arg; unsigned int convert_src; unsigned int convert_arg; unsigned int scan_end_src; unsigned int scan_end_arg; unsigned int stop_src; unsigned int stop_arg; unsigned int *chanlist; unsigned int chanlist_len; sampl_t *data; unsigned int data_len; }; More information on using commands can be found in the command section.

typedef struct comedi_insn_struct comedi_insn; struct comedi_insn_struct{ unsigned int insn; unsigned int n; lsampl_t*data; unsigned int subdev; unsigned int chanspec; unsigned int unused[3]; }; Comedi instructions are described by the comedi_insn structure. Applications send instructions to the driver in order to perform control and measurement operations that are done immediately or synchronously, i.e., the operations complete before program control returns to the application. In particular, instructions cannot describe acquisition that involves timers or external events. The field insn determines the type of instruction that is sent to the driver. Valid instruction types are: INSN_READ read values from an input channel INSN_WRITE write values to an output channel INSN_BITS read/write values on multiple digital I/O channels INSN_CONFIG configure a subdevice INSN_GTOD read a timestamp, identical to gettimeofday except the seconds and microseconds values are unsigned values of type lsampl_t. INSN_WAIT wait a specified number of nanoseconds The number of samples to read or write, or the size of the configuration structure is specified by the field n, and the buffer for those samples by data. The field subdev is the subdevice index that the instruction is sent to. The field chanspec specifies the channel, range, and analog reference (if applicable). Instructions can be sent to drivers using comedi_do_insn. Multiple instructions can be sent to drivers in the same system call using comedi_do_insnlist.

typedef struct comedi_range_struct comedi_range; struct comedi_range_struct{ double min; double max; unsigned int unit; }comedi_range; The comedi_range structure conveys part of the information necessary to translate sample values to physical units, in particular, the endpoints of the range and the physical unit type. The physical unit type is specified by the field unit, which may take the values UNIT_volt for volts, UNIT_mA for milliamps, or UNIT_none for unitless. The endpoints are specified by the fields min and max.

typedef struct comedi_krange_struct comedi_krange; struct comedi_krange_struct{ int min; int max; unsigned int flags; }; The comedi_krange structure is used to transfer range information between the driver and Comedilib, and should not normally be used by applications. The structure conveys the same information as the comedi_range structure, except the fields min and max are integers, multiplied by a factor of 1000000 compared to the counterparts in comedi_range. In addition, kcomedilib uses the comedi_krange structure in place of the comedi_range structure.

typedef struct comedi_insnlist_struct comedi_insnlist; struct comedi_insnlist_struct{ unsigned int n_insns; comedi_insn *insns; }; A comedi_insnlist structure is used to communicate a list of instructions to the driver using the comedi_do_insnlist function.

#define COMEDI_MAX_NUM_POLYNOMIAL_COEFFICIENTS 4 typedef struct { double coefficients[COMEDI_MAX_NUM_POLYNOMIAL_COEFFICIENTS]; double expansion_origin; unsigned order; } comedi_polynomial_t; A comedi_polynomial_t holds calibration data for a channel of a subdevice. It is initialized by the comedi_get_hardcal_converter or comedi_get_softcal_converter calibration functions and is passed to the comedi_to_physical and comedi_from_physical raw/physical conversion functions.