7. Comedi Reference

Reference for constants and macros, data types and structures, and functions.

7.1. Headerfiles: comedi.h and comedilib.h

All application programs must include the header file comedilib.h. (This file itself includes comedi.h.) They contain the full interface of Comedi: defines, function prototypes, data structures.

The following Sections give more details.

7.2. Constants and Macros

7.2.1. CR_PACK

CR_PACK is used to initialize the elements of the chanlist array in the comedi_cmd data structure, and the chanspec member of the comedi_insn structure.

#define CR_PACK(chan,rng,aref)      ( (((aref)&0x3)<<24) | (((rng)&0xff)<<16) | (chan) ) 

The chan argument is the channel you wish to use, with the channel numbering starting at zero.

The range rng is an index, starting at zero, whose meaning is device dependent. The comedi_get_n_ranges() and comedi_get_range() functions are useful in discovering information about the available ranges.

The aref argument indicates what reference you want the device to use. It can be any of the following:

AREF_GROUND

is for inputs/outputs referenced to ground.

AREF_COMMON

is for a "common" reference (the low inputs of all the channels are tied together, but are isolated from ground).

AREF_DIFF

is for differential inputs/outputs.

AREF_OTHER

is for any reference that does not fit into the above categories.

Particular drivers may or may not use the AREF flags. If they are not supported, they are silently ignored.

7.2.2. RANGE_LENGTH (deprecated)

Rangetype values are library-internal tokens that represent an array of range information structures. These numbers are primarily used for communication between the kernel and library.

The RANGE_LENGTH() macro returns the length of the array that is specified by the rangetype token.

The RANGE_LENGTH() macro is deprecated, and should not be used in new applications. It is scheduled to be removed from the header file at version 1.0. Binary compatibility may be broken for version 1.1.

7.3. Data Types and Structures

This Section explains the data structures that users of the Comedi API are confronted with:

typedef struct subdevice_struct       subdevice_struct:
typedef struct comedi_devinfo_struct  comedi_devinfo;
typedef struct comedi_t_struct        comedi_t;
typedef struct sampl_t_struct         sampl_t;
typedef struct lsampl_t_struct        lsampl_t;
typedef struct comedi_sv_t_struct     comedi_sv_t;
typedef struct comedi_cmd_struct      comedi_cmd;
typedef struct comedi_insn_struct     comedi_insn;
typedef struct comedi_range_struct    comedi_range;
typedef struct comedi_krange_struct   comedi_krange;
typedef struct comedi_insnlist_struct comedi_insnlist;
The data structures used in the implementation of the Comedi drivers are treated elsewhere.

7.3.1. subdevice_struct

The data type subdevice_struct is used to store information about a subdevice. This structure is usually filled in automatically when the driver is loaded ("attached"), so programmers need not access this data structure directly.

typedef struct subdevice_struct subdevice;

struct subdevice_struct{
  unsigned int type;
  unsigned int n_chan;
  unsigned int subd_flags;
  unsigned int timer_type;
  unsigned int len_chanlist;
  lsampl_t maxdata;
  unsigned int flags;
  unsigned int range_type;

  lsampl_t *maxdata_list;
  unsigned int *range_type_list;
  unsigned int *flags_list;

  comedi_range *rangeinfo;
  ccomedi_range **rangeinfo_list;

  unsigned int has_cmd;
  unsigned int has_insn_bits;

  int cmd_mask_errno;
  comedi_cmd *cmd_mask;
  int cmd_timed_errno;
  comedi_cmd *cmd_timed;
};

7.3.2. comedi_devinfo

The data type comedi_devinfo is used to store information about a device. This structure is usually filled in automatically when the driver is loaded ("attached"), so programmers need not access this data structure directly.

typedef struct comedi_devinfo_struct comedi_devinfo;

struct comedi_devinfo_struct{
  unsigned int version_code;    // version number of the Comedi code
  unsigned int n_subdevs;       // number of subdevices on this device
  char         driver_name[COMEDI_NAMELEN];
  char         board_name[COMEDI_NAMELEN];
  int          read_subdevice;  // number of read devices
  int          write_subdevice; // number of write devices
  int          unused[30];
};

7.3.3. comedi_t

The data type comedi_t is used to represent an open Comedi device:

typedef struct comedi_t_struct comedi_t;

struct comedi_t_struct{
  int magic;        // driver-specific magic number, for identification
  int fd;           // file descriptor, for open() and close()
  int n_subdevices; // number of subdevices on this device
  comedi_devinfo devinfo;
  subdevice *subdevices; // pointer to subdevice list
                         // filled in automatically at load time
  unsigned int has_insnlist_ioctl; // can process instruction lists
  unsigned int has_insn_ioctl;     // can process instructions
};
A valid comedi_t pointer is returned by a successful call to comedi_open(), and should be used for subsequent access to the device. It is a transparent type, and pointers to type comedi_t should not be dereferenced by the application.

7.3.4. sampl_t

typedef unsigned short sampl_t;

The data type sampl_t is one of the generic types used to represent data values in Comedilib. It is used in a few places where a data type shorter than lsampl_t is useful. On most architectures, sampl_t is defined to be uint16.

Most drivers represent data transferred by read() and write() using sampl_t. Applications should check the subdevice flag SDF_LSAMPL to determine if the subdevice uses sampl_t or lsampl_t.

7.3.5. lsampl_t

typedef unsigned int lsampl_t;

The data type lsampl_t is the data type typically used to represent data values in libcomedi. On most architectures, lsampl_t is defined to be uint32.

7.3.6. comedi_trig (deprecated)

typedef struct comedi_trig_struct comedi_trig;

struct comedi_trig_struct{
  unsigned int subdev;   /* subdevice */
  unsigned int mode;  /* mode */
  unsigned int flags;
  unsigned int n_chan;  /* number of channels */
  unsigned int *chanlist;   /* channel/range list */
  sampl_t *data;  /* data list, size depends on subd flags */
  unsigned int n;  /* number of scans */
  unsigned int trigsrc;
  unsigned int trigvar;
  unsigned int trigvar1;
  unsigned int data_len;
  unsigned int unused[3];
};

The comedi_trig structure is a control structure used by the COMEDI_TRIG ioctl, an older method of communicating instructions to the driver and hardware. Use of comedi_trig is deprecated, and should not be used in new applications.

7.3.7. comedi_sv_t

typedef struct comedi_sv_struct comedi_sv_t;

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 ai) */
  int n;

  lsampl_t maxdata;
};

The comedi_sv_t structure is used by the comedi_sv_*() functions to provide a simple method of accurately measuring slowly varying inputs. See the relevant section for more details.

7.3.8. comedi_cmd

typedef struct comedi_cmd_struct comedi_cmd;

struct comedi_cmd_struct{
  unsigned int subdev;
  unsigned int flags;

  unsigned int start_src;
  unsigned int start_arg;

  unsigned int scan_begin_src;
  unsigned int scan_begin_arg;

  unsigned int convert_src;
  unsigned int convert_arg;

  unsigned int scan_end_src;
  unsigned int scan_end_arg;

  unsigned int stop_src;
  unsigned int stop_arg;

  unsigned int *chanlist;
  unsigned int chanlist_len;

  sampl_t *data;
  unsigned int data_len;
};

More information on using commands can be found in the command section.

7.3.9. comedi_insn

typedef struct comedi_insn_struct comedi_insn;

struct comedi_insn_struct{
  unsigned int insn;
  unsigned int n;
  lsampl_t*data;
  unsigned int subdev;
  unsigned int chanspec;
  unsigned int unused[3];
};

Comedi instructions are described by the comedi_insn structure. Applications send instructions to the driver in order to perform control and measurement operations that are done immediately or synchronously, i.e., the operations complete before program control returns to the application. In particular, instructions cannot describe acquisition that involves timers or external events.

The field insn determines the type of instruction that is sent to the driver. Valid instruction types are:

INSN_READ

read values from an input channel

INSN_WRITE

write values to an output channel

INSN_BITS

read/write values on multiple digital I/O channels

INSN_CONFIG

configure a subdevice

INSN_GTOD

read a timestamp, identical to gettimeofday()

INSN_WAIT

wait a specified number of nanoseconds

The number of samples to read or write, or the size of the configuration structure is specified by the field n, and the buffer for those samples by data. The field subdev is the subdevice index that the instruction is sent to. The field chanspec specifies the channel, range, and analog reference (if applicable).

Instructions can be sent to drivers using comedi_do_insn(). Multiple instructions can be sent to drivers in the same system call using comedi_do_insnlist().

7.3.10. comedi_range

typedef struct comedi_range_struct comedi_range;

struct comedi_range_struct{
  double min;
  double max;
  unsigned int unit;
}comedi_range;

The comedi_range structure conveys part of the information necessary to translate sample values to physical units, in particular, the endpoints of the range and the physical unit type. The physical unit type is specified by the field unit, which may take the values UNIT_volt for volts, UNIT_mA for milliamps, or UNIT_none for unitless. The endpoints are specified by the fields min and max.

7.3.11. comedi_krange

typedef struct comedi_krange_struct comedi_krange;

struct comedi_krange_struct{
  int min;
  int max;
  unsigned int flags;
};

The comedi_krange structure is used to transfer range information between the driver and Comedilib, and should not normally be used by applications. The structure conveys the same information as the comedi_range structure, except the fields min and max are integers, multiplied by a factor of 1000000 compared to the counterparts in comedi_range.

In addition, kcomedilib uses the comedi_krange structure in place of the comedi_range structure.

7.3.12. comedi_insnlist

typedef struct comedi_insnlist_struct comedi_insnlist;

struct comedi_insnlist_struct{
  unsigned int n_insns;
  comedi_insn *insns;
};

An instruction list (insnlist) structure is used to communicate a list of instructions.

7.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_read_delayed -- read single sample from channel after delaying for specified settling time
comedi_data_read_hint -- tell driver which channel/range/aref you are going to read from next
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
comedi_apply_calibration -- set calibration from file
comedi_apply_parsed_calibration -- set calibration from memory
comedi_cleanup_calibration_file -- free calibration resources
comedi_get_default_calibration_path -- get default calibration file path
comedi_parse_calibration_file -- set calibration