wrdk/testudo/linux-gpib-svn/INSTALL

Installing Linux-GPIB
--------------------------------------------------------------------

A) First steps:
---------------

o) Installing your Hardware:
	If you have an old ISA board it may need to be configured by setting
	the appropriate board jumpers or switches
	for its base-address, interrupt-level (IRQ) and dma-request channel (DMA).
	Please choose a free base-address, irq and dma for your system
	(refer to your
	hardware documentation for this). You can "cat" /proc/interrupts,
	/proc/dma, /proc/ioports, and /proc/iomem to get information on
	interrupt, dma lines, io ports, and io memory already in use by other
	drivers. Now shut down your system and
	install the board in your computer.

o) Unpacking the Software:
	Unpack the archives with the 'tar' program, for example
	'tar -xzf linux-gpib.tar.gz'.

	You will also need the linux kernel source code, or a reasonable approximation
	thereof, which the linux-gpib
	package reads for header files and compilation variables when compiling
	the gpib kernel modules.  Ideally, you have the linux source your
	current kernel was compiled from, or are willing to compile
	a fresh kernel.  Otherwise, your distribution may provide a useable setup
	you can compile against (usually pointed at by a symbolic link at
	/lib/modules/<kernel_version>/build).  For example, on Debian Sarge
	you can install the kernel-headers package which matches the kernel you
	are running and all should be well.  
		You could also prepare a kernel source tree that matches
	the kernel you are currently running if you have its config file (in
	the Debian distibution the config files for the kernel-image packages
	are in the /boot directory).  Perform the following steps:
	1) Get a copy of the kernel source that matches the kernel you are
		running.  Unpack it and copy your kernel config file to '.config'
		in the top directory of your kernel source.  Note: you will need
		to have write permission to your kernel source
		directory when compiling linux-gpib, so it might be easiest to unpack
		the kernel source into a user-owned directory.
	2) You might need to edit the file 'Makefile' in the kernel source.
		At the top of the Makefile, the variable EXTRAVERSION is defined.
		If necessary, change it to match your kernel (for example, if the command
		'uname -r' produces "2.6.8-1-386" then your EXTRAVERSION should be
		set as 'EXTRAVERSION=-1-386'.
	3) run 'make oldconfig' in your kernel source directory.
	4) run 'make vmlinux' and 'make modules' in the kernel source directory.  This will
		compile the Linux kernel and modules (and take a long time).
		You can probably get by with just doing a 'make modules_prepare' instead, and
		your GPIB driver modules should still work.  However,
		the GPIB modules will taint your kernel when loaded.  Tainting is
		a flag to kernel developers that something fishy has been done, and
		they tend to ignore bug reports from tainted kernels.

B) Installing Linux-GPIB
-------------------------

o) cd to your linux-gpib directory and run the './configure' script.
	run './configure --help' for a list of the possible options.
	In particular, the '--with-linux-srcdir' option is useful for
	specifying the location of your Linux kernel source directory,
	and the '--enable-pcmcia' option is useful for laptops.

	If the configure script does not exist (you are using a cvs
	checkout), it can be generated by running the './bootstrap'
	script.  You will need automake, autoconf, etc. to generate
	the configure script.

	Type 'make'.  Now the Package will be compiled.  Note, you
	will need to use the same version of gcc to compile the linux-gpib
	kernel modules as was used to compile your kernel.  Using
	different versions has been known to cause problems (kernel panics,
	crashes, etc.).  Linux-gpib will compile its kernel modules
	with the compiler specified by the kernel's Makefile (the CC
	variable).

	Type 'make install' (as root).  This will copy the kernel driver to
	/lib/modules/<kernel version>/gpib as well as install the library
	and headers files.  Make sure the directory you installed the
	shared library to is listed in your /etc/ld.so.conf file,
	so that ld can find libgpib.so.  If the directory is not listed,
	add it and then run 'ldconfig'.

	To give a user access to the computer's gpib board you will have to add
	them to the group 'gpib' (you can use the 'usermod' tool or edit
	/etc/groups to change the groups a user belongs to).  Or, you could change the
	permissions on the device files /dev/gpib[0-15] to something you like
	better, using 'chmod' (or edit devfsd.conf if you are using devfs).
	If you are using udev, you can set the permissions on the gpib device
	files by adding a line like:
	KERNEL=="gpib[0-9]*",    MODE="0660", GROUP="gpib"
	to your udev rules (/etc/udev/permissions.rules on Debian Etch).

C) Configuring the GPIB-Library
-------------------------------

	Edit /etc/gpib.conf to match your interface board, and any devices you wish
	to open via ibfind().  See the documentation in doc/ for
	more information.

D) Loading the driver module
-----------------------------

o) PCI and ISA boards

	You can load the driver module by typing

		modprobe <driver name>

	See the documentation in doc/ to see which driver your board is supported
	by.

	You need to run the 'gpib_config' utility to setup the driver
	before you can use it (the 'minor' options specifies which
	board index you are setting up):

		gpib_config --minor 0

	You can also set up the modules to load automatically by adding lines
	something like 

	alias char-major-160 gpib_common
	alias gpib0 tnt4882
	install tnt4882 PATH=/sbin:/usr/sbin:/usr/local/sbin:$PATH;modprobe --ignore-install tnt4882;gpib_config --minor 0

	to /etc/modprobe.conf, which would autoload the tnt4882.o module and run
	gpib_config when the library is used.  In the Debian distribution, modprobe.conf
	is modified by adding a file to the /etc/modprobe.d directory, and then running
	'update-modules'.

o) PCMCIA cards

	If you are using a PCMCIA board, copy the files in the etc/pcmcia
	subdirectory to /etc/pcmcia.  You may need to send a SIGHUP signal
	to the cardmgr daemon to force it to reload the files in 
	/etc/pcmcia (alternatively you could use your pcmcia init.d script
	to restart the cardmgr, or you could just reboot).  The driver
	module will be loaded as needed by the cardmgr.
	You may wish to edit the options passed to the gpib_config call in the
	/etc/pcmcia/linux-gpib-pcmcia script.

o) USB devices

	USB hotplug scripts will be installed into /etc/hotplug/usb if they do not already exist.
	You may wish to edit the GPIB_CONFIG_OPTIONS in the hotplug script for your device. 
	You will also need to install firmware files for your device, a tarball is available from
	http://linux-gpib.sourceforge.net/firmware/.  Make sure you have
	the "hotplug" and "fxload" packages installed on your computer.  The hotplug system
	will automatically upload the firmware to your device and load the driver module when
	the device is plugged in.  If you have errors, check your system log files (not dmesg)
	for messages from the hotplug scripts.

E) Trying it out
----------------

	You may find the examples/ibtest program useful as a starting point in trying
	out your setup.

F) Bindings for other languages
-------------------------------

	The bindings to other languages will be enabled by default in the
	'./configure' script.  They will not be built if you disable
	them with the appropriate configure option, or if the necessary
	header files/libraries are not found on your machine.