The instruction is one of the most generic, overloaden and flexible functions in the Comedi API. It is used to execute a multiple of identical acquisitions on the same channel, but also to perform a configuration 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.
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 flexibility of the instruction function, many
types of instruction do not need to fill in all fields, or attach
different meanings to the same field. But the current implementation
of Comedi requires the
data
field 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 specified
number of nanoseconds.
Once an instruction data structure has been filled in, the
corresponding instruction is executed with the function
comedi_do_insn:
int comedi_do_insn( | comedi_t *device, |
comedi_insn *instruction); |
Many Comedi instructions are shortcuts that relieve the programmer
from explicitly filling in the data structure and calling the
comedi_do_insn
function.
A list of instructions can be executed in one function call using the function
comedi_do_insnlist:
int comedi_do_insnlist( | comedi_t *device, |
comedi_insnlist *list); |
The parameter list is a pointer to a
comedi_insnlist
data structure holding a pointer to an array of comedi_insn
and the number of instructions in the list:
typedef struct comedi_insnlist_struct { unsigned int n_insns; comedi_insn *insns; } comedi_insnlist;
The number of instructions in the list is limited in the implementation, because instructions are executed synchronously, i.e., the call blocks until the whole instruction (list) has finished.