6. Comedi Reference

Reference for functions, macros, and constants.

6.1. Constants and Macros

6.2. Data Types and Structures

6.3. Interface reference

This chapter is meant to be a reference for some of the advanced features of Comedi.

6.3.1. Digital input combining machines

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:

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.

6.3.2. INSN_CONFIG

Configuration instructions are used to access device and driver features that do not fit well into other parts of the Comedi interface. This includes changing the direction of configurable digital I/O lines, configuring complex triggering engines, and counter/timer configuration.

If a specified ID is not supported, the driver must return -EINVAL.

6.3.2.4. Extended Triggering

Status: alpha
ID: not assigned
Chanspec: 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 the issue 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 config 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 config 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:

6.4. Comedi Function Reference

Table of Contents
comedi_close -- close a Comedi device
comedi_open -- open a Comedi device
comedi_loglevel -- change Comedilib logging properties
comedi_perror -- print a Comedilib error message
comedi_strerror -- return string describing Comedilib error code
comedi_errno -- number of last Comedilib error
comedi_fileno -- integer descriptor of Comedilib device
comedi_get_n_subdevices -- number of subdevices
comedi_get_version_code -- Comedi version code
comedi_get_driver_name -- Comedi driver name
comedi_get_board_name -- Comedi device name
comedi_get_subdevice_type -- type of subdevice
comedi_find_subdevice_by_type -- search for subdevice type
comedi_get_read_subdevice -- find streaming input subdevice
comedi_get_write_subdevice -- find streaming output subdevice
comedi_get_subdevice_flags -- properties of subdevice
comedi_get_n_channels -- number of subdevice channels
comedi_range_is_chan_specific -- range information depends on channel
comedi_maxdata_is_chan_specific -- maximum sample depends on channel
comedi_get_maxdata -- maximum sample of channel
comedi_get_n_ranges -- number of ranges of channel
comedi_get_range -- range information of channel
comedi_find_range -- search for range
comedi_get_buffer_size -- streaming buffer size of subdevice
comedi_get_max_buffer_size -- maximum streaming buffer size
comedi_set_buffer_size -- streaming buffer size of subdevice
comedi_trigger -- perform streaming input/output (deprecated)
comedi_do_insnlist -- perform multiple instructions
comedi_do_insn -- perform instruction
comedi_lock -- subdevice reservation
comedi_unlock -- subdevice reservation
comedi_to_phys -- convert sample to physical units
comedi_from_phys -- convert physical units to sample
comedi_data_read -- read single sample from channel
comedi_data_write -- write single sample to channel
comedi_dio_config -- change input/output properties of channel
comedi_dio_read -- read single bit from digital channel
comedi_dio_write -- write single bit to digital channel
comedi_dio_bitfield -- read/write multiple digital channels
comedi_sv_init -- slowly-varying inputs
comedi_sv_update -- slowly-varying inputs
comedi_sv_measure -- slowly-varying inputs
comedi_get_cmd_src_mask -- streaming input/output capabilities
comedi_get_cmd_generic_timed -- streaming input/output capabilities
comedi_cancel -- stop streaming input/outpu in progress
comedi_command -- start streaming input/output
comedi_command_test -- test streaming input/output configuration
comedi_poll -- force updating of streaming buffer
comedi_set_max_buffer_size -- streaming buffer size of subdevice
comedi_get_buffer_contents -- streaming buffer status
comedi_mark_buffer_read -- streaming buffer status
comedi_get_buffer_offset -- streaming buffer status
comedi_get_timer -- timer information (deprecated)
comedi_timed_1chan -- streaming input (deprecated)
comedi_set_global_oor_behavior -- out-of-range behavior