6. Comedi Reference

6.1.1. CR_PACK

CR_PACK is used to initialize the elements of the chanlist array in the comedi_cmd structure, and the chanspec member of the comedi_insn structure.

The channel argument is the channel you wish to use, with the channel numbering starting at zero.

The range 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:

Particular drivers may or may not use the AREF flags. If they are not supported, they are silently ignored.

6.1.2. RANGE_LENGTH (deprecated)

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_LENGTH() 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.

6.2.1. comedi_t

typedef struct comedi_t_struct comedi_t;

The data type comedi_t is used to represent an open Comedi device. 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 a transparent type, and pointers to type comedi_t should not be dereferenced by the application.

6.2.2. sampl_t

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, sampl_t is defined to be uint16.

Most drivers represent data trasferred by read() and write() using sampl_t. Applications should check the subdevice flag SDF_LSAMPL to determine if the subdevice uses sampl_t or lsampl_t.

6.2.3. lsampl_t

typedef unsigned int lsampl_t;

The data type lsampl_t is the data type typically used to represent data values in libcomedi. On most architectures, lsampl_t is defined to be uint32.

6.2.4. comedi_trig (deprecated)

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 should not be used in new applications.

6.2.5. comedi_sv_t

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. See the relevant section for more details.

6.2.6. comedi_cmd

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.

6.2.7. comedi_insn

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 preform 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

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().

6.2.8. comedi_range

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.

6.2.9. comedi_krange

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.

6.2.10. comedi_insnlist

typedef struct comedi_insnlist_struct comedi_insnlist;

struct comedi_insnlist_struct{
	unsigned int n_insns;
	comedi_insn *insns;
};

An instruction list (insnlist) structure is used to communicate a list of instructions.

6.3.1. Digital input combining machines

When one or several digital inputs are used to modify an output value, either an accumulator or a single digital line or bit, a bitfield structure is typically used in the Comedi interface. The digital inputs have two properties, "sensitive" inputs and "modifier" inputs. Edge transitions on sensitive inputs cause changes in the output signal, whereas modifier inputs change the effect of edge transitions on sensitive inputs. Note that inputs can be both modifier inputs and sensitive inputs.

For simplification purposes, it is assumed that multiple digital inputs do not change simultaneously.

The combined state of the modifier inputs determine a modifier state. For each combination of modifier state and sensitive input, there is a set of bits that determine the effect on the output value due to positive or negative transitions of the sensitive input. For each transition direction, there are two bits defined as follows:

For example, a simple digital follower is specified by the bit pattern 01 10, because it sets the output on positive transitions of the input, and clears the output on negative transitions. A digital inverter is similarily 10 01. These systems have only one sensitive input.

As another example, a simple up counter, which increments on positive transitions of one input, is specified by 01 00. This system has only one sensitive input.

When multiple digital inputs are used, the inputs are divided into two types, inputs which cause changes in the accumulator, and those that only modify the meaning of transitions on other inputs. Modifier inputs do not require bitfields, but there needs to be a bitfield of length 4*(2^(N-1)) for each edge sensitive input, where N is the total number of inputs. Since N is usually 2 or 3, with only one edge sensitive input, the scaling issues are not significant.

6.3.2. INSN_CONFIG

Configuration instructions are used to access device and driver features that do not fit well into other parts of the Comedi interface. This includes changing the direction of configurable digital I/O lines, configuring complex triggering engines, and counter/timer configuration.

If a specified ID is not supported, the driver must return -EINVAL.