Documentation/comedi/Hardware_Driver.HOWTO

   1 Hardware driver interface
   2 =========================
   3
   4 [ this is a little outdated -ds ]
   5 [ this is a lot outdated -fmh ]
   6 [ this is a little bit less outdated, hopefully -rs ]
   7 [ the 'adding new drivers' section has been updated -ija ]
   8
   9
  10 Table of Contents
  11 =================
  12
  13 1. Introduction
  14 2. The source tree
  15 3. Adding new drivers
  16 4. Driver basics
  17 5. Instructions
  18
  19
  20
  21
  22 1. Introduction
  23
  24 This comedi hardware driver writing HOWTO is written to help you write a
  25 driver for your particular choice of hardware.  You should be familiar with
  26 how comedi works from the user's point of view, i.e., from a process that is
  27 utilizing the comedi driver.
  28
  29 This guide does not explain the details of things like reading and writing
  30 I/O ports, Linux kernel internals, or interrupt processing. These issues are
  31 covered in other documents, e.g.
  32
  33 - The IO-Port Programming Mini HOWTO:
  34   http://www.linuxdoc.org/HOWTO/mini/IO-Port-Programming.html
  35
  36 - Linux Kernel Module Programming Guide
  37   http://www.linuxdoc.org/LDP/lkmpg/mpg.html
  38
  39 - Kernel Hacker's Guide
  40   http://www.linuxdoc.org/LDP/khg/HyperNews/get/khg.html
  41
  42 - Linux Device Drivers, 2nd Edition
  43   http://www.xml.com/ldd/chapter/book/index.html
  44
  45 - The Linux source
  46
  47
  48
  49
  50 2. The source tree
  51
  52 Currently hardware drivers need to be part of the source tree and be
  53 compiled with the rest of the comedi driver into the module comedi.o.  Later
  54 versions will hopefully support separate compiling/separate modules, etc.
  55
  56 The source for the comedi module is located in the 'comedi/' directory,
  57 including the device independent part. The source files of the hardware
  58 drivers for the different boards are located in 'comedi/drivers/', the
  59 kernel space library (which is used for accessing comedi from realtime
  60 programs) lives in 'comedi/kcomedilib/'.
  61
  62 In the drivers' directory there is a striped-down example ('skel.c') that
  63 may be a good starting point for new hardware drivers.
  64
  65
  66
  67
  68 3. Adding new drivers
  69
  70 The best way to write a new driver is to take one of the existing ones (e.g.
  71 the 'skel' driver) and modify it to your own needs. For integrating new
  72 drivers in the comedi source tree the following things have to be done:
  73
  74 - Put your new driver into 'comedi/drivers/mydriver.c'.
  75 - Edit 'comedi/drivers/Makefile.am' and update 'module_PROGRAMS',
  76   'pci_modules2', 'pcmcia_modules', or 'usb_modules', depending on the type
  77   of driver. (There is also a 'pci_modules1' used by a few helper modules.)
  78   Add a 'mydriver_ko_sources' macro set to your 'mydriver.c' file (look at
  79   the other examples).  If your driver has its own include files, add them
  80   to the EXTRA_DIST macro.
  81 - Edit 'comedi/drivers/Kbuild' and add a 'obj-m += mydriver.o',
  82   'obj-$(COMEDI_CONFIG_PCI_MODULES) += mydriver.o',
  83   'obj-$(COMEDI_CONFIG_PCMCIA_MODULES) += mydriver.o', or
  84   'obj-$(COMEDI_CONFIG_USB_MODULES) += mydriver.o' line, depending on the
  85   type of driver.
  86
  87 Now run 'autoreconf' to update the configure script, re-run './configure'
  88 with any necessary command-line options to update the makefiles, and run
  89 'make' to rebuild comedi and be happy.
  90
  91 If you want to have your driver included in the comedi distribution
  92 (you _definitely_ want to :) ) send it to the Comedi mailing list for
  93 review and integration.  (See the top-level README for details of the
  94 Comedi mailing list.)
  95
  96
  97
  98
  99 4. Driver basics
 100
 101 Implementation details for the following things can be found in the skel
 102 driver. Each driver has to register two functions which are called when you
 103 configure and deconfigure your board:
 104
 105 - mydriver_attach()
 106 - mydriver_detach()
 107
 108 In the 'attach' function all properties of a device and its subdevices are
 109 defined. As part of this pointers to the low level instructions being
 110 supported by the subdevice have to be set (see next section) which define
 111 the basic functionality.
 112
 113
 114
 115 5. Instructions
 116
 117 Instructions (insns) are comedi's low level functins for accessing all kinds
 118 of channels, like analog or digital IOs.
 119
 120 Drivers for digital IOs should implement the following functions:
 121
 122 - insn_bits():
 123   Drivers set this if they have a function that supports reading and writing
 124   multiple bits in a digital I/O subdevice at the same time.  Most (if not
 125   all) of the drivers use this interface instead of insn_read and insn_write
 126   for DIO subdevices.
 127
 128 - insn_config():
 129   Implements INSN_CONFIG instructions.  Currently used for configuring the
 130   direction of digital I/O lines, although will eventually be used for
 131   generic configuration of drivers that is outside the scope of the
 132   currently defined Comedi interface.
 133
 134 Drivers for analog IOs should implement these function:
 135
 136 - insn_read():
 137   Analog inputs have to implement insn_read.
 138
 139 - insn_write():
 140   The same with insn_write.
 141
 142
 143 [THIS SEEMS TO BE OBSOLETE??? -rs] -------------------------------------------
 144
 145 Inside the initialization function, you should perform the following tasks:
 146
 147    o  Announce that the hardware driver has begun initialization by a
 148       printk("comedi%d: driver: ",minor);
 149
 150    o  Check and request the I/O port region, IRQ, DMA, and other hardware
 151       resources.  It is convenient here if you verify the existence of the
 152       hardware and the correctness of the other information given.
 153       Sometimes, unfortunately, this cannot be done.
 154
 155    o  Fill in the comedi_device structure.
 156
 157    o  Allocate your private data structure and subdevices.
 158
 159    o  Set up each subdevice.
 160
 161    o  Return 0, indicating success.  If there were any errors along
 162       the way, you should return the appropriate error number.  If
 163       an error is returned, the _detach function is called.  The
 164       _detach function should check any resources that may have been
 165       allocated and release them as necessary.  The comedi core frees
 166       dev->subdevices and dev->private, so this does not need to be
 167       done in _detach.
 168
 169
 170 A. Goals
 171
 172 A few things to strive for:
 173
 174    o  Your hardware driver should be functional appropriate to
 175       the resources allocated.  I.e., if the driver is fully
 176       functional when configured with an IRQ and DMA, it should
 177       still function moderately well with just an IRQ, or still
 178       do minor tasks without IRQ or DMA.  Does your driver really
 179       require an IRQ to do digital I/O?  Maybe someone will want
 180       to use your driver *just* to do digital I/O and has no
 181       interrupts available.
 182
 183    o  Drivers are to have absolutely *NO* global variables, mainly
 184       because the existence of global variables immediately negates
 185       any possibility of using the driver for two devices.  The
 186       pointer dev->private should be used to point to a structure
 187       containing any additional variables needed by a driver/device
 188       combination.
 189
 190    o  Drivers should report errors and warnings via a printk line
 191       that starts with "comedi%d: driver_name:" where %d is the
 192       minor number of the device.
 193
 194
 195