Comedi Documentation

David Schleef

        ds@schleef.org
      

Frank Hess

        fmhess@uiuc.edu
      


Table of Contents
1. Introduction
1.1. What is a "device driver"?
1.2. A general DAQ device driver package.
1.3. Policy vs. mechanism.
1.4. Overview of Comedi.
2. Installation and Configuration
2.1. Getting information from comedi
3. Writing programs that use comedi and comedilib
3.1. Your first comedi program
3.2. Converting samples to voltages
3.3. Another section
3.4. Your second comedi program
4. Application-specific functions
4.1. Digital Input/Output
4.2. Slowly-varying inputs
4.3. Commands and streaming input/output
5. Low-level drivers
5.1. 8255.o -- generic 8255 support
5.2. adl_pci9118.o -- Adlink PCI-9118DG, PCI-9118HG, PCI-9118HR
5.3. adv_pci1710.o -- Advantech PCI-1710, PCI-1710HG, PCI-1711, PCI-1713, Advantech PCI-1720, PCI-1731
5.4. amplc_pci230.o -- Driver for Amplicom PCI230 and PCI260 Multifunction I/O boards
5.5. cb_pcidas.o -- Driver for the ComputerBoards/MeasurementComputing cards of the PCI-DAS series with the AMCC S5933 PCI controller.
5.6. cb_pcidas64.o -- Driver for the ComputerBoards/MeasurementComputing PCI-DAS64xxx series with the PLX 9080 PCI controller.
5.7. cb_pcidda.o -- ComputerBoards/MeasurementComputing PCI-DDA series
5.8. comedi_parport.o -- Standard PC parallel port
5.9. comedi_rt_timer.o -- Command emulator using real-time tasks
5.10. daqboard2000.o -- IOTech DAQBoard/2000
5.11. das08.o -- DAS-08 compatible boards
5.12. das16.o -- DAS16 compatible boards
5.13. das16m1.o -- CIO-DAS16/M1
5.14. das1800.o -- Keithley Metrabyte DAS1800 (& compatibles)
5.15. das6402.o -- Keithley Metrabyte DAS6402 (& compatibles)
5.16. das800.o -- Keithley Metrabyte DAS800 (& compatibles)
5.17. dt2801.o -- Data Translation DT2801 series and DT01-EZ
5.18. dt2811.o -- Data Translation DT2811
5.19. dt2814.o -- Data Translation DT2814
5.20. dt2815.o -- Data Translation DT2815
5.21. dt2817.o -- Data Translation DT2817
5.22. dt282x.o -- Data Translation DT2821 series (including DT-EZ)
5.23. dt3000.o -- Data Translation DT3000 series
5.24. fl512.o -- unknown
5.25. icp_multi.o -- Inova ICP Multi
5.26. ii_pci20kc.o -- Intelligent Instruments PCI-20001C carrier board
5.27. mpc8260cpm.o -- MPC8260 CPM module generic digital I/O lines
5.28. multiq3.o -- Quanser Consulting MultiQ-3
5.29. ni_670x.o -- National Instruments 670x
5.30. ni_at_a2150.o -- National Instruments AT-A2150
5.31. ni_atmio.o -- National Instruments AT-MIO-E series
5.32. ni_atmio16d.o -- National Instruments AT-MIO-16D
5.33. ni_labpc.o -- National Instruments Lab-PC (& compatibles)
5.34. ni_mio_cs.o -- National Instruments DAQCard E series
5.35. ni_pcidio.o -- National Instruments PCI-DIO32HS, PCI-DIO96, PCI-6533, PCI-6503
5.36. ni_pcimio.o -- National Instruments PCI-MIO-E series (all boards)
5.37. pcl711.o -- Advantech PCL-711 and 711b, ADLink ACL-8112
5.38. pcl724.o -- Advantech PCL-724, PCL-722, PCL-731 ADLink ACL-7122, ACL-7124, PET-48DIO
5.39. pcl725.o -- Advantech PCL-725 (& compatibles)
5.40. pcl726.o -- Advantech PCL-726 & compatibles
5.41. pcl812.o -- Advantech PCL-812/PG, PCL-813/B, ADLink ACL-8112DG/HG/PG, ACL-8113, ACL-8216, ICP DAS A-821PGH/PGL/PGL-NDA, A-822PGH/PGL, A-823PGH/PGL, A-826PG, ICP DAS ISO-813
5.42. pcl818.o -- Advantech PCL-818 cards, PCL-718
5.43. pcm3730.o -- PCM3730
5.44. pcmad.o -- Winsystems PCM-A/D12, PCM-A/D16
5.45. poc.o -- Generic driver for very simple devices Device names: dac02
5.46. quatech_daqp_cs.o -- Quatech DAQP PCMCIA data capture cards
5.47. rtd520.o -- Real Time Devices PCI4520/DM7520
5.48. rti800.o -- Analog Devices RTI-800/815
5.49. rti802.o -- Analog Devices RTI-802
5.50. skel.o -- Skeleton driver, an example for driver writers
5.51. ssv_dnp.o -- SSV Embedded Systems DIL/Net-PC
6. Comedi Reference
6.1. Constants and Macros
6.1.1. CR_PACK
6.1.2. RANGE_LENGTH (deprecated)
6.2. Data Types and Structures
6.2.1. comedi_t
6.2.2. sampl_t
6.2.3. lsampl_t
6.2.4. comedi_trig (deprecated)
6.2.5. comedi_sv_t
6.2.6. comedi_cmd
6.2.7. comedi_insn
6.2.8. comedi_range
6.2.9. comedi_krange
6.2.10. comedi_insnlist
6.3. Interface reference
6.3.1. Digital input combining machines
6.3.2. INSN_CONFIG
6.4. Comedi Function Reference
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_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

1. Introduction

This section gives high-level explanation about which functionality you can expect from the software. Details are given in the following sections of this document.

1.1. What is a "device driver"?

A device driver is a piece of software that interfaces a particular piece of hardware: a printer, a sound card, a motor drive, etc. It translates the primitive, device-dependent commands with which the hardware manufacturer want you to configure, read and write the electronics of the hardware interface into more abstract and generic function calls and data structures for the application programmer.

David Schleef started the Comedi project to interface lots of different cards for measurement and control purposes. This type of cards are often called Data AcQuisition cards, or DAQ cards. Schleef designed a structure which is a balance between modularity (i.e., it's fairly easy to integrate a new card because most of the infrastructure part of the driver can be reused) and complexity (i.e., the structure doesn't present so much overhead that new contributors are scared away from writing their new drivers within the Comedi framework). The Comedi project consists of two complementary packages: "comedi" (which implements the kernel space functionality) and "comedilib" (which implements the user space access to the device driver functionality). Comedi works with a standard Linux kernel, but also with its real-time extensions RTAI and Real-Time Linux.

1.2. A general DAQ device driver package.

From the point of view of system developers, it is worthwhile to standardize the structure and API (Application Programming Interface) for device drivers as much as possible:

API: devices that offer similar functionalities, should have the same software interface, and their differences should be coped with by parameterizing the interfaces, not by changing the interface for each new device in the family.

Structure: many electronic interfaces have more than one layer of functionality between the hardware and the operating system, and the device driver code should reflect this fact. For example, many different interface cards use the same PCI driver chips, or use the parallel port to connect to the hardware device. Hence, providing "low-level" device drivers for these PCI chips and parallel ports allows for an increased modularity and re-useability of the software.

In the case of Linux as the host operating system, device driver writers must keep the following Linux-specific issues in mind:

Kernel space vs. User space. The Linux operating system has two levels: only privileged processes can run in the kernel, where they have access to all hardware and to all kernel data structures and system calls; normal application programs can run their processes only in user space, where these processes are shielded from each other, and from direct access to hardware and to critical data of the operating system. Device drivers typically must access specific addresses on the bus, and hence use privileged system calls. Therefore, a device driver has a component in kernel space. One can write a user space driver for, for example, a device on the parallel port, but in this case, the basic parallel port device driver runs already in the kernel by default; the interaction with the hardware then takes place via the method explained below.

Device files or device file system. The users that want to write an application for a particular device, must link their application to the device's device driver. This device driver, however, runs in kernel space, and the user application in user space. So, the operating system provides an interface between both. In Linux or Unix, these interfaces are in the form of "files" in the /dev directory (2.2.x kernels or earlier) or /devfs directory (2.4.x kernels and later). Each device has a representative, and can be accessed by the classical Unix file I/O calls: open, close, read, write, and ioctl.

/proc interface. Linux offers a file-like interface to attached devices (and other OS-related information) via the /proc directories. This interface allows to inspect the current status of each device.

Direct Memory Access (DMA) vs. Programmed Input/Output (PIO). Almost all devices can be interfaced in PIO mode: the processor is responsible for accessing bus addresses allocated to the device, and to read or write data. Some devices also allow DMA: the device and the memory "talk" to each other directly, without needing the processor. DMA is a feature of the bus, not of the operating system (which has to support its processes to use the feature, of course).

If the device is to be used in a Real-Time Linux or RTAI application, there are a few extra requirements, because not all system calls are available in the RTOS kernel of Real-Time Linux or RTAI.

1.3. Policy vs. mechanism.

Device drivers are often written by application programmers, that have a particular application in mind. For example, one writes a driver for the parallel port, because one wants to use it to generate pulses that drive a stepper motor. This approach often leads to device drivers that depend too much on the application, and are not general enough to be re-used for other applications. One golden rule for the device driver writer is to separate mechanism and policy:

Mechanism. The mechanism part of the device interface is a faithful representation of the bare functionality of the device, independent of what part of the functionality an application will use.

Policy. Once a device driver offers a software interface to the mechanism of the device, an application writer can use this mechanism interface to use the device in one particular fashion. That is, some of the data stuctures offered by the mechanism are interpreted in specific physical units, or some of them are taken together because this composition is relevant for the application. For example, a analog output card can be used to generate voltages that are the inputs for the electronic drivers of the motors of a robot; these voltages can be interpreted as setpoints for the desired velocity of these motors, and six of them are taken together to steer one particular robot with six-degrees of freedom. Some of the other outputs of the same physical device can be used by another application program, for example to generate a sine wave that drives a vibration shaker.

1.4. Overview of Comedi.

The supported cards in Comedi have one or more of the following features: analog input channels, analog output channels, digital input channels, and digital output channels. The digital channels are conceptually quite simple, and don't need much configuration: the number of channels, their addresses on the bus, and their direction (input/output).

The analog channels are a bit more complicated. Typically, an analog channel can be programmed to generate or read a voltage between a lower and an upper threshold (e.g., -10V and +10V); the card's electronics can be programmed to automatically sample a set of channels, in a prescribed order; top buffer sequences of data on the board; or to use DMA to dump the data in an available part of memory, without intervention from the processor.

Many interface cards have extra functionality, besides the analog and digital channels. For example, an EEPROM for configuration and board parameters, calibration inputs, counters and timers, encoders (= quadrature counter on two channels), etc. Therefore, Comedi offers more than just analog and digital data acquisition.

The kernel space structures that Comedi uses have the following hierarchy:

- channel: the lowest-level component, that represents the properties of one single data channel (analog in or out; digital in or out). Each channel has parameters for: the voltage range, the reference voltage, the channel polarity (unipolar, bipolar), a conversion factor between voltages and physical units.

- sub-device: a set of functionally identical channels that are physically implemented on the same (chip on an) interface card. For example, a set of 16 identical analog outputs. Each sub-device has parameters for: the number of channels, and the type of the channels.

- device: a set of sub-devices that are physically implemented on the same interface card; in other words, the interface card itself. For example, the NI 6024E device has a sub-device with 16 analog input channels, another sub-device with two analog output channels, and a third sub-device with eight digital inputs/outputs. Each device has parameters for: the device identification tag from the manufacturer, the identification tag given by the operating system (in order to discriminate between multiple interface cards of the same type), the number of sub-devices, etc.

The basic functionalities offered by Comedi are:

- instruction: to synchronously perform one single data acquisition on a specified channel, or to perform a configuration on the channel. "Synchronous" means that the calling process blocks until the data acquisition has finished.

- scan: repeated instructions on a number of different channels, with a programmed sequence and timing.

- command: start or stop an autonomous (and hence aynchronous) data acquisition (i.e., a number of scans) on a specified set of channels. "Autonomous" means: without interaction from the software, i.e., by means of on-board timers or possibly external triggers.

This command functionality is not offered by all DAQ cards. When using RTAI or Real-Time Linux, the command functionality is emulated through the "comedi_rt_timer" virtual driver. The command functionality is very configurable, with respect to the choice of events with which to signal the progress of the programmed scans: external triggers, end of instruction, etc.

Comedi not only offers the API to access the functionality of the cards, but also to query the capabilities of the installed Comedi devices. That is, a user process can find out on-line what channels are available, and what their physical parameters are (range, direction of input/output, etc.).

Buffers are an important aspect of device drivers: the data has to be stored in such buffers, if the application program cannot guarantee to read or write the data as soon as the interface board wants to do so. Therefore, Comedi offers functionality to configure and manage data buffers.

Comedi contains more than just procedural function calls: it also offers event-driven functionality. The data acquisition can signal its completion by means of an interrupt or a callback function call. Callbacks are also used to signal errors during the data acquisition or when writing to buffers, or at the end of a scan or acquisition that has been launched previously to take place asynchronously (i.e., the card fills up som shared memory buffer autonomously, and only warns the user program after it has finished).

The mechanisms for synchronization and interrupt handling are a bit different when used in a real-time context (i.e., with either RTAI or Real-Time Linux), but both are encapsulated behind the same Comedi calls.

Because multiple devices can all be active at the same time, Comedi provides (non-SMP!) locking primitives to ensure atomic operations on critical sections of the code or data structures.

Finally, Comedi offers the above-mentioned "high-level" interaction, i.e., at the level of user space device drivers, through file operations on entries in the /dev directory (for access to the device's functionality), or interactively from the command line through the "files" in the /proc directory (which allow to inspect the status of a Comedi device). This high-level interface resides in the "comedilib" tarball, which is the user space library, with facilities to connect to the kernel space drivers residing in the "comedi" tarball.