INSTALL

   1
   2 * Linux source:
   3
   4 In order to compile the Comedi modules, you will need to have
   5 a correctly configured Linux kernel source tree.  The best
   6 way to get one is to download a tarball from kernel.org and
   7 compile your own kernel.  Comedi should work with most 2.2,
   8 2.4, and 2.6 Linux kernels.  2.6.x kernels older than 2.6.6 are
   9 not supported.  Support for 2.0.3x is not actively maintained,
  10 but it should work and bugs will be fixed as they are reported.
  11
  12 You can also prepare a kernel source tree that matches
  13 the kernel you are currently running if you have its config file (in
  14 the Debian distibution the config files for the kernel-image packages
  15 are installed into the /boot directory).  The following steps will
  16 (almost) set up your kernel sources correctly.  You will also need
  17 write permission to the kernel source directory the first time you
  18 run comedi's configure script, so you might want to unpack the kernel
  19 source into a directory you own.
  20
  21 1) Get a copy of the kernel source that matches the kernel you are
  22         running.  Unpack it and copy your kernel config file to '.config'
  23         in the top directory of your kernel source.
  24 2) You might need to edit the file 'Makefile' in the kernel source.
  25         At the top of the Makefile, the variable EXTRAVERSION is defined.
  26         If necessary, change it to match your kernel (for example, if the command
  27         'uname -r' produces "2.4.16-386" then your EXTRAVERSION should be
  28         set as 'EXTRAVERSION=-386'.
  29 3) Run 'make oldconfig' in your kernel source directory.
  30 4) Run 'make dep' (for 2.6 kernels, do a 'make modules_prepare' instead
  31         or even better a full 'make') in the kernel source directory and
  32         you are done.
  33
  34 Red Hat users note: Kernel sources that are distributed with Red
  35 Hat Linux are not supported, because they are too heavily
  36 modified.  However, there is some information in
  37 Documentation/comedi/redhat-notes on how to use Red Hat kernels.
  38
  39 * RTAI support:
  40
  41 If you want to use the real-time capabilities of Comedi with
  42 RTAI, you need to compile and install RTAI first.  If you
  43 don't install the rtai kernel modules, you may get unresolved
  44 symbols when installing the comedi kernel modules.
  45
  46 * RTLinux support:
  47
  48 If you want to use the real-time capabilities of Comedi with
  49 RTLinux, you need to compile RTLinux (both the kernel and the
  50 modules) first.  Known working versions are 2.x and 3.0.
  51
  52 * Configuration:
  53
  54 Configure with './configure'.  './configure --help' will give the
  55 configuration options.  If the configure script does not exist
  56 (if you checked comedi out from git for example), it can
  57 be generated by running './autogen.sh'.  The autoconf, automake,
  58 autoheader, etc. tools are required to generate the configure
  59 script (automake version >= 1.7 recommended).  The --with-linuxdir
  60 option is particularly useful, as it allows you to specify
  61 the location of your Linux kernel source directory.  If
  62 you are using an RT-patched kernel, the --with-rtaidir or
  63 --with-rtlinuxdir options allow you to specify
  64 the location of your RTAI or RTLinux source directory.
  65
  66 * Compiling:
  67
  68 Compile using 'make'.  If this fails for some reason, send the
  69 _entire_ build log to the mailing list.  Without the build
  70 log, it is impossible to find problems.
  71
  72 * Installation:
  73
  74 Install using 'make install' as root.  This installs the files:
  75
  76   /lib/modules/<<kernel version>>/comedi/comedi.ko
  77   /lib/modules/<<kernel version>>/comedi/kcomedilib.ko
  78   /lib/modules/<<kernel version>>/comedi/<<driver files>>.ko
  79
  80 Comedi communicates with userspace via device files (/dev/comedi*).
  81 If you have devices which are able to auto-configure themselves and
  82 you've got udev support these devices are created automatically.  You
  83 can disable this mechanism by setting the module parameter
  84 comedi_autoconfig to zero of the module "comedi_fops". In case you
  85 have got an old ISA card or no udev support (embedded systems) you can
  86 create static devices with the module parameter
  87 comedi_num_legacy_minors by setting it to the number of desired static
  88 /dev/comedi* devices. You can then configure your device from the
  89 userspace with comedi_config. In this case you need to create device
  90 files to access the hardware by hand from a user process.  These can
  91 be created using 'make dev'.  The following special files will be
  92 created:
  93
  94   /dev/comedi0
  95   /dev/comedi1
  96   /dev/comedi2
  97   ...
  98   /dev/comedi15
  99
 100 * Comedilib:
 101
 102 Now would be a good time to compile and install Comedilib.  Comedi
 103 and Comedilib are completely independent, so it doesn't matter
 104 which is installed first.
 105
 106 * Running Comedi:
 107
 108 To use comedi, the driver module and the core Comedi modules must
 109 be loaded into the kernel.  This is done by a command similar to
 110
 111   /sbin/modprobe <<driver>>
 112
 113 If your module dependencies are set up correctly, this will load
 114 both comedi.ko and your driver.  If you get unresolved symbols, check
 115 the FAQ or the mailing list archives.  Also look at the man pages
 116 for modprobe and insmod.
 117
 118 In order to configure a driver module to use a particular device
 119 file (/dev/comediN) and a particular device, you need to use the
 120 command 'comedi_config', which is part of the comedilib
 121 distribution.  Comedi_config is invoked using
 122
 123   comedi_config /dev/comedi0 <device name> <option list>
 124
 125 The device name may or may not be the same as the module name.  In
 126 general, if the device type can be autoprobed (as with ISA PnP or
 127 PCI devices), the device name will be the same as the module name.
 128 Otherwise, you will need to check Documentation/comedi/drivers.txt
 129 for information about what device name is appropriate for your
 130 hardware.  The option list is to supply additional information,
 131 such as I/O address, IRQ, DMA channels, and other jumper settings.
 132 Information about option lists appropriate for a driver is in
 133 drivers.txt.  The following commands are examples:
 134
 135   comedi_config /dev/comedi0 dt2821 0x240,3
 136   comedi_config /dev/comedi1 ni_atmio 0x260,4
 137   comedi_config /dev/comedi2 dt2817 0x228
 138   comedi_config /dev/comedi3 ni_pcimio
 139
 140 Try a 'man comedi_config' for information on how to use
 141 this utility.  Scripts have been written for a few of the drivers
 142 with very complicated option lists -- these are found in the etc
 143 directory.
 144
 145 * Module Autoloading:
 146
 147 For recent kernels, module autoloading is handled by udev.  The
 148 following is only applicable to older kernels.
 149
 150 If you like to autoload your modules, put the following lines
 151 into /etc/modules.conf (this does not apply for PCMCIA cards):
 152
 153   alias char-major-98 comedi
 154   alias char-major-98-0 your_driver
 155   post-install your_driver PATH=/sbin:/usr/sbin:/usr/local/sbin:$PATH;comedi_config /dev/comedi0 board_name <<options>>
 156
 157 Alternatively, for complicated option lists, the scripts in etc
 158 are designed to be copied into /etc, so that you could put the
 159 following lines into /etc/conf.modules:
 160
 161   alias char-major-98-0 dt282x
 162   post-install dt282x /etc/dt282x.conf
 163
 164 * Calibration:
 165
 166 If your board has self-calibration capabilities,
 167 will want to run comedi_calibrate, an autocalibration tool that
 168 is packaged in a seperate tarball, in a bootup script.
 169
 170 * PCMCIA:
 171
 172 The PCMCIA drivers require at least a 2.6.16 kernel (at for
 173 unpatched mainline kernels).  You must also have pcmciautils
 174 and udev installed.  You can write a udev rule to automatically
 175 run gpib_config after the driver is loaded.
 176
 177 * Upgrading:
 178
 179 From versions prior to 0.6.0, you will need to edit and recompile
 180 all programs that use comedi or comedilib, since the names of
 181 functions and ioctls have changed.
 182
 183 From versions prior to 0.5.0, you will need to recompile all programs
 184 that use comedi or comedilib, since the interface to both of these has
 185 changed.  No changes should need to be made to the source of the
 186 programs.  The format for parameters of comedi_config has changed.
 187
 188 From versions prior to 0.4.0, you will need to run 'make dev' again
 189 to recreate /dev/comedi*, since the major number has changed.
 190