From: Frank Mori Hess Date: Thu, 24 Jan 2008 19:11:18 +0000 (+0000) Subject: Fixed indentation. Performed some editing of content. Removed some parts X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=dfaf144f85eb1f3ca417ea1643d3de786b6d95b8;p=comedilib.git Fixed indentation. Performed some editing of content. Removed some parts which were wrong, or made no sense to me. --- diff --git a/doc/intro.xml b/doc/intro.xml index b13802a..96a3559 100644 --- a/doc/intro.xml +++ b/doc/intro.xml @@ -6,709 +6,595 @@ ]>
- - -Overview - - - -&comedi; is a free software project that develops -drivers, tools, and libraries for various forms of -data acquisition: reading and writing of analog -signals; reading and writing of digital inputs/outputs; pulse and -frequency counting; pulse generation; reading encoders; etc. The -project's source code is distributed in two packages, - -comedi - and - -comedilib -, and provides several Linux -kernel modules and a -user space library: - - - - -Comedi is a collection of drivers for a variety -of common data acquisition plug-in boards (which are called -devices in &comedi; terminology). The drivers are -implemented as the combination of (i) one single core Linux kernel module -(called comedi) providing common -functionality, and (ii) individual low-level driver modules for -each device. - - - - - -Comedilib is a separately distributed package -containing a user-space library that provides a -developer-friendly interface to the &comedi; devices. Included in the -Comedilib package are documentation, -configuration and calibration utilities, and demonstration programs. - - - - - -Kcomedilib is a Linux kernel module -(distributed with the comedi package) that provides -the same interface as comedilib in kernel space, -and suitable for real-time tasks. It is -effectively a kernel library for using &comedi; from -real-time tasks. - - - - -&comedi; works with standard Linux kernels, but also with its -real-time extensions RTAI and -RTLinux/GPL. - - -This section gives a high-level introduction to which functionality -you can expect from the software. More technical details and -programming examples are given in the following sections of this -document. - - -
- -What is a <quote>device driver</quote>? - - -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 allows 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 put a generic interface -on top of -lots of different cards for measurement and control purposes. This -type of cards are often called data acquisition -(or DAQ) cards. - - -Analog input and output cards were the first goal -of the project, but now &comedi; also provides a device -independent interface to digital input and output -cards, and counter and timer cards (including -encoders, pulse generators, frequency and pulse timers, etc.). - - -Schleef designed a structure which is a balance between -modularity and complexity: -it's fairly easy to integrate a new card because most of the -infrastructure part of other, similar drivers can be reused, and -learning the generic and hence somewhat heavier &comedi; -API doesn't scare away new contributors from integrating their drivers -into the &comedi; framework. - -
- - -
- -Policy vs. mechanism - - -Device drivers are often written by application programmers, that have -only their particular application in mind; especially in real-time -applications. 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 that particular 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. - - - - -So, &comedi; focuses only on the mechanism part -of DAQ interfacing. The project does not provide the policy parts, -such as Graphical User Interfaces to program and display acquisitions, -signal processing libraries, or control algorithms. - - -
- - -
- -A general DAQ device driver package - - -From the point of view of application developers, there are many -reasons to welcome the standardization of the API and the -architectural structure of DAQ software: - - - - - 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. However, the DAQ manufacturers -have never been able (or willing) to come up with such a -standardization effort themselves. - - - - - - Architectural 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 as an intermediate means to connect to the hardware -device. Hence, lower-level device drivers for -these PCI chips and parallel ports allow for an increased modularity -and re-useability of the software. Finding the generic -similarities and structure among different cards helps in developing -device drivers faster and with better documentation. - - - - - - -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 that require -basically different programming approaches. Only privileged processes - can run in the kernel, where they have access to all hardware and to - all kernel data structures. 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; these user -space programs execute much of the operating system's functionality -through system calls. - - -Device drivers typically must access specific addresses on the bus, -and hence must (at least partially) run in kernel space. Normal users -program against the API of Comedi, while -&comedi; device driver writers use the API offered by -Kcomedilib. Typical examples of the latter are -the registration of interrupt handler routines, and the handling of -events. - - - - - - Device files or device file system. - Users who write an application for a particular device, - must link their application to that device's device driver. Part of -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 supported in the kernel has a -representative as such a user space device file, and its functionality can - be accessed by classical Unix file I/O: -open, -close, read, - write, and ioctl. - - - - - - /proc interface. - Linux (and some other UNIX operating systems) offer a file-like -interface to attached devices (and other OS-related information) via -the /proc directories. These -files do not really exist, but it gives a familiar -interface to users, with which they can 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 directly accessing the bus addresses allocated to -the device whenever it needs - 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, of -course, has - to support its processes to use the feature). - - - - - -Real-time vs. non real-time. -If the device is to be used in a -RTLinux/GPL - -or RTAI application, -there are a few extra requirements, because not all system calls are -available in the kernel of the real-time operating systems -RTLinux/GPL - -or RTAI. -The APIs of RTAI and RTLinux/Free differ in -different ways, so the &comedi; developers have spent a lot of efforts -to make generic wrappers to the required RTOS primitives: timers, -memory allocation, registration of interrupt handlers, etc. - - - - - -
- -
- -DAQ signals - - -The cards supported in &comedi; have one or more of the following -signals: analog input, analog -output, digital input, digital output, counter input, counter output, -pulse input, pulse output: - - - - -Digital signals are conceptually quite simple, and don't need -much configuration: the number of channels, their addresses on the -bus, and their input or output direction. - - - - - -Analog signals are a bit more complicated. Typically, an analog -acquisition 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, to -buffer sequences of data on the board; or to use -DMA or an interrupt routine to dump the data in a prescribed part of -memory. - - - - - -Pulse-based signals (counters, -timers, encoders, etc.) are conceptually -only a bit more complex than digital inputs and outputs, in that -they only add some timing specifications to the -signal. &comedi; has still only a limited number of drivers for this -kind of signals, although most of the necessary API and support -functionality is available. - - - - -In addition to these real DAQ functions, &comedi; also -offers basic timer access. - -
- -
- -Device hierarchy - - -&comedi; organizes all hardware according to the following generic -hierarchy: - - - - -Channel: the lowest-level hardware -component, that represents the properties of one single data channel; -for example, an analog input, or a digital output. -Each channel has several parameters, such as: the voltage range; the -reference voltage; the channel polarity (unipolar, bipolar); a -conversion factor between voltages and physical units; the binary -values 0 and 1; etc. - - - - - -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 channel -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 National Instruments 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. - - - - -Some interface cards have extra components that don't fit in the -above-mentioned classification, such as an EEPROM to store -configuration and board parameters, or calibration inputs. These -special components are also classified as sub-devices in -&comedi;. - - -
- -
- -Acquisition terminology - - - -This Section introduces the terminology that this document uses when -talking about acquisitions. -depicts a typical acquisition sequence: - - - - -The sequence has a start and an -end. At both sides, the software -and the hardware need some finite -initialization or settling time. - - - - - - -The sequence consists of a number of identically repeated -scans. This is where the actual -data acquisitions are taking place: data is read from the card, or -written to it. Each scan also has a -begin, an -end, and a finite -setup time. Possibly, there is also -a settling time -(scan delay) at the -end of a scan. - - -So, the hardware puts a -lower boundary (the scan interval) -on the minimum time needed to complete a full scan. - - - - - -Each scan contains one or more - -conversions on particular channels, -i.e., the AD/DA converter is activated on each of the programmed -channels, and produces a sample, again in a finite -conversion time, starting from the -moment in time called the -sample time -in -(sometimes also called the timestamp), -and caused by a -triggering event, called convert. -In addition, each hardware has limits on the minimum -conversion interval it can achieve, -i.e., the minimum time it needs between -subsequent conversions. - - -Some hardware must multiplex the conversions onto -one single AD/DA hardware, such that the conversions are done serially -in time (as shown on the Figure); -other cards have the hardware to do two or more acquisitions in -parallel. The begin of each conversion is triggered by -some internally or externally generated pulse, e.g., a timer. - - - - -In general, not only the begin of a conversion is -triggered, but also the begin of a scan and of a -sequence. &comedi; provides the API to configure -what triggering source -one wants to use in each case. The API also -allows to specify the channel list, -i.e., the sequence of channels that needs to be acquired during each -scan. - - - -
- - Acquisition sequence. (Figure courtesy of - <ulink url="mailto:Kurt.Mueller@aerodynamics.ch">Kurt Müller</ulink>.) - - - - - - - -
- - - -
- - -
- -DAQ functions - - - -The basic data acquisition functionalities that &comedi; offers work -on channels, or sets of channels: - - - - -Single acquisition: &comedi; has -function calls to synchronously perform -one single data acquisition on a specified -channel: comedi_data_read(), -comedi_data_write(), -comedi_dio_read(), -comedi_dio_write(). -Synchronous means that the calling process -blocks until the data acquisition has finished. - - - - - -Instruction: a -comedi_do_insn() instruction -performs (possibly multiple) data acquisitions on a specified channel, -in a synchronous way. So, the -function call blocks until the whole acquisition has finished. - - -In addition, comedi_do_insnlist() executes a -list of instructions (on different channels) in -one single (blocking, synchronous) call, such that the overhead -involved in configuring each individual acquisition is reduced. - - - - - -Scan: a scan is an acquisition on a -set of different channels, with a specified sequence and -timing. - - -Scans are not directly available as stand-alone function calls in the -&comedi; API. They are the internal building blocks of a &comedi; -command (see below). - - - - - -Command: a command is -sequence of -scans, for which conditions have been specified -that determine when the acquisition will start and stop. A -comedi_command() function call generates -aynchronous data acquisition: -as soon as the command information has been filled in, the -comedi_command() function call returns, -the hardware of the card takes care of the sequencing and the timing of -the data acquisition, - and makes sure that the acquired data is delivered -in a software buffer provided by the calling process. Asynchronous -operation requires some form of callback functionality -to prevent buffer overflow: after the calling process has launched the -acquisition command, it goes off doing other things, but not after it -has configured the handler that the interface card can -use when it needs to put data in the calling process's buffer. -Interrupt routines or DMA are typical techniques to allow such -asynchronous operation. Their handlers are configured at driver load -time, and can typically not be altered from user space. - - -Buffer management is not the only asynchronous activity: a running -acquisition must eventually be stopped too, or it must be started -after the comedi_command() function call has -prepared (but not started) the hardware for the acquisition. -The command functionality is very configurable with respect to -choosing which events will signal -the starting or stopping of the programmed acquisition: external triggers, -internal triggers, end of scan interrupts, timers, etc. -The user of the driver can execute a &comedi; -instruction that sends a -trigger signal to the device driver. What the driver does exactly with -this trigger signal is determined in the specific driver. For example, -it starts or stops the ongoing acquisition. The execution of the event -associated with this trigger instruction is -synchronous with the execution of -the trigger instruction in the device driver, but it is -asynchronous with respect to the -instruction or command that initiated the current acquisition. - - -Typically, there is one synchronous triggering instruction for each -subdevice. - - - - -Note that software triggering is only relevant for commands, and not -for instructions: instructions are executed -synchronously in the sense that the instruction -call blocks until the whole instruction has finished. The command call, on -the other hand, activates an acquisition and returns before this -acquisition has finished. So, the software trigger works -asynchronously for the ongoing acquisition. - - -
- -
- -Supporting functionality - - - -The full command functionality cannot be offered by DAQ cards that -lack the hardware to autonomously sequence a series of -scans, and/or to support interrupt or DMA callback functionality. -For these cards, the command functionality must be provided in -software. And because of the quite strict real-time requirements for a -command acquisition, a real-time operating system should be used to -translate the command specification into a correctly timed sequence of -instructions. Such a correct translation is the responsibility of the -device driver developer for the card. However, -&comedi; provides the comedi_rt_timer kernel -module to support such a -virtual command execution under -RTAI or RTLinux/Free. - - - -&comedi; not only offers the API -to access the functionality of the -cards, but also to query the -capabilities of the installed 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.). - - - -Buffering is another important -aspect of device drivers: the acquired data has to be stored in such -buffers, because, in general, the application program cannot guarantee -to always be ready to provide or accept data as soon as the interface -board wants to do a read or write operation. Therefore, &comedi; -offers all functionality to configure and manage data buffers, -abstracting away the intricacies of buffer management at the bare -operating system level. - - - -As already mentioned before, &comedi; contains more than just -procedural function calls, since it also offers -event-driven -(asynchronous) 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 real-time -(RTAI or -RTLinux/Free) or non real-time, but both -contexts are encapsulated wihting the same &comedi; calls. - - - -Because multiple devices can all be active at the same time, &comedi; -provides locking primitives to -ensure atomic operations on critical sections of the code or data -structures. - - - -Finally, &comedi; offers the previously 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). - - -
- - + Overview + + &comedi; is a free software project that develops + drivers, tools, and libraries for various forms of + data acquisition: reading and writing of analog + signals; reading and writing of digital inputs/outputs; pulse and + frequency counting; pulse generation; reading encoders; etc. The + project's home page may be found at + http://www.comedi.org. + The source code is distributed in two main packages, comedi and + comedilib: + + + + Comedi is a collection of drivers for a variety + of common data acquisition plug-in boards (which are called + devices in &comedi; terminology). The drivers are + implemented as the combination of (i) one single core Linux kernel module + (called comedi) providing common + functionality, and (ii) individual low-level driver modules for + each device. + + + + + Comedilib is a separately distributed package + containing a user-space library that provides a + developer-friendly interface to the &comedi; devices. Included in the + Comedilib package are documentation, + configuration and calibration utilities, and demonstration programs. + + + + + Kcomedilib is a Linux kernel module + (distributed with the comedi package) that provides + the same interface as comedilib in kernel space, + and suitable for use by real-time kernel modules. It is + effectively a kernel library for using &comedi; from + real-time tasks. + + + + &comedi; works with standard Linux kernels, but also with its + real-time extensions RTAI and + RTLinux/GPL. + + + This section gives a high-level introduction to which functionality + you can expect from the software. More technical details and + programming examples are given in the following sections of this + document. + + +
+ + What is a <quote>device driver</quote>? + + + 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 allows 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 put a generic interface + on top of + lots of different cards for measurement and control purposes. This + type of cards are often called data acquisition + (or DAQ) cards. + + + Analog input and output cards were the first goal + of the project, but now &comedi; also provides a device + independent interface to digital input and output + cards, and counter and timer cards (including + encoders, pulse generators, frequency and pulse timers, etc.). + + + Schleef designed a structure which is a balance between + modularity and complexity: + it's fairly easy to integrate a new card because most of the + infrastructure part of other, similar drivers can be reused, and + learning the generic and hence somewhat heavier &comedi; + API doesn't scare away new contributors from integrating their drivers + into the &comedi; framework. + +
+ + +
+ + Policy vs. mechanism + + + Device drivers are often written by application programmers, that have + only their particular application in mind; especially in real-time + applications. 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 that particular 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. + + + + + So, &comedi; focuses only on the mechanism part + of DAQ interfacing. The project does not provide the policy parts, + such as Graphical User Interfaces to program and display acquisitions, + signal processing libraries, or control algorithms. + + +
+ + +
+ + A general DAQ device driver package + + + From the point of view of application developers, there are many + reasons to welcome the standardization of the API and the + architectural structure of DAQ software: + + + + + 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. However, the DAQ manufacturers + have never been able (or willing) to come up with such a + standardization effort themselves. + + + + + + Architectural 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 as an intermediate means to connect to the hardware + device. Hence, lower-level device drivers for + these PCI chips and parallel ports allow for an increased modularity + and re-useability of the software. Finding the generic + similarities and structure among different cards helps in developing + device drivers faster and with better documentation. + + + + + + + In the case of Linux as the host operating system, device driver + writers must keep the following issues in mind: + + + + Kernel space vs. User space. + The Linux operating system has two levels that require + different programming approaches. Only privileged processes + can run in the kernel, where they have access to all hardware and to + all kernel data structures. 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; these user + space programs execute much of the operating system's functionality + through system calls. + + + Device drivers typically must access specific addresses on the bus, + and hence must (at least partially) run in kernel space. Normal users + program against the API of the Comedilib + user-space library. Comedilib then handles + the necessary communication with the Comedi modules + running in kernel-space. + + + + + + Device files or device file system. + Users who write an application for a particular device, + must link their application to that device's device driver. Part of + 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. + Each device supported in the kernel may be + representated as such a user space device file, and its functionality can + may be accessed by classical Unix file I/O: + open, + close, read, + write, ioctl, and mmap. + + + + + + /proc interface. + Linux (and some other UNIX operating systems) offer a file-like + interface to attached devices (and other OS-related information) via + the /proc directories. These + files do not really exist, but it gives a familiar + interface to users, with which they can 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 directly accessing the bus addresses allocated to + the device whenever it needs + 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, of + course, has + to support its processes to use the feature). + + + + + + Real-time vs. non real-time. + If the device is to be used in a + RTLinux/GPL + + or RTAI application, + there are a few extra requirements, because not all system calls are + available in the kernel of the real-time operating systems + RTLinux/GPL + + or RTAI. + The APIs of RTAI and RTLinux/Free differ in + different ways, so the &comedi; developers have spent a lot of efforts + to make generic wrappers to the required RTOS primitives: timers, + memory allocation, registration of interrupt handlers, etc. + + + + + +
+ +
+ + DAQ signals + + + The cards supported in &comedi; have one or more of the following + signals: analog input, analog + output, digital input, digital output, counters input, counter output, + pulse input, pulse output: + + + + + Digital signals are conceptually quite simple, and don't need + much configuration: the number of channels, their addresses on the + bus, and their input or output direction. + + + + + + Analog signals are a bit more complicated. Typically, an analog + acquisition 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 may also allow + automatically sampling of a set of channels in a prescribed order. + + + + + + Pulse-based signals (counters, + timers, encoders, etc.) are conceptually + only a bit more complex than digital inputs and outputs, in that + they only add some timing specifications to the + signal. &comedi; has still only a limited number of drivers for this + kind of signals, although most of the necessary API and support + functionality is available. + + + + + In addition to these real DAQ functions, &comedi; also + offers basic timer access. + +
+ +
+ + Device hierarchy + + + &comedi; organizes all hardware according to the following + hierarchy: + + + + + Channel: the lowest-level hardware + component, that represents the properties of one single data channel; + for example, an analog input, or a digital output. + + + + + + Subdevice: a set of functionally + identical channels. For example, a set of 16 identical analog + inputs. + + + + + + Device: a set of subdevices that + are physically implemented on the + same interface card; in other words, the interface card itself. + For example, the National Instruments 6024E + device has a subdevice with 16 analog input channels, another + subdevice with two analog output channels, and a + third subdevice with eight digital inputs/outputs. + + + + + Some interface cards have extra components that don't fit in the + above-mentioned classification, such as an EEPROM to store + configuration and board parameters, or calibration inputs. These + special components are also classified as sub-devices in + &comedi;. + + +
+ +
+ + Acquisition terminology + + + + This Section introduces the terminology that this document uses when + talking about Comedi commands, which are streaming asyncronous + acquisitions. + depicts a typical acquisition sequence when running a command: + + + + + The sequence has a start and an + end. At both sides, the software + and the hardware need some finite + initialization or settling time. + + + + + + + The sequence consists of a number of identically repeated + scans. This is where the actual + data acquisitions are taking place: data is read from the card, or + written to it. Each scan also has a + begin, an + end, and a finite + setup time. Possibly, there is also + a settling time + (scan delay) at the + end of a scan. + + + So, the hardware puts a + lower boundary (the scan interval) + on the minimum time needed to complete a full scan. + + + + + + Each scan contains one or more + + conversions on particular channels, + i.e., the AD/DA converter is activated on each of the programmed + channels, and produces a sample, again in a finite + conversion time, starting from the + moment in time called the + sample time + in + (sometimes also called the timestamp), + and caused by a + triggering event, called convert. + + + In addition, some hardware has limits on the minimum + conversion interval it can achieve, + i.e., the minimum time it needs between + subsequent conversions. + For example, some A/D hardware must multiplex + the conversions from different input channels onto + one single A/D converter. Thus the conversions are done serially + in time (as shown on the Figure). + Other cards have the hardware to do two or more acquisitions in + parallel, and can perform all the conversions in a scan simultaneously. + The begin of each conversion is triggered by + some internally or externally generated pulse, e.g., a timer. + + + + + In general, not only the start of a conversion is + triggered, but also the start of a scan and of a + sequence. &comedi; provides the API to configure + what triggering source + one wants to use in each case. The API also + allows you to specify the channel list, + i.e., the sequence of channels that needs to be acquired during each + scan. + + + +
+ + Asynchronous Acquisition Sequence + + + + + + + + Figure courtesy of Kurt Müller. + + + +
+ + +
+ + +
+ + DAQ functions + + + + The basic data acquisition functionalities that &comedi; offers work + on channels, or sets of channels: + + + + + Single acquisition: &comedi; has + function calls to synchronously perform + one single data acquisition on a specified + channel: comedi_data_read, + comedi_data_read_delayed, + comedi_data_write, + comedi_dio_read, + comedi_dio_write. In addition, + the lower-level comedi_do_insn + function can + be used to perform an acquisition. + + + Synchronous means that the calling process + blocks until the data acquisition has finished. + + + + + + Mutiple synchronous acquisition: + The comedi_data_read_n function + performs (possibly multiple) data acquisitions on a specified channel, + in a synchronous way. So, the + function call blocks until the whole acquisition has finished. + The precise timing between the acquisitions is not hardware controlled. + + + In addition, comedi_do_insnlist() executes a + list of instructions in + one single (blocking, synchronous) call, such that the overhead + involved in configuring each individual acquisition is reduced. + + + + + + Command: a command is + sequence of + scans, for which conditions have been specified + that determine when the acquisition will start and stop, and + when each conversion in each scan should occur. A + comedi_command function call sets up the + aynchronous data acquisition: + as soon as the command information has been filled in, the + comedi_command function call returns. + The hardware of the card takes care of the sequencing and timing of + the data acquisition as it proceeds. + + + + + + +
+ +
+ + Supporting functionality + + + + The command functionality cannot be offered by DAQ cards that + lack the hardware to autonomously sequence a series of + scans. + For these cards, the command functionality may be provided in + software. And because of the quite strict real-time requirements for a + command acquisition, a real-time operating system should be used to + translate the command specification into a correctly timed sequence of + instructions. &comedi; provides the comedi_rt_timer kernel + module to support such a + virtual command execution under + RTAI or RTLinux/Free. + + + + &comedi; not only offers the API + to access the functionality of the + cards, but also to query the + capabilities of the installed devices. That is, a user process can + find out what channels are available, and + what their physical parameters are (range, direction of input/output, + etc.). + + + + Buffering is another important + aspect of device drivers: the acquired data has to be stored in such + buffers, because, in general, the application program cannot guarantee + to always be ready to provide or accept data as soon as the interface + board wants to do a read or write operation. &comedi; provides internal + buffers for data being streamed to/from devices via Comedi commands. + The buffer sizes are user-adjustable. + + +