diff --git a/doc/driverwriting.sgml b/doc/driverwriting.sgml index b8c10f6..6476826 100644 --- a/doc/driverwriting.sgml +++ b/doc/driverwriting.sgml @@ -54,8 +54,8 @@ How to use DMA and interrupts? What are the addresses and meanings of all the card's registers? -This information is to be found in the so-called “register level -manual” of the card. Without it, coding a device driver is close +This information is to be found in the so-called register level +manual of the card. Without it, coding a device driver is close to hopeless. It is also something that &comedi; (and hence also this handbook) cannot give any support or information for: board manufacturers all use their own design and nomenclature. @@ -263,7 +263,7 @@ struct comedi_lrange_struct{ comedi_subdevice The subdevice is the smallest &comedi; entity that can be used for -“stand-alone” DAQ, so it is no surprise that it is +stand-alone DAQ, so it is no surprise that it is quite big: struct comedi_subdevice_struct{ @@ -516,7 +516,7 @@ the same driver files. To help device driver writers, -&comedi; provides the “skeleton” of a new device driver, +&comedi; provides the skeleton of a new device driver, in the comedi/drivers/skel.c file. Before starting to write a new driver, make sure you understand this file, and compare it to what you find in the other already available @@ -544,7 +544,7 @@ module): mydriver_attach(); mydriver_detach(); -In the “attach” function, memory is allocated for the +In the attach function, memory is allocated for the necessary data structures, all properties of a device and its subdevices are defined, and filled in in the generic &comedi; data structures. As part of this, pointers @@ -683,7 +683,7 @@ Continuous acquisition is tyically an asynchronous activity: the function call that has set the acquisition in motion has returned before the acquisition has finished (or even started). So, not only the acquired data must be -sent back to the user's buffer “in the background”, but +sent back to the user's buffer in the background, but various types of asynchronous event handling can be needed during the acquisition: @@ -706,7 +706,7 @@ an acquisition scan, etc. The device driver writer can register a driver-supplied -”callback” function, that is called at the end of each +callback function, that is called at the end of each hardware interrupt routine. @@ -741,7 +741,7 @@ The possible event bits are: COMEDI_CB_EOA: execute the callback at the -“End Of-Acquisition”. +End Of-Acquisition. @@ -749,7 +749,7 @@ The possible event bits are: COMEDI_CB_EOS: execute the callback at the -“End-Of-Scan”. +End-Of-Scan. @@ -786,7 +786,7 @@ A few things to strive for when writing a new driver: -Some DAQ cards consist of different “layers” of hardware, +Some DAQ cards consist of different layers of hardware, which can each be given their own device driver. Examples are: some of the National Instruments cards, that all share the same Mite PCI driver chip; the ubiquitous parallel @@ -846,20 +846,20 @@ things have to be done: Choose a senseful name for the source code file. Let's assume here -that you call it “mydriver.c” +that you call it mydriver.c -Put your new driver into “comedi/drivers/mydriver.c”. +Put your new driver into comedi/drivers/mydriver.c. -Edit “comedi/Config.in” and add a new -“dep_tristate” line (look at the other examples). Invent a +Edit comedi/Config.in and add a new +dep_tristate line (look at the other examples). Invent a senseful name for the driver's variable. For example: dep_tristate 'MYDRIVER' CONFIG_COMEDI_MYDRIVER $CONFIG_COMEDI @@ -869,7 +869,7 @@ senseful name for the driver's variable. For example: -Add a line to “comedi/drivers/Makefile.in”, using your +Add a line to comedi/drivers/Makefile.in, using your freshly defined variable, i.e., CONFIG_COMEDI_MYDRIVER. diff --git a/doc/install.sgml b/doc/install.sgml index 897af20..c5b3133 100644 --- a/doc/install.sgml +++ b/doc/install.sgml @@ -30,7 +30,7 @@ its man page now): PATH=/sbin:/usr/sbin:/usr/local/sbin:$PATH comedi_config /dev/comedi0 labpc-1200 0x260,3 -This command says that the “file” +This command says that the file /dev/comedi0 can be used to access the &comedi; device that uses the labpc-1200 board, and that you give it two run-time parameters (0x260 and diff --git a/doc/intro.sgml b/doc/intro.sgml index a8bd309..3d87582 100644 --- a/doc/intro.sgml +++ b/doc/intro.sgml @@ -27,9 +27,9 @@ project's source code is distributed in two packages, 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 +devices in &comedi; terminology). The drivers are implemented as the combination of (i) one single core Linux kernel module -(called “comedi”) providing common +(called comedi) providing common functionality, and (ii) individual low-level driver modules for each device. @@ -51,7 +51,7 @@ configuration and calibration utilities, and demonstration programs. (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 +effectively a kernel library for using &comedi; from real-time tasks. @@ -70,7 +70,7 @@ document.
-What is a “device driver”? +What is a <quote>device driver</quote>? A device driver is a piece of software that interfaces a particular @@ -100,7 +100,7 @@ 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; +learning the generic and hence somewhat heavier &comedi; API doesn't scare away new contributors from integrating their drivers into the &comedi; framework. @@ -188,7 +188,7 @@ standardization effort themselves. 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 +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 @@ -232,7 +232,7 @@ events. 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” +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 @@ -250,7 +250,7 @@ representative as such a user space device file, and its functionality can 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 +files do not really exist, but it gives a familiar interface to users, with which they can inspect the current status of each device. @@ -264,7 +264,7 @@ Input/Output (PIO). 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. + 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). @@ -341,7 +341,7 @@ functionality is available. -In addition to these “real” DAQ functions, &comedi; also +In addition to these real DAQ functions, &comedi; also offers basic timer access.
@@ -363,7 +363,7 @@ 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. +values 0 and 1; etc. @@ -396,7 +396,7 @@ sub-device with two analog output channels, and a 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 +special components are also classified as sub-devices in &comedi;. @@ -409,7 +409,7 @@ Acquisition terminology This Section introduces the terminology that this document uses when -talking about “acquisitions.” +talking about acquisitions. depicts a typical acquisition sequence: @@ -433,7 +433,7 @@ written to it. Each scan also has a end, and a finite setup time. Possibly, there is also a settling time -(“scan delay”) at the +(scan delay) at the end of a scan. @@ -454,7 +454,7 @@ channels, and produces a sample, again in a finite moment in time called the sample time in -(sometimes also called the “timestamp”), +(sometimes also called the timestamp), and caused by a triggering event, called convert. In addition, each hardware has limits on the minimum @@ -467,7 +467,7 @@ 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 +parallel. The begin of each conversion is triggered by some internally or externally generated pulse, e.g., a timer. @@ -525,7 +525,7 @@ channel: comedi_data_read(), comedi_data_write(), comedi_dio_read(), comedi_dio_write(). -“Synchronous” means that the calling process +Synchronous means that the calling process blocks until the data acquisition has finished. @@ -573,10 +573,10 @@ 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 +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 +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 @@ -666,7 +666,7 @@ operating system level. As already mentioned before, &comedi; contains more than just procedural function calls, since it also offers event-driven -(“asynchronous”) functionality: +(asynchronous) functionality: the data acquisition can signal its completion by means of an interrupt or a callback function call. @@ -691,11 +691,11 @@ structures. Finally, &comedi; offers the previously mentioned -“high-level” interaction, i.e., at the level of user space +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 +through the files in the /proc directory (which allow to inspect the status of a &comedi; device). diff --git a/doc/other.sgml b/doc/other.sgml index dfee185..3f84ef4 100644 --- a/doc/other.sgml +++ b/doc/other.sgml @@ -9,7 +9,7 @@ Acquisition and configuration functions This Section gives an overview of all &comedi; functions with which application programmers can implement their data acquisition. (With -“acquisition” we mean all possible kinds of interfacing +acquisition we mean all possible kinds of interfacing with the cards: input, output, configuration, streaming, etc.) explains the function calls in full detail. @@ -163,11 +163,11 @@ the device. lsampl_t: this -“data structure” represents one single sample. On most +data structure represents one single sample. On most architectures, it's nothing more than a 32 bits value. Internally, &comedi; does some conversion from raw sample data to -“correct” integers. This is called “data -munging”. +correct integers. This is called data +munging. @@ -286,7 +286,7 @@ read or write values on multiple digital I/O channels. -INSN_GTOD: the instruction performs a “Get Time Of Day” +INSN_GTOD: the instruction performs a Get Time Of Day acquisition. @@ -401,7 +401,7 @@ depends on the card and its particular driver. The data[0] field of the INSN_INTTRIG instruction is reserved for future use, and should be set -to “0”. +to 0. @@ -582,7 +582,7 @@ The specifies the sequence of channels and gains (and analog references) that should be stepped through for each scan. The elements of the chanlist array should be -initialized by “packing” the channel, range and reference +initialized by packing the channel, range and reference information together with the CR_PACK() @@ -635,7 +635,7 @@ structure). And each event source can have a corresponding argument (the *_arg members of the comedi_cmd data structure) whose meaning depends on the type of source trigger. -For example, to specify an external digital line “3” as a +For example, to specify an external digital line 3 as a source (in general, any of the five event sources), you would use src=TRIG_EXT and @@ -819,7 +819,7 @@ TRIG_NONE: perform continuous acquisition, until stopped using Its argument is reserved and should be set to 0. -(“Reserved” +(Reserved means that unspecified things could happen if it is set to something else but 0.) @@ -881,7 +881,7 @@ The command flags The flags field in the command data structure -is used to specify some “behaviour” of the acquisitions in +is used to specify some behaviour of the acquisitions in a command. The meaning of the field is as follows: @@ -906,7 +906,7 @@ nothing. TRIG_WAKE_EOS: -where “EOS” stands for “End of Scan”. Some +where EOS stands for End of Scan. Some drivers will change their behaviour when this flag is set, trying to transfer data at the end of every scan (instead of, for example, passing data in chunks whenever the board's hardware data buffer is @@ -954,14 +954,14 @@ to do…? TRIG_DITHER: enable dithering? Dithering is a software technique to -smooth the influence of discretization “noise”. +smooth the influence of discretization noise. -TRIG_DEGLITCH: enable deglitching? Another “noise” +TRIG_DEGLITCH: enable deglitching? Another noise smoothing technique. @@ -1050,12 +1050,12 @@ Obviously, there are limitations to this: -you are ultimately limited by “Spurious Free Dynamic -Range”. This SFDR is one of the popular measures to quantify how +you are ultimately limited by Spurious Free Dynamic +Range. This SFDR is one of the popular measures to quantify how much noise a signal carries. If you take a Fourier transform of your -signal, you will see several “peaks” in the transform: one +signal, you will see several peaks in the transform: one or more of the fundamental harmonics of the measured signal, and lots -of little “peaks” (called “spurs”) caused by +of little peaks (called spurs) caused by noise. The SFDR is then the difference between the amplitude of the fundamental harmonic and of the largest spur (at frequencies below half of the Nyquist frequency of the DAQ sampler!). @@ -1168,8 +1168,8 @@ this yet)) When one or several digital inputs are used to modify an output value, either an accumulator or a single digital line or bit, a bitfield structure is typically used in the &comedi; interface. -The digital inputs have two properties, “sensitive” inputs -and “modifier” inputs. Edge transitions on sensitive +The digital inputs have two properties, sensitive inputs +and modifier inputs. Edge transitions on sensitive inputs cause changes in the output signal, whereas modifier inputs change the effect of edge transitions on sensitive inputs. Note that inputs can be both modifier inputs and sensitive inputs. diff --git a/doc/reference.sgml b/doc/reference.sgml index 3552a7a..5c4a29f 100644 --- a/doc/reference.sgml +++ b/doc/reference.sgml @@ -70,7 +70,7 @@ want the device to use. It can be any of the following: AREF_COMMON - is for a “common” reference (the low inputs of all the + is for a common reference (the low inputs of all the channels are tied together, but are isolated from ground). @@ -155,7 +155,7 @@ subdevice_struct The data type subdevice_struct is used to store information about a subdevice. This structure is usually filled in -automatically when the driver is loaded (“attached”), so +automatically when the driver is loaded (attached), so programmers need not access this data structure directly. typedef struct subdevice_struct subdevice; @@ -200,7 +200,7 @@ comedi_devinfo The data type comedi_devinfo is used to store information about a device. This structure is usually filled in -automatically when the driver is loaded (“attached”), so +automatically when the driver is loaded (attached), so programmers need not access this data structure directly. typedef struct comedi_devinfo_struct comedi_devinfo; diff --git a/doc/tutorial.sgml b/doc/tutorial.sgml index 65a8684..5f73809 100644 --- a/doc/tutorial.sgml +++ b/doc/tutorial.sgml @@ -56,7 +56,7 @@ The can only be successful if the comedi0 device file is configured to point to a valid &comedi; driver. explains -how this driver is linked to the “device file”. +how this driver is linked to the device file. The code above is basically the guts of demo/inp.c, without error checking or fancy @@ -98,16 +98,16 @@ and 4095 the highest. &comedi; compensates for anything else the manual for your device says. However, you probably prefer to have this number translated to a voltage. Naturally, as a good programmer, your first -question is: “How do I do this in a device-independent -manner?” +question is: How do I do this in a device-independent +manner? Most devices give you a choice of gain and unipolar/bipolar input, and &comedi; allows you to select which of these to use. This -parameter is called the “range parameter,” since it -specifies the “input range” for analog input (or -“output range” for analog output.) The range parameter +parameter is called the range parameter, since it +specifies the input range for analog input (or +output range for analog output.) The range parameter represents both the gain and the unipolar/bipolar aspects. @@ -163,7 +163,7 @@ or are dimensionless (e.g., for digital I/O). -“Could it get easier?” you say. Well, yes. Use +Could it get easier? you say. Well, yes. Use the function comedi_to_phys() comedi_to_phys(), which converts data values to physical units. Call it using something like