Documentation/comedi/Hardware_Driver.HOWTO

   1
   2 Hardware driver interface
   3
   4
   5 [ this is a little outdated -ds ]
   6
   7
   8 1. Introduction
   9
  10 This comedi hardware driver writing HOWTO is written to help you
  11 write a driver for your particular choice of hardware.  You should
  12 be familiar with how comedi works from the user's point of view,
  13 i.e., from a process that is utilizing the comedi driver.
  14
  15 This guide does not explain the details of things like reading
  16 and writing I/O ports, Linux kernel internals, or interrupt
  17 processing.  These issues are covered in other documents,
  18 specifically, the IO-Port-Programming mini-HOWTO, the Kernel
  19 Hacker's Guide, and the Linux source.
  20
  21
  22 2. The source tree
  23
  24 As of comedi-0.5.0, hardware drivers need to be part of the
  25 source tree and be compiled with the rest of the comedi driver
  26 into the module comedi.o.  Later versions will hopefully support
  27 separate compiling/separate modules, etc.
  28
  29 The source for the comedi module is located in module/, including
  30 the device independent part and each hardware driver.  A hardware
  31 driver, such as the "dt282x" driver, is typically located in the
  32 C source file of the same name.
  33
  34 The hardware driver "dummy" is a stripped-down example that may be
  35 a good starting point for new hardware drivers.
  36
  37
  38 3. comedi_config and *_init()
  39
  40 The file "module/comeditypes.c" has a list of the initialization
  41 functions for all the drivers.  You should add your init function
  42 to this list.  The top level Makefile and scripts/configure
  43 take care of all the defines.
  44
  45 The purpose of comeditypes.c is to keep a list of available
  46 hardware drivers by keeping a list of available initialization
  47 functions.  Thus, when comedi_config is run, it issues the
  48 COMEDI_CONFIG ioctl() with the name of the driver and
  49 configuration parameters (I/O port address, irq, dma, etc.).
  50 The comedi driver then calls the initialization function of
  51 each hardware driver on the list.
  52
  53 Inside the initialization function, you should perform the
  54 following tasks:
  55
  56    o  Check to see if you are the correct hardware driver
  57       for the name specified in the comedi_devconfig structure.
  58       Your hardware driver may consider several names as
  59       "correct", and even behave differently depending on
  60       the name given.  The idea here is to support different
  61       cards in a series using different names, but using the
  62       same hardware driver.  If you are not the correct
  63       hardware driver, return a 0.
  64
  65    o  Announce that the hardware driver has begun initialization
  66       by a printk("comedi%d: driver: ",minor);
  67
  68    o  Check and request the I/O port region, IRQ, DMA, and other
  69       hardware resources.  It is convenient here if you verify the
  70       existence of the hardware and the correctness of the other
  71       information given.  Sometimes, unfortunately, this cannot
  72       be done.
  73
  74    o  Fill in the comedi_device structure.
  75
  76    o  Allocate your private data structure and space for channel
  77       configuration.
  78
  79    o  Configure each channel.  Each channel has three function
  80       pointers:  one for triggering a single conversion (itrig),
  81       one for triggering general conversions (trig), and one
  82       for setting channel parameters (sp).  Each channel also has
  83       a parameter linked list.
  84       Parameters are added to this list via addparam().  All the
  85       parameter routines are in param.c.  They are currently not
  86       very efficient, so if you know of a better algorithm...
  87       Look at the header files for parameter types that you may
  88       wish to include.
  89
  90    o  Initialize the read buffer via comedi_initbuf().  The buffering
  91       routines are in buffer.c, and support multiple processes
  92       reading the same device.  The buffers are also dynamic, so
  93       you don't have to worry about the hardware driver collecting
  94       1M of data before the controlling process reads it.  I've been
  95       using these routines for a while--they appear to be pretty
  96       stable.  Most of the error messages you get from the buffer
  97       routines indicate memory leaks.
  98
  99    o  Set mtrig in the comedi_device structure to the function that
 100       is called for a channel scan trigger.
 101
 102    o  Tell the comedi driver the function to call when your driver
 103       needs to be removed.
 104
 105    o  Return a 1.  If there were any errors along the way, you
 106       should return the appropriate error number, but don't forget
 107       to release any resources that you allocated.  (It will only
 108       take one time to realize that if you don't release an I/O region,
 109       you have to reboot to get it back.  (Or write a hack, as I did.))
 110
 111
 112 4. Set Parameter routines
 113
 114 When the COMEDI_SETPARAM ioctl() is called, the comedi driver
 115 calls the setparameter routine of the channel involved.  Common
 116 settable parameters are input gain (input range) and setting bits
 117 on digital I/O lines as input or output.  The setparameter
 118 function should check the validity of the parameter type and
 119 value, and then call changeparam() to update the parameter
 120 linked lists.  If necessary, calls to update the hardware
 121 should be made.
 122
 123
 124 5. Triggering routines
 125
 126 Like the setparameter routines, each channel has a trigger
 127 function that is called for a COMEDI_TRIG ioctl().  The trigger
 128 function is called with the comedi_trig structure, which
 129 includes the trigger type, number of samples, and one sample value
 130 (which may be read or written, depending on context).
 131
 132 As of 0.5.0, there are two triggering routines per channel, one
 133 for TRIGNOW, and one for all the rest.  The reason this was done
 134 is because the TRIGNOW functions are exported to the rest of the
 135 kernel (i.e., for RTLinux).
 136
 137 Trigger types are accompanied by the trigger variable, which
 138 is interpreted based on the trigger type.  The types of triggers
 139 (currently) available are:
 140
 141    o  COMEDI_TRIGNOW - causes one sample conversion to be
 142       completed immediately.  The trigger variable and number of
 143       samples are ignored.
 144
 145    o  COMEDI_TRIGCLK - causes conversions timed by a clock on
 146       the hardware.  The trigger variable determines the clock
 147       speed.
 148
 149    o  COMEDI_TRIGEXT - causes conversions to be triggered by
 150       an external trigger provided by the hardware.  The trigger
 151       variable determines the particular choice, if there is
 152       more than one choice.
 153
 154 Other trigger sources that may be defined in the future are
 155 analog triggers and comedi triggers.  Comedi triggers could include
 156 the 100 Hz interrupt, the rtc interrupt, general timing triggers,
 157 signals generated by other boards, etc.
 158
 159 Except for COMEDI_TRIGNOW, your triggering routine should return
 160 after telling the hardware to perform the requested task.  For
 161 COMEDI_TRIGNOW on input, you should wait for the conversion to
 162 finish and return it in the ioctl structure, but do *NOT* report
 163 the sample via report_sample().
 164
 165 Typically, you will poll the hardware or the hardware will
 166 generate interrupts to tell you when samples are ready.  The
 167 samples should be reported via report_sample().
 168
 169
 170 6. The remove function
 171
 172 A driver is removed from service via a call to dev->rem().  The driver
 173 is expected to halt all conversions, put the hardware in a sane,
 174 off-line state, delete all channel parameters, free all allocated memory,
 175 and release any irq's and port addresses held.  If these things are
 176 not all done, there will be memory leaks, and more importantly, the
 177 driver will not configure properly if reused.
 178
 179
 180 A. Goals
 181
 182 A few things to strive for:
 183
 184    o  Your hardware driver should be functional appropriate to
 185       the resources allocated.  I.e., if the driver is fully
 186       functional when configured with an IRQ and DMA, it should
 187       still function moderately well with just an IRQ, or still
 188       do minor tasks without IRQ or DMA.  Does your driver really
 189       require an IRQ to do digital I/O?  Maybe someone will want
 190       to use your driver *just* to do digital I/O and has no
 191       interrupts available.
 192
 193    o  Drivers are to have absolutely *NO* global variables, mainly
 194       because the existence of global variables immediately negates
 195       any possibility of using the driver for two devices.  The
 196       pointer dev->private should be used to point to a structure
 197       containing any additional variables needed by a driver/device
 198       combination.
 199
 200    o  Drivers should report errors and warnings via a printk line
 201       that starts with "comedi%d: driver_name:" where %d is the
 202       minor number of the device.
 203
 204
 205
 206