/usr/share/doc/libcomedi-dev/html/index.html

<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Comedi</title><link rel="stylesheet" type="text/css" href="comedilib.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><meta name="description" content="Comedi is a free software project to interface digital acquisition (DAQ) cards. It is the combination of three complementary software items: (i) a generic, device-independent API, (ii) a collection of Linux kernel modules that implement this API for a wide range of cards, and (iii) a Linux user space library with a developer-oriented programming interface to configure and use the cards."><link rel="home" href="index.html" title="Comedi"><link rel="next" href="install.html" title="2.&#160; Configuration"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Comedi</th></tr><tr><td width="20%" align="left">&#160;</td><th width="60%" align="center">&#160;</th><td width="20%" align="right">&#160;<a accesskey="n" href="install.html">Next</a></td></tr></table><hr></div><div class="article"><div class="titlepage"><div><div><h2 class="title"><a name="idp57371728"></a>Comedi</h2></div><div><h3 class="subtitle"><i>
			The <span class="emphasis"><em>Control and Measurement Device Interface</em></span>
			handbook for Comedilib 
		</i></h3></div><div><div class="author"><h3 class="author"><span class="firstname">David</span> <span class="surname">Schleef</span></h3><code class="email">&lt;<a class="email" href="mailto:ds@schleef.org">ds@schleef.org</a>&gt;</code></div></div><div><div class="author"><h3 class="author"><span class="firstname">Frank</span> <span class="othername">Mori</span> <span class="surname">Hess</span></h3><code class="email">&lt;<a class="email" href="mailto:fmhess@users.sourceforge.net">fmhess@users.sourceforge.net</a>&gt;</code></div></div><div><div class="author"><h3 class="author"><span class="firstname">Herman</span> <span class="surname">Bruyninckx</span></h3><code class="email">&lt;<a class="email" href="mailto:Herman.Bruyninckx@mech.kuleuven.ac.be">Herman.Bruyninckx@mech.kuleuven.ac.be</a>&gt;</code></div></div><div><div class="author"><h3 class="author"><span class="firstname">Bernd</span> <span class="surname">Porr</span></h3><code class="email">&lt;<a class="email" href="mailto:tech@linux-usb-daq.co.uk">tech@linux-usb-daq.co.uk</a>&gt;</code></div></div><div><div class="author"><h3 class="author"><span class="firstname">Ian</span> <span class="surname">Abbott</span></h3><code class="email">&lt;<a class="email" href="mailto:abbotti@mev.co.uk">abbotti@mev.co.uk</a>&gt;</code></div></div><div><p class="copyright">Copyright &#169; 1998-2003 David Schleef</p></div><div><p class="copyright">Copyright &#169; 2001-2003, 2005, 2008 Frank Mori Hess</p></div><div><p class="copyright">Copyright &#169; 2002-2003 Herman Bruyninckx</p></div><div><p class="copyright">Copyright &#169; 2012 Bernd Porr</p></div><div><p class="copyright">Copyright &#169; 2012 Ian Abbott</p></div><div><div class="legalnotice"><a name="idp53352128"></a><p>
				This document is part of Comedilib.  In the context of this
				document, the term "source code" as defined by the license is
				interpreted as the XML source.
			</p><p>
				This library is free software; you can redistribute it and/or
				modify it under the terms of the GNU Lesser General Public
				License as published by the Free Software Foundation, version 2.1
				of the License.
			</p><p>
				This library is distributed in the hope that it will be useful,
				but WITHOUT ANY WARRANTY; without even the implied warranty of
				MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
				Lesser General Public License for more details.
			</p><p>
				You should have received a copy of the GNU Lesser General Public
				License along with this library; if not, write to the Free Software
				Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307
				USA.
			</p></div></div><div><div class="abstract"><p class="title"><b>Abstract</b></p><p>
				<a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> is a free software project to interface
				<span class="emphasis"><em>digital acquisition</em></span> (DAQ) cards. It is the
				combination of three complementary software items: (i) a generic,
				device-independent API, (ii) a collection of Linux kernel modules that
				implement this API for a wide range of cards, and (iii) a Linux user
				space library with a developer-oriented programming interface to
				configure and use the cards.
			</p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="index.html#introduction">1. Overview</a></span></dt><dd><dl><dt><span class="section"><a href="index.html#whatisdevicedriver">1.1. 
			What is a <span class="quote">&#8220;<span class="quote">device driver</span>&#8221;</span>?
		</a></span></dt><dt><span class="section"><a href="index.html#policymechanism">1.2. 
			Policy vs. mechanism
		</a></span></dt><dt><span class="section"><a href="index.html#generaldaqpackage">1.3. 
			A general DAQ device driver package
		</a></span></dt><dt><span class="section"><a href="index.html#comediosignals">1.4. 
			DAQ signals
		</a></span></dt><dt><span class="section"><a href="index.html#comedidevices">1.5. 
			Device hierarchy
		</a></span></dt><dt><span class="section"><a href="index.html#acquisitionterminology">1.6. 
			Acquisition terminology
		</a></span></dt><dt><span class="section"><a href="index.html#comedifunctions">1.7. 
			DAQ functions
		</a></span></dt><dt><span class="section"><a href="index.html#comedisupporting">1.8. 
			Supporting functionality
		</a></span></dt></dl></dd><dt><span class="section"><a href="install.html">2. 
		Configuration
	</a></span></dt><dd><dl><dt><span class="section"><a href="install.html#cardconfiguration">2.1. 
			Configuration
		</a></span></dt><dt><span class="section"><a href="gettinginformation.html">2.2. 
			Getting information about a card
		</a></span></dt></dl></dd><dt><span class="section"><a href="writingprograms.html">3. 
    Writing <acronym class="acronym">Comedi</acronym> programs
  </a></span></dt><dd><dl><dt><span class="section"><a href="writingprograms.html#firstprogram">3.1. 
      Your first <acronym class="acronym">Comedi</acronym> program
    </a></span></dt><dt><span class="section"><a href="convertingsamples.html">3.2. 
      Converting between integer data and physical units
    </a></span></dt><dt><span class="section"><a href="secondprogram.html">3.3. 
      Your second <acronym class="acronym">Comedi</acronym> program
    </a></span></dt><dt><span class="section"><a href="asyncprogram.html">3.4. 
      Asynchronous acquisition
    </a></span></dt><dt><span class="section"><a href="ar01s03s05.html">3.5. Further examples</a></span></dt></dl></dd><dt><span class="section"><a href="acquisitionfunctions.html">4. 
Acquisition and configuration functions
</a></span></dt><dd><dl><dt><span class="section"><a href="acquisitionfunctions.html#singleacquisition">4.1. 
Functions for single acquisition
</a></span></dt><dt><span class="section"><a href="instructions.html">4.2. 
Instructions for multiple acquisitions
</a></span></dt><dt><span class="section"><a href="instructionsconfiguration.html">4.3. 
Instructions for configuration
</a></span></dt><dt><span class="section"><a href="inttrigconfiguration.html">4.4. 
Instruction for internal triggering
</a></span></dt><dt><span class="section"><a href="commandsstreaming.html">4.5. 
Commands for streaming acquisition
</a></span></dt><dt><span class="section"><a href="slowlyvarying.html">4.6. 
Slowly-varying inputs
</a></span></dt><dt><span class="section"><a href="experimentalfunctionality.html">4.7. 
Experimental functionality
</a></span></dt></dl></dd><dt><span class="section"><a href="comedireference.html">5. 
		<acronym class="acronym">Comedi</acronym> reference
	</a></span></dt><dd><dl><dt><span class="section"><a href="comedireference.html#comedi-comedilib-h">5.1. 
Headerfiles: <code class="filename">comedi.h</code> and <code class="filename">comedilib.h</code>
</a></span></dt><dt><span class="section"><a href="constantsmacros.html">5.2. 
Constants and macros
</a></span></dt><dt><span class="section"><a href="datatypesstructures.html">5.3. 
Data types and structures
</a></span></dt><dt><span class="section"><a href="functionreference.html">5.4. Functions</a></span></dt><dt><span class="section"><a href="lowleveldrivers.html">5.5. 
    Kernel drivers
  </a></span></dt></dl></dd><dt><span class="section"><a href="driverwriting.html">6. 
Writing a <acronym class="acronym">Comedi</acronym> driver
</a></span></dt><dd><dl><dt><span class="section"><a href="driverwriting.html#userkernelhow">6.1. 
Communication user-space &#8212; kernel-space
</a></span></dt><dt><span class="section"><a href="comedikernelgeneric.html">6.2. 
Generic functionality
</a></span></dt><dt><span class="section"><a href="boardspecific.html">6.3. 
Board-specific functionality
</a></span></dt><dt><span class="section"><a href="drivercallbacks.html">6.4. 
Callbacks, events and interrupts
</a></span></dt><dt><span class="section"><a href="drivercaveats.html">6.5. 
Device driver caveats
</a></span></dt><dt><span class="section"><a href="integratingdriver.html">6.6. 
Integrating the driver in the <acronym class="acronym">Comedi</acronym> library
</a></span></dt></dl></dd><dt><span class="glossary"><a href="comedilib-glossary.html">
    Glossary
  </a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction"></a>1.&#160;Overview</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="index.html#whatisdevicedriver">1.1. 
			What is a <span class="quote">&#8220;<span class="quote">device driver</span>&#8221;</span>?
		</a></span></dt><dt><span class="section"><a href="index.html#policymechanism">1.2. 
			Policy vs. mechanism
		</a></span></dt><dt><span class="section"><a href="index.html#generaldaqpackage">1.3. 
			A general DAQ device driver package
		</a></span></dt><dt><span class="section"><a href="index.html#comediosignals">1.4. 
			DAQ signals
		</a></span></dt><dt><span class="section"><a href="index.html#comedidevices">1.5. 
			Device hierarchy
		</a></span></dt><dt><span class="section"><a href="index.html#acquisitionterminology">1.6. 
			Acquisition terminology
		</a></span></dt><dt><span class="section"><a href="index.html#comedifunctions">1.7. 
			DAQ functions
		</a></span></dt><dt><span class="section"><a href="index.html#comedisupporting">1.8. 
			Supporting functionality
		</a></span></dt></dl></div><p>
		<a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> is a <span class="emphasis"><em>free software</em></span> project that develops
		drivers, tools, and libraries for various forms of
		<span class="emphasis"><em>data acquisition</em></span>: reading and writing of analog
		signals; reading and writing of digital inputs/outputs; pulse and
		frequency counting; pulse generation; reading encoders; etc.
		The source code is distributed in two main packages, comedi and
		comedilib:
		</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
					<span class="strong"><strong>Comedi</strong></span> is a collection of drivers for a variety
					of common data acquisition plug-in boards (which are called
					<span class="quote">&#8220;<span class="quote">devices</span>&#8221;</span> in <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> terminology). The drivers are
					implemented as the combination of (i) one single core Linux kernel module
					(called <span class="quote">&#8220;<span class="quote"><code class="literal">comedi</code></span>&#8221;</span>) providing common
					functionality, and (ii) individual low-level driver modules for
					each device.
				</p></li><li class="listitem"><p>
					<span class="strong"><strong>Comedilib</strong></span> is a separately distributed package
					containing a user-space library that provides a
					developer-friendly interface to the <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> devices. Included in the
					<span class="emphasis"><em>Comedilib</em></span> package are documentation,
					configuration and calibration utilities, and demonstration programs.
				</p></li><li class="listitem"><p>
					<span class="strong"><strong>Kcomedilib</strong></span> is a Linux kernel module
					(distributed with the <code class="literal">comedi</code> package) that provides
					the same interface as <span class="emphasis"><em>comedilib</em></span> in kernel space,
					and suitable for use by <span class="emphasis"><em>real-time</em></span> kernel modules. It is
					effectively a <span class="quote">&#8220;<span class="quote">kernel library</span>&#8221;</span> for using <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> from
					real-time tasks.
				</p></li></ul></div><p>
		<a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> works with standard Linux kernels, but also with its
		real-time extensions <a class="ulink" href="http://www.rtai.org" target="_top">RTAI</a> and
		<a class="ulink" href="http://www.rtlinux-gpl.org/" target="_top">RTLinux/GPL</a>.
	</p><p>
		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.
	</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="whatisdevicedriver"></a>1.1.&#160;
			What is a <span class="quote">&#8220;<span class="quote">device driver</span>&#8221;</span>?
		</h3></div></div></div><p>
			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.
		</p><p>
			David Schleef started the <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> 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 <span class="emphasis"><em>data acquisition</em></span>
			(or <span class="strong"><strong>DAQ</strong></span>) cards.
		</p><p>
			<span class="emphasis"><em>Analog input and output</em></span> cards were the first goal
			of the project, but now <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> also provides a device
			independent interface to digital <span class="emphasis"><em>input and output</em></span>
			cards, and <span class="emphasis"><em>counter and timer</em></span> cards (including
			encoders, pulse generators, frequency and pulse timers, etc.).
		</p><p>
			Schleef designed a structure which is a balance between
			<span class="emphasis"><em>modularity</em></span> and <span class="emphasis"><em>complexity</em></span>:
			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 <span class="quote">&#8220;<span class="quote">heavier</span>&#8221;</span> <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a>
			API doesn't scare away new contributors from integrating their drivers
			into the <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> framework.
		</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="policymechanism"></a>1.2.&#160;
			Policy vs. mechanism
		</h3></div></div></div><p>
			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:
			</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
						<span class="strong"><strong>Mechanism.</strong></span>
						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.
					</p></li><li class="listitem"><p>
						<span class="strong"><strong>Policy.</strong></span>
						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.
					</p></li></ul></div><p>
			So, <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> focuses only on the <span class="emphasis"><em>mechanism</em></span> 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.
		</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="generaldaqpackage"></a>1.3.&#160;
			A general DAQ device driver package
		</h3></div></div></div><p>
			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:
			</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
						<span class="strong"><strong>API</strong></span>: 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.
					</p></li><li class="listitem"><p>
						<span class="strong"><strong>Architectural structure</strong></span>:
						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, <span class="quote">&#8220;<span class="quote">lower-level</span>&#8221;</span> 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.
					</p></li></ul></div><p>
		</p><p>
			In the case of Linux as the host operating system, device driver
			writers must keep the following issues in mind:
			</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
					<span class="strong"><strong>Kernel space vs. User space.</strong></span>
					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 <span class="emphasis"><em>system calls</em></span>.
				</p><p>
					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 <span class="emphasis"><em>Comedilib</em></span>
					user-space library.  <span class="emphasis"><em>Comedilib</em></span> then handles
					the necessary communication with the <span class="emphasis"><em>Comedi</em></span> modules
					running in kernel-space.
				</p></li><li class="listitem"><p>
					<span class="strong"><strong>Device files or device file system.</strong></span>
					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 <span class="quote">&#8220;<span class="quote">files</span>&#8221;</span>
					in the <code class="filename">/dev</code> 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:
					<code class="function">open</code>,
					<code class="function">close</code>, <code class="function">read</code>,
					<code class="function">write</code>, <code class="function">ioctl</code>, and <code class="function">mmap</code>.
				</p></li><li class="listitem"><p>
					<span class="strong"><strong><code class="filename">/proc</code> interface.</strong></span>
					Linux (and some other UNIX operating systems) offer a file-like
					interface to attached devices (and other OS-related information) via
					the <code class="filename">/proc</code> directories. These
					<span class="quote">&#8220;<span class="quote">files</span>&#8221;</span> do not really exist, but it gives a familiar
					interface to users, with which they can inspect the current status of
					each device.
				</p></li><li class="listitem"><p>
					<span class="strong"><strong>Direct Memory Access (DMA) vs. Programmed
					Input/Output (PIO).</strong></span>
					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 <span class="quote">&#8220;<span class="quote">talk</span>&#8221;</span> 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).
				</p></li><li class="listitem"><p>
					<span class="strong"><strong>Real-time vs. non real-time.</strong></span>
					If the device is to be used in a
					<a class="ulink" href="http://www.rtlinux-gpl.org/" target="_top">RTLinux/GPL
					</a>
					or <a class="ulink" href="http://www.rtai.org" target="_top">RTAI</a> application,
					there are a few extra requirements, because not all system calls are
					available in the kernel of the real-time operating systems
					<a class="ulink" href="http://www.rtlinux-gpl.org/" target="_top">RTLinux/GPL
					</a>
					or <a class="ulink" href="http://www.rtai.org" target="_top">RTAI</a>.
					The APIs of RTAI and RTLinux/Free differ in
					different ways, so the <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> developers have spent a lot of efforts
					to make generic wrappers to the required RTOS primitives: timers,
					memory allocation, registration of interrupt handlers, etc.
				</p></li></ul></div><p>
		</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="comediosignals"></a>1.4.&#160;
			DAQ signals
		</h3></div></div></div><p>
			The cards supported in <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> have one or more of the following
			<span class="strong"><strong>signals</strong></span>: analog input, analog
			output, digital input, digital output, counters input, counter output,
			pulse input, pulse output:
			</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
						<span class="strong"><strong>Digital</strong></span> 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.
					</p></li><li class="listitem"><p>
						<span class="strong"><strong>Analog</strong></span> 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., <code class="literal">-10V</code> and
						<code class="literal">+10V</code>).  The card's electronics may also allow
						automatically sampling of a set of channels in a prescribed order.
					</p></li><li class="listitem"><p>
						<span class="strong"><strong>Pulse</strong></span>-based signals (counters,
						timers, encoders, etc.) are conceptually
						only a bit more complex than digital inputs and outputs, in that
						they only add some <span class="emphasis"><em>timing specifications</em></span> to the
						signal. <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> has still only a limited number of drivers for this
						kind of signals, although most of the necessary API and support
						functionality is available.
					</p></li></ul></div><p>
			In addition to these <span class="quote">&#8220;<span class="quote">real</span>&#8221;</span> DAQ functions, <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> also
			offers basic timer access.
		</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="comedidevices"></a>1.5.&#160;
			Device hierarchy
		</h3></div></div></div><p>
			<a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> organizes all hardware according to the following
			hierarchy:
			</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
						<span class="strong"><strong>Channel</strong></span>: the lowest-level hardware
						component, that represents the properties of one single data channel;
						for example, an analog input, or a digital output.
					</p></li><li class="listitem"><p>
						<span class="strong"><strong>Subdevice</strong></span>: a set of functionally
						identical channels. For example, a set of 16 identical analog
						inputs.
					</p></li><li class="listitem"><p>
						<span class="strong"><strong>Device</strong></span>: a set of subdevices that
						are physically implemented on the
						same interface card; in other words, the interface card itself.
						For example, the <code class="literal">National Instruments 6024E</code>
						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.
					</p></li></ul></div><p>
			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 <span class="quote">&#8220;<span class="quote">sub-devices</span>&#8221;</span> in
			<a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a>.
		</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="acquisitionterminology"></a>1.6.&#160;
			Acquisition terminology
		</h3></div></div></div><p>
			This Section introduces the terminology that this document uses when
			talking about Comedi <span class="quote">&#8220;<span class="quote">commands</span>&#8221;</span>, which are streaming asyncronous
			acquisitions. <a class="xref" href="index.html#fig-acq-seq" title="Figure&#160;1.&#160; Asynchronous Acquisition Sequence">Figure&#160;1</a>
			depicts a typical acquisition sequence when running a command:
			</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
						The sequence has a <span class="strong"><strong>start</strong></span> and an
						<span class="strong"><strong>end</strong></span>. At both sides, the software
						and the hardware need some finite
						<span class="strong"><strong>initialization or settling time</strong></span>.
					</p></li><li class="listitem"><p>
						<a name="scan"></a>
						The sequence consists of a number of identically repeated
						<span class="strong"><strong>scans</strong></span>. 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
						<span class="strong"><strong>begin</strong></span>, an
						<span class="strong"><strong>end</strong></span>, and a finite
						<span class="strong"><strong>setup time</strong></span>. Possibly, there is also
						a settling time
						(<span class="quote">&#8220;<span class="quote"><span class="strong"><strong>scan delay</strong></span></span>&#8221;</span>) at the
						end of a scan.
					</p><p>
						So, the hardware puts a
						lower boundary (the <span class="strong"><strong>scan interval</strong></span>)
						on the minimum time needed to complete a full scan.
					</p></li><li class="listitem"><p>
						Each scan contains one or more
						<a name="conversion"></a>
						<span class="strong"><strong>conversions</strong></span> 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
						<span class="strong"><strong>conversion time</strong></span>, starting from the
						moment in time called the
						<span class="strong"><strong>sample time</strong></span>
						in <a class="xref" href="index.html#fig-acq-seq" title="Figure&#160;1.&#160; Asynchronous Acquisition Sequence">Figure&#160;1</a>
						(sometimes also called the <span class="quote">&#8220;<span class="quote">timestamp</span>&#8221;</span>),
						and caused by a
						triggering event, called <span class="strong"><strong>convert</strong></span>.
					</p><p>
						In addition, some hardware has limits on the minimum
						<span class="strong"><strong>conversion interval</strong></span> it can achieve,
						i.e., the minimum time it needs between
						<span class="emphasis"><em>subsequent</em></span> conversions.
						For example, some A/D hardware must <span class="emphasis"><em>multiplex</em></span>
						the conversions from different input channels onto
						one single A/D converter.  Thus the conversions are done serially
						in time (as shown in <a class="xref" href="index.html#fig-acq-seq" title="Figure&#160;1.&#160; Asynchronous Acquisition Sequence">Figure&#160;1</a>).
						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 <span class="quote">&#8220;<span class="quote">triggered</span>&#8221;</span> by
						some internally or externally generated pulse, e.g., a timer.
					</p></li></ul></div><p>
			In general, not only the start of a <span class="emphasis"><em>conversion</em></span> is
			triggered, but also the start of a <span class="emphasis"><em>scan</em></span> and of a
			<span class="emphasis"><em>sequence</em></span>. <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> provides the API to configure
			what <a class="link" href="commandsstreaming.html#comedicmdsources" title="4.5.3.&#160; The command trigger events">triggering source</a>
			one wants to use in each case. The API also
			allows you to specify the <span class="strong"><strong>channel list</strong></span>,
			i.e., the sequence of channels that needs to be acquired during each
			scan.
		</p><p>
			</p><div class="figure"><a name="fig-acq-seq"></a><p class="title"><b>Figure&#160;1.&#160;
					Asynchronous Acquisition Sequence
				</b></p><div class="figure-contents"><div class="mediaobject"><img src="acq-seq.gif" alt="Asynchronous Acquisition Sequence"><div class="caption"><p>
						Figure courtesy of Kurt M&#252;ller.
					</p></div></div></div></div><p><br class="figure-break">
		</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="comedifunctions"></a>1.7.&#160;
			DAQ functions
		</h3></div></div></div><p>
			The basic data acquisition functionalities that <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> offers work
			on channels, or sets of channels:
			</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
						<span class="strong"><strong>Single acquisition</strong></span>: <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> has
						function calls to synchronously perform
						<span class="emphasis"><em>one single</em></span> data acquisition on a specified
						channel: <code class="function">comedi_data_read</code>,
						<code class="function">comedi_data_read_delayed</code>,
						<code class="function">comedi_data_write</code>,
						<code class="function">comedi_dio_read</code>,
						<code class="function">comedi_dio_write</code>.  In addition,
						the lower-level <code class="function">comedi_do_insn</code>
						function can
						be used to perform an acquisition.
					</p><p>
						<span class="quote">&#8220;<span class="quote">Synchronous</span>&#8221;</span> means that the calling process
						blocks until the data acquisition has finished.
					</p></li><li class="listitem"><p>
						<span class="strong"><strong>Mutiple synchronous acquisition</strong></span>:
						The <code class="function">comedi_data_read_n</code> function
						performs (possibly multiple) data acquisitions on a specified channel,
						in a <span class="strong"><strong>synchronous</strong></span> way. So, the
						function call blocks until the whole acquisition has finished.
						The precise timing between the acquisitions is not hardware controlled.
					</p><p>
						In addition, <code class="function">comedi_do_insnlist()</code> executes a
						<span class="emphasis"><em>list</em></span> of instructions in
						one single (blocking, synchronous) call, such that the overhead
						involved in configuring each individual acquisition is reduced.
					</p></li><li class="listitem"><p>
						<span class="strong"><strong>Command</strong></span>: a command is
						<span class="emphasis"><em>sequence</em></span> of
						<span class="emphasis"><em>scans</em></span>, 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
						<code class="function">comedi_command</code> function call sets up the
						<span class="strong"><strong>aynchronous</strong></span> data acquisition:
						as soon as the command information has been filled in, the
						<code class="function">comedi_command</code> function call returns.
						The hardware of the card takes care of the sequencing and timing of
						the data acquisition as it proceeds.
					</p></li></ul></div><p>
		</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="comedisupporting"></a>1.8.&#160;
			Supporting functionality
		</h3></div></div></div><p>
			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. <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> provides the <code class="function">comedi_rt_timer</code> kernel
			module to support such a
			<span class="strong"><strong>virtual command execution</strong></span> under
			<acronym class="acronym">RTAI</acronym> or <acronym class="acronym">RTLinux/Free</acronym>.
		</p><p>
			<a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> not only offers the API
			<span class="strong"><strong>to access</strong></span> the functionality of the
			cards, but also <span class="strong"><strong>to query</strong></span> 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.).
		</p><p>
			<span class="strong"><strong>Buffering</strong></span> 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. <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> provides internal
			buffers for data being streamed to/from devices via Comedi commands.
			The buffer sizes are user-adjustable.
		</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left">&#160;</td><td width="20%" align="center">&#160;</td><td width="40%" align="right">&#160;<a accesskey="n" href="install.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">&#160;</td><td width="20%" align="center">&#160;</td><td width="40%" align="right" valign="top">&#160;2.&#160;
		Configuration
	</td></tr></table></div></body></html>
libcomedi-dev 0.10.1-1ubuntu2 / usr / share / doc / libcomedi-dev / html / index.html
