4.2.  Instructions for multiple acquisitions

4.2.1. The instruction data structure
4.2.2. Instruction execution

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.

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

4.2.2.  Instruction execution

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.