/usr/share/doc/libcomedi-dev/html/index.html is in libcomedi-dev 0.10.1-1ubuntu2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 | <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.  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"> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <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"><<a class="email" href="mailto:ds@schleef.org">ds@schleef.org</a>></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"><<a class="email" href="mailto:fmhess@users.sourceforge.net">fmhess@users.sourceforge.net</a>></code></div></div><div><div class="author"><h3 class="author"><span class="firstname">Herman</span> <span class="surname">Bruyninckx</span></h3><code class="email"><<a class="email" href="mailto:Herman.Bruyninckx@mech.kuleuven.ac.be">Herman.Bruyninckx@mech.kuleuven.ac.be</a>></code></div></div><div><div class="author"><h3 class="author"><span class="firstname">Bernd</span> <span class="surname">Porr</span></h3><code class="email"><<a class="email" href="mailto:tech@linux-usb-daq.co.uk">tech@linux-usb-daq.co.uk</a>></code></div></div><div><div class="author"><h3 class="author"><span class="firstname">Ian</span> <span class="surname">Abbott</span></h3><code class="email"><<a class="email" href="mailto:abbotti@mev.co.uk">abbotti@mev.co.uk</a>></code></div></div><div><p class="copyright">Copyright © 1998-2003 David Schleef</p></div><div><p class="copyright">Copyright © 2001-2003, 2005, 2008 Frank Mori Hess</p></div><div><p class="copyright">Copyright © 2002-2003 Herman Bruyninckx</p></div><div><p class="copyright">Copyright © 2012 Bernd Porr</p></div><div><p class="copyright">Copyright © 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">“<span class="quote">device driver</span>”</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 — 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. 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">“<span class="quote">device driver</span>”</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">“<span class="quote">devices</span>”</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">“<span class="quote"><code class="literal">comedi</code></span>”</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">“<span class="quote">kernel library</span>”</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. 
What is a <span class="quote">“<span class="quote">device driver</span>”</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">“<span class="quote">heavier</span>”</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. 
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. 
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">“<span class="quote">lower-level</span>”</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">“<span class="quote">files</span>”</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">“<span class="quote">files</span>”</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">“<span class="quote">talk</span>”</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. 
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">“<span class="quote">real</span>”</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. 
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">“<span class="quote">sub-devices</span>”</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. 
Acquisition terminology
</h3></div></div></div><p>
This Section introduces the terminology that this document uses when
talking about Comedi <span class="quote">“<span class="quote">commands</span>”</span>, which are streaming asyncronous
acquisitions. <a class="xref" href="index.html#fig-acq-seq" title="Figure 1.  Asynchronous Acquisition Sequence">Figure 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">“<span class="quote"><span class="strong"><strong>scan delay</strong></span></span>”</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 1.  Asynchronous Acquisition Sequence">Figure 1</a>
(sometimes also called the <span class="quote">“<span class="quote">timestamp</span>”</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 1.  Asynchronous Acquisition Sequence">Figure 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">“<span class="quote">triggered</span>”</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.  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 1. 
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ü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. 
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">“<span class="quote">Synchronous</span>”</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. 
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"> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="install.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"> </td><td width="40%" align="right" valign="top"> 2. 
Configuration
</td></tr></table></div></body></html>
|