4.2. Instructions for multiple acquisitions
Prev | 4. Acquisition and configuration functions | Next

### 4.2. Instructions for multiple acquisitions

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.

Prev | Up | Next
4. Acquisition and configuration functions | Home | 4.3. Instructions for configuration