
                       Diamond Systems Corporation
                      Universal Driver Version 5.91

About This Package
------------------

This package contains the base driver software needed to develop for Diamond
Systems PC104 boards on Linux on x86.  Documentation and example source code is
available at http://www.diamondsystems.com/.

The online manual for DSCUD is at http://docs.diamondsystems.com/dscud/
See the Linux section of this manual for more help with installation.


Installing Driver Files
-----------------------

The base driver software and board software are packaged as a simple gzip'd tar
archive.  To install the base driver software type the following command at the
root user prompt:

    $ tar zfx dscud-5.91.tar.gz
	$ mv dscud5 /usr/local/

Later if you wish to uninstall the package you can simply delete this 
directory.


Building the Kernel Module
--------------------------

Once the driver files have been copied to /usr/local/dscud5 you should
run the "install.sh" script located in that directory.  

It is only required to run this script if you plan on using the interrupt
driven features of the product such as dscADSampleInt().  If you do not need
interrupt features you do not need to build the kernel module or run the
"load.sh" shell script.

Before running the "install.sh" script you must have installed the source
code to the Linux kernel on your system.  This kernel version must be the
same kernel version you will run on your target embedded system.  A kernel
module built for one version should not be run under other kernel versions
or driver instability may occur.

You must have configured the kernel source by running "make menuconfig"
and you must run "make dep" to prepare the kernel source for use in
building modules.

When you run the "install.sh" script it will search your system for
the kernel source and display a list of kernel source version which
may be suitable.  Select the version you will run on your target system
from the list and a kernel module will be compiled for that version
and installed in /lib/modules/misc.

If you have any problems, or additional questions about this process,
consult the online driver documentation, especially the section on
Linux located here:

http://docs.diamondsystems.com/dscud/manual_Instructions_for_Linux.html


Driver Components
-----------------

The driver contains three key components.

* The "dscud.h" header file must be included in any program which uses
  this driver.
* The "libdscud5.a" library must be linked with any executable which 
  uses this driver.
* The "dscudkp.c" kernel module must be compiled for your version of the
  Linux kernel and loaded before any interrupt operations occur.


Development Instructions
------------------------

The dscudkp kernel module is required for all DSCUD interrupt operations.  This
module must be loaded into the kernel every time the system boots.  The
included "load.sh" script can be run at startup to do this.  A simple way of
running this script at system start time is to run it from the Linux
startup script by running this command on most Linux distributions:

    echo "/usr/local/dscud5/load.sh &" >> /etc/rc.local

If "/etc/rc.local" does not exist on your system, check "/etc/rc.sysinit" or
"/etc/rc.d/boot.local".

The "load.sh" script also creates the device /dev/dscud the first time it
is run on a new system.  This device file is required for the proper 
operation of the kernel module.

Compiling software with the driver for Linux requires adding several options
when compiling.  For example:

  $ gcc myapp.c -I/usr/local/dscud5 -L/usr/local/dscud5 -ldscud5 -lm -pthread

Source code for demo programs showing how to use DSCUD features with all
Diamond Systems boards are available.  See the software section of the 
support area of the Diamond Systems website at the URL below to download
these demo programs:

	http://www.diamondsystems.com/support/software


Deployment Instructions
-----------------------

These are instructions for distributing the driver files along with the 
customer application onto new Linux systems for deployment.

The following things must be present on the target systems along with
your executable:

  * The Linux kernel module /lib/modules/misc/dscudkp.o (or .ko)
  * The device file /dev/dscud
  * A method of loading the kernel module when the system boots

If your development system and target system have similar Linux kernels you
will be able to simply copy the kernel module file from your development PC to
the target.

You can copy the "load.sh" script to the target and run it at startup using the
same method as on your development station.  This will create the /dev/dscud
device file and manage loading the kernel module at startup.

If the kernel module fails to load on the target, review the installation
instructions above to be sure you compiled the kernel module for the 
exact Linux kernel version on your target system.

Installation Notes
-----------------------------

These are some suggestions for how to deal with the most common errors in
installing the driver or running your own DSCUD programs for the first time.

"Kernel-module Version Mismatch"
Linux wants kernel modules to be compiled on the system the module it will run
on, for a specific kernel version.  Review the installation instructions
above to be sure you compiled the kernel module for the exact Linux kernel
version on your target system.

"Missing or Wrong Headers" 
You must download the full source to the Linux kernel of your target system
and extract it to /usr/src/linux.  Follow the instructions above for 
building the kernel module from source code.

"Unresolved Symbols"
Linux wants kernel modules to be compiled on the system the module it will run
on, for a specific kernel version.  Review the installation instructions
above to be sure you compiled the kernel module for the exact Linux kernel
version on your target system.


Getting Additional Help
-----------------------

Please review the online documentation for the driver, especially
the Linux installation section, before contacting support, as many
of the most frequently asked questions are answered there.

The Diamond Systems website at http://www.diamondsystems.com/

Call toll-free 800-367-2104.

Outside North America call 510-456-7800.

