4. Acquisition and configuration functions

This Section gives an overview of all Comedi functions with which application programmers can implement their data acquisition. (With "acquisition" we mean all possible kinds of interfacing with the cards: input, output, configuration, streaming, etc.) Section 7 explains the function calls in full detail.

4.1. Functions for single acquisition

The simplest form of using Comedi is to get one single sample to or from an interface card. This sections explains how to do such simple digital and analog acquisitions.

4.1.1. Single digital acquisition

Many boards supported by Comedi have digital input and output channels; i.e., channels that can only produce a 0 or a 1. Some boards allow the direction (input or output) of each channel to be specified independently in software.

Comedi groups digital channels into a subdevice, which is a group of digital channels that have the same characteristics. For example, digital output lines will be grouped into a digital output subdevice, bidirectional digital lines will be grouped into a digital I/O subdevice. Thus, there can be multiple digital subdevices on a particular board.

Individual bits on a digital I/O device can be read and written using the functions

  int comedi_dio_read(device,subdevice,channel,unsigned int *bit);
  int comedi_dio_write(device,subdevice,channel,unsigned int bit);
The device parameter is a pointer to a successfully opened Comedi device. The subdevice and channel parameters are positive integers that indicate which subdevice and channel is used in the acquisition. The integer bit contains the value of the acquired bit.

The direction of bidirectional lines can be configured using the function

  comedi_dio_config(device,subdevice,channel,unsigned int dir);
The parameter dir should be either COMEDI_INPUT or COMEDI_OUTPUT. Many digital I/O subdevices group channels into blocks for configuring direction. Changing one channel in a block changes the entire block.

Multiple channels can be read and written simultaneously using the function

  comedi_dio_bitfield(device,subdevice,unsigned int write_mask,unsigned int *bits);
Each channel is assigned to a bit in the write_mask and bits bitfield. If a bit in write_mask is set, the corresponding bit in *bits will be written to the corresponding digital output line. Each digital line is then read and placed into *bits. The value of bits in *bits corresponding to digital output lines is undefined and device-specific. Channel 0 is the least significant bit in the bitfield; channel 31 is the most significant bit. Channels higher than 31 cannot be accessed using this method.

The digital acquisition functions seem to be very simple, but, behind the implementation screens of the Comedi kernel module, they are executed as special cases of the general instruction command.

4.1.2. Single analog acquisition

Analog Comedi channels can produce data values that are samples from continuous analog signals. These samples are integers with a significant content in the range of, typically, 8, 10, 12, or 16 bits.

The

 int comedi_data_read(comedi_t * device, unsigned int subdevice, unsigned int channel, 
                    unsigned int range, unsigned int aref, lsampl_t * data);
function reads one such data value from a Comedi channel, and puts it in the user-specified data buffer. The
 int comedi_data_write(comedi_t * device, unsigned int subdevice, unsigned int channel, 
                       unsigned int range, unsigned int aref, lsampl_t data);
works in the opposite direction. Data values returned by this function are unsigned integers less than, or equal to, the maximum sample value of the channel, which can be determined using the function
 lsampl_t comedi_get_maxdata(comedi_t * device, unsigned int subdevice, unsigned int channel);
Conversion of data values to physical units can be performed by the function
 double comedi_to_phys(lsampl_t data, comedi_range * range,  lsampl_t maxdata);
There are two data structures in these commands that are not fully self-explanatory:

  • comedi_t: this data structure contains all information that a user program has to know about an open Comedi device. The programmer doesn't have to fill in this data structure manually: it gets filled in by opening the device.

  • lsampl_t: this "data structure" represents one single sample. On most architectures, it's nothing more than a 32 bits value. Internally, Comedi does some conversion from raw sample data to "correct" integers. This is called "data munging".

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:

  int comedi_data_read_n(comedi_t *it, unsigned int subdev, unsigned int chan, 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 data acquisition can also be delayed by a specified number of nano-seconds:

int comedi_data_read_delayed(comedi_t *it, unsigned int subdev, unsigned int chan, 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 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:

struct comedi_insn_struct{
  unsigned int insn;      // integer encoding the type of acquisition
                          // (or configuration)
  unsigned int n;         // number of samples
  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 flag 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 as follows:

 int comedi_do_insn(comedi_t *it, 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.

The

 int comedi_do_insnlistcomedi_t *it, comedi_insnlist * list)
instruction allows to perform a list of instructions in one function call. 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.

4.3. Instructions for configuration

Section 4.2 explains how instructions are used to do acquisition on channels. This section explains how they are used to configure a device. There are various sorts of configurations, and the specific information for each different configuration possibility is to be specified via the data buffer of the instruction data structure. (So, the pointer to a lsampl_t is misused as a pointer to an array with board-specific information.)

Using INSN_CONFIG as the insn flag in an instruction data structure indicates that the instruction will not perform acquisition on a channel, but will configure that channel. For example, the configuration of digital I/O channels is done as follows. The chanspec field in the comedi_insn data structure, contains the channel to be configured. And data[0] contains either COMEDI_INPUT or COMEDI_OUTPUT, depending on the desired direction of the digital I/O lines. On typical devices, multiple channels are grouped together in blocks for determining their direction. And configuring one channel in a block configures the entire block.

Another example of an INSN_CONFIG instruction is the configuration of the TRIG_OTHER event source.

4.4. Instruction for internal triggering

This special instruction has INSN_INTTRIG as the insn flag in its instruction data structure. Its execution causes an internal triggering event. This event can, for example, cause the device driver to start a conversion, or to stop an ongoing acquisition. The exact meaning of the triggering depends on the card and its particular driver.

The data[0] field of the INSN_INTTRIG instruction is reserved for future use, and should be set to "0".

4.5. Commands for streaming acquisition

The most powerful Comedi acquisition primitive is the command. It's powerful because, with one single command, the programmer launches:

This command functionality exists in the Comedi API, because various data acquisition devices have the capability to perform this kind of complex acquisition, driven by either on-board or off-board timers and triggers.

A command specifies a particular data acquisition sequence, which consists of a number of scans, and each scan is comprised of a number of conversions, which usually corresponds to a single A/D or D/A conversion. So, for example, a scan could consist of sampling channels 1, 2 and 3 of a particular device, and this scan should be repeated 1000 times, at intervals of 1 millisecond apart.

The command function is complementary to the configuration instruction function: each channel in the command's chanlist should first be configured by an appropriate instruction.

4.5.1. Executing a command

A commands is executed by the following Comedi function:

 int comedi_command(comedi_t * device,  comedi_cmd * command);
The following sections explain the meaning of the comedi_cmd data structure. Filling in this structure can be quite complicated, and requires good knowledge about the exact functionalities of the DAQ card. So, before launching a command, the application programmer is adviced to check whether this complex command data structure can be successfully parsed. So, the typical sequence for executing a command is to first send the command through comedi_command_test() once or twice. The test will check that the command is valid for the particular device, and often makes some adjustments to the command arguments, which can then be read back by the user to see the actual values used.

A Comedi program can find out on-line what the command capabilities of a specific device are, by means of the comedi_get_cmd_src_mask() function.

4.5.2. The command data structure

The command executes according to the information about the requested acquisition, which is stored in the comedi_cmd data structure:

typedef struct comedi_cmd_struct comedi_cmd;

struct comedi_cmd_struct{
  unsigned int subdev;         // which subdevice to sample
  unsigned int flags;          // encode some configuration possibilities 
                               // of the command execution; e.g.,
                               // whether a callback routine is to be
                               // called at the end of the command

  unsigned int start_src;      // event to make the acquisition start
  unsigned int start_arg;      // parameters that influence this start

  unsigned int scan_begin_src; // event to make a particular scan start
  unsigned int scan_begin_arg; // parameters that influence this start`

  unsigned int convert_src;    // event to make a particular conversion start
  unsigned int convert_arg;    // parameters that influence this start

  unsigned int scan_end_src;   // event to make a particular scan terminate
  unsigned int scan_end_arg;   // parameters that influence this termination

  unsigned int stop_src;       // what make the acquisition terminate
  unsigned int stop_arg;       // parameters that influence this termination

  unsigned int *chanlist;      // pointer to list of channels to be sampled
  unsigned int chanlist_len;   // number of channels to be sampled

  sampl_t *data;               // address of buffer
  unsigned int data_len;       // number of samples to acquire
};
The start and end of the whole command acquisition sequence, and the start and end of each scan and of each conversion, is triggered by a so-called event. More on these in Section 4.5.3.

The subdev member of the comedi_cmd() structure is the index of the subdevice the command is intended for. The comedi_find_subdevice_by_type() function can be useful in discovering the index of your desired subdevice.

The chanlist member of the comedi_cmd data structure should point to an array whose number of elements is specificed by chanlist_len (this will generally be the same as the scan_end_arg). The chanlist specifies the sequence of channels and gains (and analog references) that should be stepped through for each scan. The elements of the chanlist array should be initialized by "packing" the channel, range and reference information together with the CR_PACK() macro.

The data and data_len members can be safely ignored when issueing commands from a user-space program. They only have meaning when a command is sent from a kernel module using the kcomedilib interface, in which case they specify the buffer where the driver should write/read its data to/from.

The final member of the comedi_cmd structure is the flags field, i.e., bits in a word that can be bitwise-or'd together. The meaning of these bits are explained in a later section.

4.5.3. The command trigger events

A command is a very versatile acquisition instruction, in the sense that it offers lots of possibilities to let different hardware and software sources determine when acquisitions are started, performed, and stopped. More specifically, the command data structure has five types of events: start the acquisition, start a scan, start a conversion, stop a scan, and stop the acquisition. Each event can be given its own source (the *_src members in the comedi_cmd data structure). And each event source can have a corresponding argument (the *_arg members of the comedi_cmd data structure) whose meaning depends on the type of source trigger. For example, to specify an external digital line "3" as a source (in general, any of the five event sources), you would use src=TRIG_EXT and arg=3.

The following paragraphs discuss in somewhat more detail the trigger event sources(*_src), and the corresponding arguments (*_arg).

The start of an acquisition is controlled by the start_src events. The available options are:

  • TRIG_NOW: the start_src event occurs start_arg nanoseconds after the comedi_cmd is called. Currently, only start_arg=0 is supported.

  • TRIG_FOLLOW: (For an output device.) The start_src event occurs when data is written to the buffer.

  • TRIG_EXT: the start event occurs when an external trigger signal occurs; e.g., a rising edge of a digital line. start_arg chooses the particular digital line.

  • TRIG_INT: the start event occurs on a Comedi internal signal, which is typically caused by an INSN_INTTRIG instruction.

The start of the beginning of each scan is controlled by the scan_begin events. The available options are:

  • TRIG_TIMER: scan_begin events occur periodically. The time between scan_begin events is convert_arg nanoseconds.

  • TRIG_FOLLOW: The scan_begin event occurs immediately after a scan_end event occurs.

  • TRIG_EXT: the scan_begin event occurs when an external trigger signal occurs; e.g., a rising edge of a digital line. scan_begin_arg chooses the particular digital line.

The scan_begin_arg used here may not be supported exactly by the device, but it will be adjusted to the nearest supported value by comedi_command_test().

The timing between each sample in a scan is controlled by the convert_* fields:

  • TRIG_TIMER: the conversion events occur periodically. The time between convert events is convert_arg nanoseconds.

  • TRIG_EXT: the conversion events occur when an external trigger signal occurs, e.g., a rising edge of a digital line. convert_arg chooses the particular digital line.

  • TRIG_NOW: All conversion events in a scan occur simultaneously.

The end of each scan is almost always specified using TRIG_COUNT, with the argument being the same as the number of channels in the chanlist. You could probably find a device that allows something else, but it would be strange.

The end of an acquisition is controlled by stop_src and stop_arg:

  • TRIG_COUNT: stop the acquisition after stop_arg scans.

  • TRIG_NONE: perform continuous acquisition, until stopped using comedi_cancel().

    Its argument is reserved and should be set to 0. ("Reserved" means that unspecified things could happen if it is set to something else but 0.)

There are a couple of less usual or not yet implemented events:

  • TRIG_TIME: cause an event to occur at a particular time.

    (This event source is reserved for future use.)

  • TRIG_OTHER: driver specific event trigger.

    This event can be useful as any of the trigger sources. Its exact meaning is driver specific, because it implements a feature that otherwise does not fit into the generic Comedi command interface. Configuration of TRIG_OTHER features are done by INSN_CONFIG instructions.

    The argument is reserved and should be set to 0.

Not all event sources are applicable to all events. Supported trigger sources for specific events depend significantly on your particular device, and even more on the current state of its device driver. The comedi_get_cmd_src_mask() function is useful for determining what trigger sources a subdevice supports.

4.5.4. The command flags

The flags field in the command data structure is used to specify some "behaviour" of the acquisitions in a command. The meaning of the field is as follows:

  • TRIG_RT: ask the driver to use a hard real-time interrupt handler. This will reduce latency in handling interrupts from your data aquisition hardware. It can be useful if you are sampling at high frequency, or if your hardware has a small onboard data buffer. You must have a real-time kernel (RTAI or RTLinux/Free) and must compile Comedi with real-time support, or this flag will do nothing.

  • TRIG_WAKE_EOS: where "EOS" stands for "End of Scan". Some drivers will change their behaviour when this flag is set, trying to transfer data at the end of every scan (instead of, for example, passing data in chunks whenever the board's hardware data buffer is half full). This flag may degrade a driver's performance at high frequencies, because the end of a scan is, in general, a much more frequent event than the filling up of the data buffer.

  • TRIG_ROUND_NEAREST: round to nearest supported timing period, the default. This flag (as well as the following three), indicates how timing arguments should be rounded if the hardware cannot achieve the exact timing requested.

  • TRIG_ROUND_DOWN: round period down.

  • TRIG_ROUND_UP: round period up.

  • TRIG_ROUND_UP_NEXT: this one doesn't do anything, and I don't know what it was intended to do...?

  • TRIG_DITHER: enable dithering? Dithering is a software technique to smooth the influence of discretization "noise".

  • TRIG_DEGLITCH: enable deglitching? Another "noise" smoothing technique.

  • TRIG_WRITE: write to bidirectional devices. Could be useful, in principle, if someone wrote a driver that supported commands for a digital I/O device that could do either input or output.

  • TRIG_BOGUS: do the motions?

  • TRIG_CONFIG: perform configuration, not triggering. This is a legacy of the deprecated comedi_trig_struct data structure, and has no function at present.

4.5.5. Anti-aliasing

If you wish to aquire accurate waveforms, it is vital that you use an anti-alias filter. An anti-alias filter is a low-pass filter used to remove all frequencies higher than the Nyquist frequency (half your sampling rate) from your analog input signal before you convert it to digital. If you fail to filter your input signal, any high frequency components in the original analog signal will create artifacts in your recorded digital waveform that cannot be corrected.

For example, suppose you are sampling an analog input channel at a rate of 1000 Hz. If you were to apply a 900 Hz sine wave to the input, you would find that your sampling rate is not high enough to faithfully record the 900 Hz input, since it is above your Nyquist frequency of 500 Hz. Instead, what you will see in your recorded digital waveform is a 100 Hz sine wave! If you don't use an anti-alias filter, it is impossible to tell whether the 100 Hz sine wave you see in your digital signal was really produced by a 100 Hz input signal, or a 900 Hz signal aliased to 100 Hz, or a 1100 Hz signal, etc.

In practice, the cutoff frequency for the anti-alias filter is usually set 10% to 20% below the Nyquist frequency due to fact that real filters do not have infinitely sharp cutoffs.

4.6. Slowly-varying inputs

Sometimes, your input channels change slowly enough that you are able to average many successive input values to get a more accurate measurement of the actual value. In general, the more samples you average, the better your estimate gets, roughly by a factor of sqrt(number_of_samples). Obviously, there are limitations to this:

As you might have guessed, the Comedi library has functions to help you in your quest to accurately measure slowly varying inputs:

  int comedi_sv_init(comedi_sv_t * sv, comedi_t * device, unsigned int subdevice, unsigned int channel);
This function initializes the comedi_sv_t data structure, used to do the averaging acquisition:
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 analog inputs) */
  int n;

  lsampl_t maxdata;
};
The actual acquisition is done with:
  int comedi_sv_measure(comedi_sv_t * sv, double * data);
The number of samples over which the comedi_sv_measure() averages is limited by the implementation (currently the limit is 100 samples).

One typical use for this function is the measurement of thermocouple voltages. And the Comedi self-calibration utility also uses these functions. On some hardware, it is possible to tell it to measure an internal stable voltage reference, which is typically going to be very slowly varying; on the kilosecond time scale or more. So, it is reasonable to measure millions of samples, to get a very accurate measurement of the A/D converter output value that corresponds to the voltage reference. Sometimes, however, this is overkill, since there is no need to perform a part-per-million calibration to a standard that is only accurate to a part-per-thousand.

4.7. Experimental functionality

The following subsections document functionality that has not yet matured. Most of this functionality has even not been implemented yet in any single device driver. This information is included here, in order to stimulate discussion about their API, and to encourage pioneering implementations.

4.7.1. Digital input combining machines

(Status: experimental (i.e., no driver implements this yet))

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:

00: transition is ignored.
01: accumulator is incremented, or output is set.
10: accumulator is decremented, or output is cleared.
11: reserved.

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.

4.7.2. Analog filtering configuration

(Status: design (i.e., no driver implements this yet).)

The insn field of the instruction data structure has not been assigned yet.

The chanspec field of the instruction data structure is ignored.

Some devices have the capability to add white noise (dithering) to analog input measurement. This additional noise can then be averaged out, to get a more accurate measurement of the input signal. It should not be assumed that channels can be separately configured. A simple design can use 1 bit to turn this feature on/off.

Some devices have the capability of changing the glitch characteristics of analog output subsytems. The default (off) case should be where the average settling time is lowest. A simple design can use 1 bit to turn this feature on/off.

Some devices have a configurable analog filters as part of the analog input stage. A simple design can use 1 bit to enable/disable the filter. Default is disabled, i.e., the filter being bypassed, or if the choice is between two filters, the filter with the largest bandwidth.

4.7.3. Analog Output Waveform Generation

(Status: design (i.e., no driver implements this yet).)

The insn field of the instruction data structure has not been assigned yet.

The chanspec field of the instruction data structure is ignored.

Some devices have the ability to cyclicly loop through samples kept in an on-board analog output FIFO. This config should allow the user to enable/disable this mode.

This config should allow the user to configure the number of samples to loop through. It may be necessary to configure the channels used.

4.7.4. Extended Triggering

(Status: alpha.)

The insn field of the instruction data structure has not been assigned yet.

The chanspec field of the instruction data structure is ignored.

This section covers common information for all extended triggering configuration, and doesn't describe a particular type of extended trigger.

Extended triggering is used to configure triggering engines that do not fit into commands. In a typical programming sequence, the application will use configuration instructions to configure an extended trigger, and a command, specifying TRIG_OTHER as one of the trigger sources.

Extended trigger configuration should be designed in such a way that the user can probe for valid parameters, similar to how command testing works. An extended trigger configuration instruction should not configure the hardware directly, rather, the configuration should be saved until the subsequent command is issued. This allows more flexibility for future interface changes.

It has not been decided whether the configuration stage should return a token that is then used as the trigger argument in the command. Using tokens is one method to satisfy the problem that extended trigger configurations may have subtle compatiblity issues with other trigger sources/arguments that can only be determined at command test time. Passing all stages of a command test should only be allowed with a properly configured extended trigger.

Extended triggers must use data[1] as flags. The upper 16 bits are reserved and used only for flags that are common to all extended triggers. The lower 16 bits may be defined by the particular type of extended trigger.

Various types of extended triggers must use data[1] to know which event the extended trigger will be assigned to in the command structure. The possible values are an OR'd mask of the following:

  • COMEDI_EV_START

  • COMEDI_EV_SCAN_BEGIN

  • COMEDI_EV_CONVERT

  • COMEDI_EV_SCAN_END

  • COMEDI_EV_STOP

4.7.5. Analog Triggering

(Status: alpha. The ni_mio_common.c driver implements this feature.)

The insn field of the instruction data structure has not been assigned yet.

The chanspec field of the instruction data structure is ignored.

The data field of the instruction data structure is used as follows:

data[1]: trigger and combining machine configuration.
data[2]: analog triggering signal chanspec.
data[3]: primary analog level.
data[4]: secondary analog level.

Analog triggering is described by a digital combining machine that has two sensitive digital inputs. The sensitive digital inputs are generated by configurable analog comparators. The analog comparators generate a digital 1 when the analog triggering signal is greater than the comparator level. The digital inputs are not modifier inputs. Note, however, there is an effective modifier due to the restriction that the primary analog comparator level must be less than the secondary analog comparator level.

If only one analog comparator signal is used, the combining machine for the secondary input should be set to ignored, and the secondary analog level should be set to 0.

The interpretation of the chanspec and voltage levels is device dependent, but should correspond to similar values of the analog input subdevice, if possible.

Notes: Reading range information is not addressed. This makes it difficult to convert comparator voltages to data values.

Possible extensions: A parameter that specifies the necessary time that the set condition has to be true before the trigger is generated. A parameter that specifies the necessary time that the reset condition has to be true before the state machine is reset.

4.7.6. Bitfield Pattern Matching Extended Trigger

(Status: design. No driver implements this feature yet.)

The insn field of the instruction data structure has not been assigned yet.

The chanspec field of the instruction data structure is ignored.

The data field of the instruction data structure is used as follows:

data[1]: trigger flags.
data[2]: mask.
data[3]: pattern.

The pattern matching trigger issues a trigger when all of a specifed set of input lines match a specified pattern. If the device allows, the input lines should correspond to the input lines of a digital input subdevice, however, this will necessarily be device dependent. Each possible digital line that can be matched is assigned a bit in the mask and pattern. A bit set in the mask indicates that the input line must match the corresponding bit in the pattern. A bit cleared in the mask indicates that the input line is ignored.

Notes: This only allows 32 bits in the pattern/mask, which may be too few. Devices may support selecting different sets of lines from which to match a pattern.

Discovery: The number of bits can be discovered by setting the mask to all 1's. The driver must modify this value and return -EAGAIN.

4.7.7. Counter configuration

(Status: design. No driver implements this feature yet.)

The insn field of the instruction data structure has not been assigned yet.

The chanspec field of the instruction data structure is used to specify which counter to use. (I.e., the counter is a Comedi channel.)

The data field of the instruction data structure is used as follows:

data[1]: trigger configuration.
data[2]: primary input chanspec.
data[3]: primary combining machine configuration.
data[4]: secondary input chanspec.
data[5]: secondary combining machine configuration.
data[6]: latch configuration.

Note that this configuration is only useful if the counting has to be done in software. Many cards offer configurable counters in hardware; e.g., general purpose timer cards can be configured to act as pulse generators, frequency counters, timers, encoders, etc.

Counters can be operated either in synchronous mode (using INSN_READ) or asynchronous mode (using commands), similar to analog input subdevices. The input signal for both modes is the accumulator. Commands on counter subdevices are almost always specified using scan_begin_src = TRIG_OTHER, with the counter configuration also serving as the extended configuration for the scan begin source.

Counters are made up of an accumulator and a combining machine that determines when the accumulator should be incremented or decremented based on the values of the input signals. The combining machine optionally determines when the accumulator should be latched and put into a buffer. This feature is used in asynchronous mode.

Note: How to access multiple pieces of data acquired at each event?

4.7.8. One source plus auxiliary counter configuration

(Status: design. No driver implements this feature yet.)

The insn field of the instruction data structure has not been assigned yet.

The chanspec field of the instruction data structure is used to ...

The data field of the instruction data structure is used as follows:

data[1]: is flags, including the flags for the command triggering configuration. If a command is not subsequently issued on the subdevice, the command triggering portion of the flags are ignored.
data[2]: determines the mode of operation. The mode of operation is actually a bitfield that encodes what to do for various transitions of the source signals.
data[3], data[4]: determine the primary source for the counter, similar to the _src and the _arg fields used in the command data structure.

Notes: How to specify which events cause a latch and push, and what should get latched?