
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-3.2.21.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 you
	have an ISA based card you will need to use the
	'--enable-isa' option unless you have a kernel version >=
	3.12.0 with CONFIG_ISA set.

	If the configure script does not exist (you are using a svn
	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 modules
-----------------------------

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.  If
	your device requires a external firmware 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 "fxload" and either the "hotplug" or "udev"
	packages installed on your computer.  The hotplug scripts 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.  For systems using udev the rules
	files are installed in /etc/udev/rules.d/ which invoke the USB
	hotplug scripts.

        Using multiple-boards of the same type with hotplug requires
	udev support: In the hotplug scripts you can use either the
	serial number $SERIAL or the device path $DEVPATH to decide
	which board is to be associated with which minor in your
	gpib.conf.  Using serial number it does not matter which usb
	ports you use.  Using device path the association will be made
	with the physical usb port in your system. To obtain the
	serial numbers or device paths for your boards plug the boards
	in and check the syslog for the output from the default
	hotplog script. The order of the messages will correspond to
	the order in which you plugged the boards in. Edit the hotplug
	scripts to setup the serial numbers/device paths and minors
	that correspond to your system.
	
E) Trying it out
----------------

	You may find the examples/ibtest program useful as a starting
	point in trying out your setup.  The examples/ibterm program
	provides a simple terminal interface to send commands to a
	specific instrument and view the response.

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.

G) Uninstalling
---------------

	Type 'make uninstall' as root from the install root of the
	build tree (i.e. the same directory from which the package was
	originally installed).

	Note: The configuration files and scripts are not uninstalled
	by this procedure. They need to be removed manually if you
	wish to re-install the standard distribution configuration
	files and scripts later since existing files are not
	overwritten by the install procedure. Check the following file
	and directories:

	      /etc/gpib.conf
	      /etc/hotplug/usb/
	      /etc/udev/rules.d/