Add `chanlist_len` to `comedi_get_cmd_generic_timed()` calls in Python demos.

[comedilib.git] / doc / driverwriting.xml

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % comedilib_entities SYSTEM "comedilib.ent">
%comedilib_entities;
]>

<section id="driverwriting">
<title>
Writing a &comedi; driver
</title>

<para>
This Section explains the most important implementations aspects of
the &comedi; device drivers. It tries to give the interested device
driver writer an overview of the different steps required to write a
new device driver.
</para>
<para>
This Section does <emphasis>not</emphasis> explain all implementation
details of the &comedi; software itself: &comedi; has once and for
all solved lots of boring but indispensable infrastructural things,
such as: timers, management of which drivers
are active, memory management for drivers and buffers, wrapping
of RTOS-specific interfaces, interrupt handler management, general
error handling, the <filename role="directory">/proc</filename>
interface, etc. So,
the device driver writers can concentrate on the interesting stuff:
implementing their specific interface card's DAQ functionalities.
</para>
<para>
In order to make a decent &comedi; device driver, you must
know the answers to the following questions:
<itemizedlist>

<listitem>
<para>
How does the
<link linkend="userkernelhow">communication</link> between user space
and kernel space work?
</para>
</listitem>

<listitem>
<para>
What functionality is provided by the
<link linkend="comedikernelgeneric">generic</link> kernel-space
&comedi; functions, and what must be provided for each
<link linkend="boardspecific">specific new driver</link>?
</para>
</listitem>

<listitem>
<para>
How to use <link linkend="drivercallbacks">DMA and interrupts</link>?
</para>
</listitem>

<listitem>
<para>
What are the addresses and meanings of all the card's registers?
</para>
<para>
This information is to be found in the so-called <quote>register level
manual</quote> 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.
</para>
</listitem>

</itemizedlist>
</para>

<section id="userkernelhow">
<title>
Communication user space-kernel space
</title>

<para>
In user space, you interact with the functions implemented in the
<filename role="directory">/usr/src/comedilib</filename> directory. Most
of the device driver core of the Comedilib library is found in
<filename role="directory">lib</filename> subdirectory.
</para>
<para>
All user-space &comedi;
<link linkend="instructions">instructions</link> and
<link linkend="commandsstreaming">commands</link>
are transmitted to kernel space through a traditional
<function>ioctl</function> system call.
(See <filename>/usr/src/comedilib/lib/ioctl.c</filename>.)
The user space information command is <emphasis>encoded</emphasis> as
a number in the <function>ioctl</function> call, and decoded in the
kernel space library.  There, they are executed by their kernel-space
counterparts.  This is done in the
<filename>/usr/src/comedi/comedi/comedi_fops.c</filename> file: the
<function>comedi_ioctl()</function> function processes the results of
the <function>ioctl</function> system call, interprets its contents,
and then calls the corresponding kernel space
<function>do_&hellip;_ioctl</function> function(s).
For example, a &comedi;
<link linkend="instructions">instruction</link> is further processed
by the <function>do_insn_ioctl()</function>function. (Which, in turn,
uses <function>parse_insn()</function> for further detailed processing.)
</para>
<para>
The data corresponding to instructions and commands is transmitted
with the <function>copy_from_user()</function> system call;
acquisition data captured by the interface card passes the kernel-user
space boundary with the help of a <function>copy_to_user()</function>
system call.
</para>

</section>

<section id="comedikernelgeneric">
<title>
Generic functionality
</title>

<para>
The major include files of the kernel-space part of &comedi; are:
<itemizedlist>

<listitem>
<para>
<filename>include/linux/comedidev.h</filename>: the
header file for kernel-only structures (device, subdevice, async
(i.e., buffer/event/interrupt/callback functionality for asynchronous
DAQ in a &comedi; command), driver, lrange), variables, inline functions
and constants.
</para>
</listitem>

<listitem>
<para>
<filename>include/linux/comedi_rt.h</filename>:
all the real-time stuff, such as management of ISR in RTAI and
RTLinux/Free, and spinlocks for atomic sections.
</para>
</listitem>

<listitem>
<para>
<filename>include/linux/comedilib.h</filename>: the header file for
the kernel library of &comedi;.
</para>
</listitem>

</itemizedlist>
</para>
<para>
From all the relevant &comedi; device driver code that is found in the
<filename role="directory">/usr/src/comedi/comedi</filename> directory
(<emphasis>if</emphasis> the &comedi; source has been installed in its
normal <filename role="directory">/usr/src/comedi</filename> location),
the <emphasis role="strong">generic</emphasis> functionality is
contained in two parts:
 <itemizedlist>

 <listitem>
 <para>
A couple of <filename>C</filename> files contain the <emphasis
role="strong">infrastructural support</emphasis>.
From these <filename>C</filename> files, it's especially the
<filename>comedi_fops.c</filename> file that implements what makes
&comedi; into what people want to use it for: a library that has
solved 90% of the DAQ device driver efforts, once and for all.
 </para>
 </listitem>

 <listitem>
 <para>
For <emphasis role="strong">real-time</emphasis> applications,
the subdirectory <filename role="directory">kcomedilib</filename>
implements an interface in the kernel that is similar to the &comedi;
interface accessible through the
<link linkend="functionreference">user-space Comedi library</link>.
</para>
<para>
There are some differences in what is possible and/or needed
in kernel space and in user space, so the functionalities offered in
<filename role="directory">kcomedilib</filename> are not an exact copy
of the user-space library. For example, locking, interrupt handling,
real-time execution, callback handling, etc., are only available in
kernel space.
 </para>
 <para>
Most drivers don't make use (yet) of these real-time functionalities.
 </para>
 </listitem>

 </itemizedlist>
</para>


<section id="driverdatastructures">
<title>
Data structures
</title>

<para>
This Section explains the generic data structures that a device driver
interacts with:
<programlisting>
typedef struct comedi_lrange_struct    <link linkend="comedilrange">comedi_lrange</link>;
typedef struct comedi_subdevice_struct <link linkend="comedisubdevice">comedi_subdevice</link>;
typedef struct comedi_device_struct    <link linkend="comedidevice">comedi_device</link>:
typedef struct comedi_async_struct     <link linkend="comediasync">comedi_async</link>
typedef struct comedi_driver_struct    <link linkend="comedidriver">comedi_driver</link>;
</programlisting>
They can be found in
<filename>/usr/src/comedi/include/linux/comedidev.h</filename>.
Most of the fields are filled in by the &comedi; infrastructure, but
there are still quite a handful that your driver must provide or use.
As for the user-level &comedi;, each of the hierarchical layers has
its own data structures: channel (<function>comedi_lrange</function>),
subdevice, and device.
</para>
<para>
Note that these kernel-space data structures have similar names as
their
<link linkend="datatypesstructures">user-space equivalents</link>, but
they have a different (kernel-side) view on the DAQ problem and a
different meaning: they encode the interaction with the
<emphasis>hardware</emphasis>, not with the <emphasis>user</emphasis>.
</para>
<para>
However, the <link linkend="ref-type-comedi-insn">comedi_insn</link>
and <link linkend="ref-type-comedi-cmd">comedi_cmd</link>
data structures are shared between user space and kernel space: this
should come as no surprise, since these data structures contain all
information that the user-space program must transfer to the
kernel-space driver for each acquisition.
</para>
<para>
In addition to these data entities that are also known at the user
level (device, sub-device, channel), the device driver level provides
two more data structures which the application programmer doesn't get
in touch with: the data structure
<link linkend="comedidriver">comedi_driver</link>
that stores the device driver information that is relevant at the
operating system level, and the data structure
<link linkend="comediasync">comedi_async</link> that stores the
information about all <emphasis>asynchronous</emphasis> activities
(interrupts, callbacks and events).
</para>

<section id="comedilrange">
<title>
<function>comedi_lrange</function>
</title>
<para>
The channel information is simple, since it contains only the signal
range information:
<programlisting>
struct comedi_lrange_struct{
  int           length;
  <link linkend="ref-type-comedi-krange">comedi_krange</link> range[GCC_ZERO_LENGTH_ARRAY];
};
</programlisting>
</para>

</section>


<section id="comedisubdevice">
<title>
<function>comedi_subdevice</function>
</title>
<para>
The subdevice is the smallest &comedi; entity that can be used for
<quote>stand-alone</quote> DAQ, so it is no surprise that it is
quite big:
<programlisting>
struct comedi_subdevice_struct{
  int  type;
  int  n_chan;
  int  subdev_flags;
  int  len_chanlist;            /* maximum length of channel/gain list */

  void *private;

  <link linkend="comediasync">comedi_async</link> *async;

  void         *lock;
  void         *busy;
  unsigned int runflags;

  int          io_bits;

  <link linkend="ref-type-lsampl-t">lsampl_t</link> maxdata;       /* if maxdata==0, use list */
  <link linkend="ref-type-lsampl-t">lsampl_t</link> *maxdata_list; /* list is channel specific */

  unsigned int flags;
  unsigned int *flaglist;

  <link linkend="comedilrange">comedi_lrange</link> *range_table;
  <link linkend="comedilrange">comedi_lrange</link> **range_table_list;

  unsigned int *chanlist;               /* driver-owned chanlist (not used) */

  int (*insn_read)(<link linkend="comedidevice">comedi_device</link> *,<link linkend="comedisubdevice">comedi_subdevice</link> *,<link linkend="ref-type-comedi-insn">comedi_insn</link> *,<link linkend="ref-type-lsampl-t">lsampl_t</link> *);
  int (*insn_write)(<link linkend="comedidevice">comedi_device</link> *,<link linkend="comedisubdevice">comedi_subdevice</link> *,<link linkend="ref-type-comedi-insn">comedi_insn</link> *,<link linkend="ref-type-lsampl-t">lsampl_t</link> *);
  int (*insn_bits)(<link linkend="comedidevice">comedi_device</link> *,<link linkend="comedisubdevice">comedi_subdevice</link> *,<link linkend="ref-type-comedi-insn">comedi_insn</link> *,<link linkend="ref-type-lsampl-t">lsampl_t</link> *);
  int (*insn_config)(<link linkend="comedidevice">comedi_device</link> *,<link linkend="comedisubdevice">comedi_subdevice</link> *,<link linkend="ref-type-comedi-insn">comedi_insn</link> *,<link linkend="ref-type-lsampl-t">lsampl_t</link> *);

  int (*do_cmd)(<link linkend="comedidevice">comedi_device</link> *,<link linkend="comedisubdevice">comedi_subdevice</link> *);
  int (*do_cmdtest)(<link linkend="comedidevice">comedi_device</link> *,<link linkend="comedisubdevice">comedi_subdevice</link> *,<link linkend="ref-type-comedi-cmd">comedi_cmd</link> *);
  int (*poll)(<link linkend="comedidevice">comedi_device</link> *,<link linkend="comedisubdevice">comedi_subdevice</link> *);
  int (*cancel)(<link linkend="comedidevice">comedi_device</link> *,<link linkend="comedisubdevice">comedi_subdevice</link> *);

  int (*buf_change)(<link linkend="comedidevice">comedi_device</link> *,<link linkend="comedisubdevice">comedi_subdevice</link> *s,unsigned long new_size);
  void (*munge)(<link linkend="comedidevice">comedi_device</link> *, <link linkend="comedisubdevice">comedi_subdevice</link> *s, void *data, unsigned int num_bytes, unsigned int start_chan_index );

  unsigned int state;
};
</programlisting>
The function pointers <function>(*insn_read)</function> &hellip;
<function>(*cancel)</function> .
offer (pointers to) the standardized
<link linkend="functionreference">user-visible API</link>
that every subdevice should offer; every device driver has to fill
in these functions with their board-specific implementations.
(Functionality for which &comedi; provides generic functions will, by
definition, not show up in the device driver data structures.)
</para>
<para>
The <function>buf_change()</function> and <function>munge()</function>
functions offer functionality that is not visible to the user and for
which the device driver writer must provide a board-specific
implementation:
<function>buf_change()</function> is called when a change in the
data buffer requires handling; <function>munge()</function> transforms
different bit-representations of DAQ values, for example from
<emphasis>unsigned</emphasis> to <emphasis>2's complement</emphasis>.
</para>

</section>

<section id="comedidevice">
<title>
<function>comedi_device</function>
</title>

<para>
The last data structure stores the information at the
<emphasis>device</emphasis> level:
<programlisting>
struct comedi_device_struct{
  int           use_count;
  <link linkend="comedidriver">comedi_driver</link> *driver;
  void          *private;
  kdev_t        minor;
  char          *board_name;
  const void    *board_ptr;
  int           attached;
  int           rt;
  spinlock_t    spinlock;
  int           in_request_module;

  int               n_subdevices;
  <link linkend="comedisubdevice">comedi_subdevice</link> *subdevices;
  int              options[COMEDI_NDEVCONFOPTS];

  /* dumb */
  int iobase;
  int irq;

  <link linkend="comedisubdevice">comedi_subdevice</link> *read_subdev;
  wait_queue_head_t read_wait;

  <link linkend="comedisubdevice">comedi_subdevice</link> *write_subdev;
  wait_queue_head_t write_wait;

  struct fasync_struct *async_queue;

  void (*open)(<link linkend="comedidevice">comedi_device</link> *dev);
  void (*close)(<link linkend="comedidevice">comedi_device</link> *dev);
};
</programlisting>
</para>

</section>

<section id="comediasync">
<title>
<function>comedi_async</function>
</title>

<para>
The following data structure contains all relevant information:
addresses and sizes of buffers, pointers to the actual data, and the
information needed for
<link linkend="drivercallbacks">event handling</link>:
<programlisting>
struct comedi_async_struct{
  void          *prealloc_buf;          /* pre-allocated buffer */
  unsigned int  prealloc_bufsz;         /* buffer size, in bytes */
  unsigned long *buf_page_list;         /* physical address of each page */
  unsigned int  max_bufsize;            /* maximum buffer size, bytes */
  unsigned int  mmap_count;     /* current number of mmaps of prealloc_buf */

  volatile unsigned int buf_write_count;        /* byte count for writer (write completed) */
  volatile unsigned int buf_write_alloc_count;  /* byte count for writer (allocated for writing) */
  volatile unsigned int buf_read_count; /* byte count for reader (read completed)*/

  unsigned int buf_write_ptr;   /* buffer marker for writer */
  unsigned int buf_read_ptr;    /* buffer marker for reader */

  unsigned int cur_chan;                /* useless channel marker for interrupt */
  /* number of bytes that have been received for current scan */
  unsigned int scan_progress;
  /* keeps track of where we are in chanlist as for munging */
  unsigned int munge_chan;

  unsigned int  events;         /* events that have occurred */

  <link linkend="ref-type-comedi-cmd">comedi_cmd</link> cmd;

  // callback stuff
  unsigned int cb_mask;
  int (*cb_func)(unsigned int flags,void *);
  void *cb_arg;

  int (*inttrig)(<link linkend="comedidevice">comedi_device</link> *dev,<link linkend="comedisubdevice">comedi_subdevice</link> *s,unsigned int x);
};
</programlisting>
</para>

</section>

<section id="comedidriver">
<title>
<function>comedi_driver</function>
</title>

<para>
<programlisting>
struct comedi_driver_struct{
        struct comedi_driver_struct *next;

        char *driver_name;
        struct module *module;
        int (*attach)(<link linkend="comedidevice">comedi_device</link> *,comedi_devconfig *);
        int (*detach)(<link linkend="comedidevice">comedi_device</link> *);

        /* number of elements in board_name and board_id arrays */
        unsigned int num_names;
        void *board_name;
        /* offset in bytes from one board name pointer to the next */
        int offset;
};
</programlisting>
</para>

</section>

</section>


<section id="driversupportfunctions">
<title>
Generic driver support functions
</title>

<para>
The directory
<filename role="directory">comedi</filename> contains a large set of
support functions. Some of the most important ones are given below.
</para>
<para>
From <filename>comedi/comedi_fops.c</filename>, functions to handle the
hardware events (which also runs the registered callback function), to
get data in and out of the software data buffer, and to parse the
incoming functional requests:
<programlisting>
  void comedi_event(<link linkend="comedidevice">comedi_device</link> *dev,<link linkend="comedisubdevice">comedi_subdevice</link> *s,unsigned int mask);

  int comedi_buf_put(<link linkend="comediasync">comedi_async</link> *async, <link linkend="ref-type-sampl-t">sampl_t</link> x);
  int comedi_buf_get(<link linkend="comediasync">comedi_async</link> *async, <link linkend="ref-type-sampl-t">sampl_t</link> *x);

  static int parse_insn(<link linkend="comedidevice">comedi_device</link> *dev,<link linkend="ref-type-comedi-insn">comedi_insn</link> *insn,<link linkend="ref-type-lsampl-t">lsampl_t</link> *data,void *file);
</programlisting>
The file <filename>comedi/kcomedilib/kcomedilib_main.c</filename> provides
functions to register a callback, to poll an ongoing data acquisition,
and to print an error message:
<programlisting>
  int comedi_register_callback(<link linkend="ref-type-comedi-t">comedi_t</link> *d,unsigned int subdevice, unsigned int mask,int (*cb)(unsigned int,void *),void *arg);

  int comedi_poll(<link linkend="ref-type-comedi-t">comedi_t</link> *d, unsigned int subdevice);

  void comedi_perror(const char *message);
</programlisting>
The file <filename>comedi/rt.c</filename> provides interrupt handling
for real-time tasks (one interrupt per <emphasis>device</emphasis>!):
<programlisting>
  int comedi_request_irq(unsigned irq,void (*handler)(int, void *,struct pt_regs *), unsigned long flags,const char *device,<link linkend="comedidevice">comedi_device</link> *dev_id);
  void comedi_free_irq(unsigned int irq,<link linkend="comedidevice">comedi_device</link> *dev_id)
</programlisting>
</para>

</section>

</section>


<section id="boardspecific">
<title>
Board-specific functionality
</title>

<para>
The <filename role="directory">/usr/src/comedi/comedi/drivers</filename>
subdirectory contains
the <emphasis role="strong">board-specific</emphasis> device driver
code. Each new card must get an entry in this directory.
<emphasis role="strong">Or</emphasis>
extend the functionality of an already existing driver file if the new
card is quite similar to that implemented in an already existing
driver. For example, many of the National Instruments DAQ cards use
the same driver files.
</para>
<para>
To help device driver writers,
&comedi; provides the <quote>skeleton</quote> of a new device driver,
in the <filename>comedi/drivers/skel.c</filename> 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
board-specific files in the same directory.
</para>
<para>
The first thing you notice in <filename>skel.c</filename> is the
documentation section: the &comedi; documentation is partially
generated automatically, from the information that is given in this
section. So, please comply with the structure and the keywords
provided as &comedi; standards.
</para>
<para>
The second part of the device driver contains board-specific static
data structure and defines: addresses of hardware registers; defines and
function prototypes for functionality that is only used inside of the
device driver for this board; the encoding of the types and number of
available channels; PCI information; etc.
</para>
<para>
Each driver has to register two functions which are called when you
load and unload your board's device driver (typically via a kernel
module):
<programlisting>
  mydriver_attach();
  mydriver_detach();
</programlisting>
In the <quote>attach</quote> function, memory is allocated for the
necessary <link linkend="driverdatastructures">data structures</link>,
all properties of a device and its subdevices are defined, and filled
in in the generic &comedi; data structures. As part of this, pointers
to the low level instructions being supported by the subdevice have to
be set, which define the basic functionality. In somewhat more detail,
the <function>mydriver_attach()</function> function must:
<itemizedlist>

<listitem>
<para>
check and request the I/O port region, IRQ, DMA, and other hardware
resources.  It is convenient here if you verify the existence of the
hardware and the correctness of the other information given.
Sometimes, unfortunately, this cannot be done.
</para>
</listitem>

<listitem>
<para>
allocate memory for the private data structures.
</para>
</listitem>

<listitem>
<para>
initialize the board registers and possible subdevices (timer, DMA, PCI,
hardware FIFO, etc.).
</para>
</listitem>

<listitem>
<para>
return 1, indicating success. If there were any errors along the way,
you should return the appropriate error number.  If an error is
returned, the <function>mydriver_detach()</function> function is
called.  The <function>mydriver_detach()</function> function should
check any resources that may have been allocated and release them as
necessary.  The &comedi; core frees
<function>dev->subdevices</function> and
<function>dev->private</function>, so this does not need to be done in
<function>detach</function>.
</para>
</listitem>

<listitem>
<para>
If the driver has the possibility to offer asynchronous data
acquisition, you have to code an interrupt service routine, event
handling routines, and/or callback routines.
</para>
</listitem>

</itemizedlist>
Typically, you will be able to implement most of
the above-mentioned functionality by
<emphasis>cut-and-paste</emphasis> from already existing drivers. The
<function>mydriver_attach()</function> function needs most of your
attention, because it must correctly define and allocate the (private
and generic) data structures that are needed for this device. That is,
each sub-device and each channel must get appropriate data fields, and
an appropriate initialization. The good news, of course, is that
&comedi; provides the data structures and the defines that fit very
well with almost all DAQ functionalities found on interface cards.
These can be found in the
<link linkend="comedikernelgeneric">header files</link> of the
<filename role="directory">/usr/src/comedi/include/linux/</filename>
directory.
</para>
<para>
Drivers for digital IOs should implement the following functions:
<itemizedlist>

<listitem>
<para>
<function>insn_bits()</function>: drivers set this if they have a
function that supports reading and writing multiple bits in a digital
I/O subdevice at the same time.  Most (if not all) of the drivers use
this interface instead of insn_read and insn_write for DIO subdevices.
</para>
</listitem>

<listitem>
<para>
<function>insn_config()</function>: implements INSN_CONFIG
instructions.  Currently used for configuring the direction of digital
I/O lines, although will eventually be used for generic configuration
of drivers that is outside the scope of the currently defined &comedi;
interface.
</para>
</listitem>

</itemizedlist>
Finally, the device driver writer must implement the
<function>read</function> and <function>write</function> functions for
the analog channels on the card:
<itemizedlist>

<listitem>
<para>
<function>insn_read()</function>: acquire the inputs on the board and
transfer them to the software buffer of the driver.
</para>
</listitem>

<listitem>
<para>
<function>insn_write()</function>: transfer data from the software
buffer to the card, and execute the appropriate output conversions.
</para>
</listitem>

</itemizedlist>
In some drivers, you want to catch interrupts, and/or want to use the
<link linkend="insn-inttrig">INSN_INTTRIG</link> instruction. In this
case, you must provide and register these
<link linkend="drivercallbacks">callback</link> functions.
</para>
<para>
Implementation of all of the above-mentioned functions requires
perfect knowledge about the hardware registers and addresses of the
interface card. In general, you can find
<emphasis>some</emphasis> inspiration in the already available device
drivers, but don't trust that blind
<emphasis>cut-and-paste</emphasis> will bring you far&hellip;
</para>

</section>

<section id="drivercallbacks">
<title>
Callbacks, events and interrupts
</title>

<para>
Continuous acquisition is tyically an
<emphasis>asynchronous</emphasis> 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 <quote>in the background</quote>, but
various types of asynchronous <emphasis>event handling</emphasis> can
be needed during the acquisition:
<itemizedlist>

<listitem>
<para>
The <emphasis>hardware</emphasis> can generate some error or
warning events.
</para>
</listitem>

<listitem>
<para>
Normal functional interrupts are generated by the hardware, e.g.,
signalling the filling-up of the card's hardware buffer, or the end of
an acquisition <link linkend="scan">scan</link>, etc.
</para>
</listitem>

<listitem>
<para>
The device driver writer can register a driver-supplied
<quote>callback</quote> function, that is called at the end of each
hardware interrupt routine.
</para>
</listitem>

<listitem>
<para>
Another driver-supplied callback function is executed when the user
program launches an <link linkend="insn-inttrig">INSN_INTTRIG</link>
instruction. This event handling is executed
<emphasis>synchronously</emphasis> with the execution of the
triggering instruction.
</para>
</listitem>

</itemizedlist>
</para>
<para>
The interrupt handlers are registered through the functions mentioned
<link linkend="driversupportfunctions">before</link>
The event handling is done in the existing &comedi; drivers in
statements such as this one:
<programlisting>
<anchor id="async-events"/>
   s->async->events |= COMEDI_CB_EOA | COMEDI_CB_ERROR
</programlisting>
It fills in the bits corresponding to particular events in the
<link linkend="comediasync">comedi_async</link> data structure.
The possible event bits are:
<itemizedlist>

<listitem>
<para>
<anchor id="comedi-cb-eoa"/>
<parameter>COMEDI_CB_EOA</parameter>: execute the callback at the
<quote>End Of-Acquisition</quote>.
</para>
</listitem>

<listitem>
<para>
<anchor id="comedi-cb-eos"/>
<parameter>COMEDI_CB_EOS</parameter>: execute the callback at the
<quote>End-Of-Scan</quote>.
</para>
</listitem>

<listitem>
<para>
<anchor id="comedi-cb-overflow"/>
<parameter>COMEDI_CB_OVERFLOW</parameter>: execute the callback when a
buffer overflow has occurred.
</para>
</listitem>

<listitem>
<para>
<anchor id="comedi-cb-error"/>
<parameter>COMEDI_CB_ERROR</parameter>: execute the callback at the
occurrence of an (undetermined) error.
</para>
</listitem>

</itemizedlist>
</para>

</section>


<section id="drivercaveats">
<title>
Device driver caveats
</title>

<para>
A few things to strive for when writing a new driver:
<itemizedlist>

<listitem>
<para>
Some DAQ cards consist of different <quote>layers</quote> of hardware,
which can each be given their own device driver. Examples are:
some of the National Instruments cards, that all share the same
<emphasis>Mite</emphasis> PCI driver chip; the ubiquitous parallel
port, that can be used for simple digital IO acquisitions. If your
new card has such a multi-layer design too, please take the effort to
provide drivers for each layer separately.
</para>
</listitem>

<listitem>
<para>
Your hardware driver should be functional appropriate to the resources
allocated.  I.e., if the driver is fully functional when configured
with an IRQ and DMA, it should still function moderately well with
just an IRQ, or still do minor tasks without IRQ or DMA.  Does your
driver really require an IRQ to do digital I/O?  Maybe someone will
want to use your driver <emphasis>just</emphasis> to do digital I/O
and has no interrupts available.
</para>
</listitem>

<listitem>
<para>
Drivers are to have absolutely <emphasis role="strong">no</emphasis>
global variables, mainly because the existence of global variables
immediately negates any possibility of using the driver for two
devices. The pointer <function>dev->private</function> should be used
to point to a structure containing any additional variables needed by
a driver/device combination.
</para>
</listitem>

<listitem>
<para>
Drivers should report errors and warnings via the
<function>comedi_error()</function> function.
(This is <emphasis>not</emphasis> the same function as the user-space
<link linkend="func-ref-comedi-perror">comedi_perror()</link> function.)

</para>
</listitem>

</itemizedlist>
</para>
</section>

<section id="integratingdriver">
<title>
Integrating the driver in the &comedi; library
</title>

<para>
For integrating new drivers in the &comedi;'s source tree the following
things have to be done:
<itemizedlist>

<listitem>
<para>
Choose a sensible name for the source code file. Let's assume here
that you call it <quote>mydriver.c</quote>
</para>
</listitem>

<listitem>
<para>
Put your new driver into <quote>comedi/drivers/mydriver.c</quote>.
</para>
</listitem>

<listitem>
<para>
Edit <quote>comedi/drivers/Makefile.am</quote> and add <quote>mydriver.ko</quote>
to the <quote>module_PROGRAMS</quote> list.  Also add a line
<programlisting>
mydriver_ko_SOURCES = mydriver.c
</programlisting>
in the alphabetically appropriate place.
</para>
</listitem>

<listitem>
<para>
Run ./autogen.sh in the top-level comedi directory.  You will
need to have (a recent version of) autoconf and automake
installed to successfully run autogen.sh.  Afterwards, your driver will
be built along with the rest of the drivers when you 'make'.
</para>
</listitem>

<listitem>
<para>
If you want to have your driver included in the &comedi; distribution
(you <emphasis>definitely</emphasis> want to :-) ) send it to
David Schleef <address><email>ds@schleef.org</email></address> or
Frank Hess <address><email>fmhess@users.sourceforge.net</email></address>
for review and integration.  Note your work must be licensed under terms
compatible with the GNU GPL to be distributed as a part of Comedi.
</para>
</listitem>
</itemizedlist>
</para>

</section>

</section>