Specifications

Comedi

16 / 148

Most functions specify the range to be used for a channel by a zero-based index into the list of ranges supported by the

channel. Depending on the device and subdevice, different channels on the subdevice may or may not share the same list of

ranges, that is, ranges may or may not be channel-speciﬁc. (The SDF_RANGETYPE subdevice ﬂag indicates whether ranges

are channel-speciﬁc.)

Each single acquisition by, for example, comedi_data_read() requires quite some overhead, because all the arguments of

the function call are checked. If multiple acquisitions must be done on the same channel, this overhead can be avoided by using

a function that can read more than one sample, comedi_data_read_n():

int comedi_data_read_n(comedi_t *device, unsigned int subdevice, unsigned int channel, unsigned int range, unsigned int aref,

lsampl_t *data, unsigned int n);

The number of samples, n, is limited by the Comedi implementation (to a maximum of 100 samples), because the call is blocking.

The start of the a single data acquisition can also be delayed by a speciﬁed number of nano-seconds using the function comed-

i_data_read_delayed():

int comedi_data_read_delayed(comedi_t *device, unsigned int subdevice, unsigned int channel, unsigned int range, unsigned

int aref, lsampl_t *data, unsigned int nano_sec);

All these read and write acquisition functions are implemented on top of the generic instruction command.

4.2 Instructions for multiple acquisitions

The instruction is one of the most generic, overloaden and ﬂexible functions in the Comedi API. It is used to execute a multiple

of identical acquisitions on the same channel, but also to perform a conﬁguration of a channel. An instruction list is a list

of instructions, possibly on different channels. Both instructions and instructions lists are executed synchronously, i.e., while

blocking the calling process. This is one of the limitations of instructions; the other one is that they cannot code an acquisition

involving timers or external events. These limits are eliminated by the command acquisition primitive.

4.2.1 The instruction data structure

All the information needed to execute an instruction is stored in the comedi_insn data structure:

typedef struct comedi_insn_struct {

unsigned int insn; // integer encoding the type of acquisition

// (or configuration)

unsigned int n; // number of elements in data array

lsampl_t

data; // pointer to data buffer

unsigned int subdev; // subdevice

unsigned int chanspec; // encoded channel specification

unsigned int unused[3];

} comedi_insn;

Because of the large ﬂexibility of the instruction function, many types of instruction do not need to ﬁll in all ﬁelds, or attach

different meanings to the same ﬁeld. But the current implementation of Comedi requires the data ﬁeld to be at least one byte

long.

The insn member of the instruction data structure determines the type of acquisition executed in the corresponding instruction:

• INSN_READ: the instruction executes a read on an analog channel.

• INSN_WRITE: the instruction executes a write on an analog channel.

• INSN_BITS: indicates that the instruction must read or write values on multiple digital I/O channels.

• INSN_GTOD: the instruction performs a ‘Get Time Of Day’ acquisition.

• INSN_WAIT: the instruction blocks for a speciﬁed number of nanoseconds.