The software package includes device drivers, APIs, and support and diagnostic programs for Communication Automation Corporation's (CAC) desktop PCI DPT4 board.
The software distributions for Solaris, Linux and Windows are available for downloading from the CAC Software Site or on CDROM.
This document describes how to install the DPT4 software package on
DPT4 Software Installation for Solaris and Linux
An installation tool from the GNU Project (www.gnu.org) is used to configure the software for a particular target environment. The file named INSTALL in the top-level directory of the installation contains generic information about using the configuration tool.
Note that while you may be able to unpack and install the libraries and programs as a normal Unix user, you will need to have root access privileges to install the device driver.
Specific, step-by-step instructions are provided below in the following sections:
Install your DPT4 board(s) in appropriate PCI slots of your computer. The system will identify the boards based on which slots they located in. If you installing more than one DPT4 board, the board found closest to the CPU will be named "dpt0" and the others will be named in order, "dpt1", "dpt2", etc. The ordering may vary depending on PCI bus slot ordering.
Solaris systems save the device information for each board when the device driver is installed and when new boards are added to the system. The DPT4 boards will retain their designations based on the slot they are in. If a board is moved to a new slot it will be given a new designation. For example, if a board originally installed in slot1 and named "dpt0" is moved to the adjacent slot, its new designation will be "dpt1". The system will still have a record for a "dpt0" but the device is no longer installed. It is recommended that the boards not be relocated after the initial installation to avoid confusion.
On Linux systems the boards will always be designated in the order they are found by the system, with the first found being named "dpt0", etc.
2. Download (if necessary) and Extract the Software Distribution
The companion gunzip is available for Solaris from several software sites including Sunfreeware.com. It is included with most Linux distributions.
To unpack the downloaded version of the software distribution, create your local directory and place the archive file there. Then run the gunzip and tar programs as shown:
# mkdir /usr/cac
# cd /usr/cac
# (download the software distribution to here)
# gunzip -c dpt-version.tar.gz | tar xvf -
If you are receiving the software on the CDROM there is no need to download any additional software. Load the CDROM and you can find the software packaged in tar format in the unix or solaris directory of the CDROM named: dpt-version.tar where version denotes the version number of the software release (e.g. dpt-1.1.1.tar).
You can unpack the software onto your system by creating your local directory, cd'ing into it and running the tar program. For example:
# mkdir /usr/cac
# cd /usr/cac
# tar xvf /cdrom/unix/dpt-version.tar
The resulting, unpacked software distribution is placed in a directory named dpt-version where version denotes the version number of the software release. For example:
An unpacked copy of the distribution is also available on the CDROM in a sub-directory of the solaris directory named dpt-version. This is provided as a backup to view the original distribution files.
Note: The current software distribution includes support for both Solaris and Linux in the same package. The directory on the CDROM may be named either "solaris" or "unix". Device driver code for Solaris and Linux are in separate sub-directories of the unpacked software distribution. The configuration step will configure your package to use the proper device driver directory for the system you run the configuration on.
3a. Choose the Installation Directory
Users of the software should include the directory, $CAC/bin, on their program search path to enable running the utility programs from any location in the filesystem. This is usually done by appending to the PATH environment variable, as described earlier. If the DPT4 diagnostic programs are to be run on a regular basis, the directory, $CAC/dpt/diag should also be included in the search path.
If you use the Bourne shell (sh or one like it) use the following commands to set this variable (replace "/usr/cac" with the directory you have chosen):
# CAC=/usr/cac
# export CAC
# PATH=$PATH:$CAC/bin
# export PATH
You can add those commands to your .profile file, or whatever file your shell reads startup commands from, so that the CAC variable and PATH will be set automatically the next time you log on.
If you use the C-shell (csh or one like it) use the following command to set this variable (replace "/usr/cac" with the directory you have chosen):
# setenv CAC /usr/cac
# setenv PATH ${PATH}:$CAC/bin
You can add those command to your .login file so that the CAC variable and PATH will be set automatically the next time you log on.
3b. Choose the Build Directory
If you choose to build the software in the distribution source directory run:
# cd /usr/cac/dpt-version
# ./configure --prefix=$CAC
If you choose the build the software in a separate directory the commands
are slightly different, specifying the path to the configure program
in the source directory.
# mkdir /usr/cac/dpt
# cd /usr/cac/dpt
# ../dpt-version/configure --prefix=$CAC
# ./configure --help
This will generate a rather long list of options, many of which are part of
the standard GNU software system but are irrelevant for the DPT4 software.
The options of interest are:
--prefix=PREFIX
--enable-smpci
--enable-hdlc
--enable-devel
--disable-diags
--disable-demos
--with-readline=option
The --with-readline parameter allows the user to specify the following readline options:
| cac | Use the readline library provided by CAC. (default) |
| system | Search for a readline library installed on the system. |
| disable | Disable the use of any readline library. |
Many host systems have a readline or compatible facility already installed. However the use of the readline facility in the CAC diagnostics may be incompatible with newer distributions of the readline library. Therefore, as of DPT release 1.4.1, the default readline option is to compile and use the version in the DPT software distribution.
Special options for Solaris device driver configuration are:
--enable-solaris64
--enable-solaris32
These options force the device driver configuration to be compiled for the 32-bit or 64-bit kernel regardless of the currently running system. This may be useful if you need to prepare an installation that can be used with a different kernel.
--with-prebuilt_driver
| pcie1drv_sparc64 | built for Solaris 2.7, Sparc (sun4u) architecture, 64-bit kernel |
| pcie1drv_sparc32 | built for Solaris 2.7, Sparc (sun4u) architecture, 32-bit kernel |
| pcie1drv_intel32 | built for Solaris 2.8, Intel architecture, 32-bit kernel |
Pre-built drivers may work for systems of the same kernel address space but a different version of Solaris or architecture. However, CAC has not tested it in that environment. If you require a pre-built driver for a different combination of architecture and operating system version contact CAC.
Special options for Linux device driver configuration are:
--with-majordev=#
Be sure not to specify a number that is reserved for other devices in the system. Consult the file, devices.txt, in the Documentation directory of the Linux kernel source for a list of devices with reserved major device numbers.
In any case, the various shell scripts used for creating device nodes examine the contents of /proc/devices to determine the major device number for the DPT driver.
--with-numboards=#
--disable-vsyms
--with-ksrcdir=dirname
By default this directory is determined by the version of the currently running Linux kernel at the time the configure program is run. For Linux 2.4 kernels, it is usually found in /usr/src/linux-version. For Linux 2.6 kernels this directory will be the module build directory which is usually found in /lib/modules/version/build.
The source or build directory may be specified to be that of a different version of the Kernel to allow building the device driver to be installed on a system running a different version of the Linux kernel. There are some additional requirements and limits for the ability to cross-build the device driver, described below.
--with-kmoddir=dirname
The module installation location setting affects both where the Makefile installs the module and where the boot script looks for it. By default the directory is determined by the currently running kernel version at installation time and at boot time and is located in /lib/modules/version/misc.
Because the default location is determined at installation or boot time, it is not usually required to specify this option when configuring the device driver to be built for a different kernel version.
--with-rcdir=dirname
--with-initdir=dirname
If neither of those exist or you need to specify another location, use the --with-rcdir option to name the parent directory where the directories rc2.d, rc3.d, rc5.d, etc. are found. If that directory does not also include the directory named init.d then also use the --with-initdir option to specify the parent directory of the init.d directory.
As an example, for a Solaris system running a 64-bit kernel on a Sparc machine without a 64-bit capable compiler, the configure command would be:
# ./configure --prefix=$CAC --with-prebuilt_driver
For a Linux system in which you expect to install at most 2 DPT boards, the configure command would be:
# ./configure --prefix=$CAC --with-numboards=2
4. Compile and Install the Software
# make
This will compile the various libraries and programs that comprise the DPT4 software. Excluded from the default build is the device driver. The device driver is built and installed as a separate operation, described below.
Once the API and programs have successfully compiled they can be installed by running the command:
# make install
This will install the software into the following directories:
| directory | files installed |
| $CAC/lib | the DPT API library and other libraries used by the software |
| $CAC/include | header files required for applications that use the API |
| $CAC/bin | support and utility programs |
| $CAC/dpt/diag | diagnostic programs |
| $CAC/dpt/demos | demonstration programs |
| $CAC/dpt/flash | data files containing flash data and PLL configuration files |
| $CAC/smpci | support files for smPCI modules (if configured with --enable-smpci) |
DPT software versions prior to 1.4.3 installed the diagnostic and demonstration programs in $CAC/bin along with the utility programs. If you are upgrading from a version prior to 1.4.3 you should run the following command before running make install to remove any old program version from $CAC/bin:
# make uninstall
This should be run using the new software release because this procedure did not work properly in some older versions.
5. Compile and Install the Device Driver
To compile and install the Solaris device driver, change your current directory to the soldev directory of the software distribution and run make install-drv. For example:
# cd /usr/cac/dpt-version/soldev
# make install-drv
This will compile the driver code and run the system commands to install the driver in your system. The device driver installation process includes installing a system start-up script, dpinit.sh, that will automatically initialize the DPT4 boards as part of the system boot-up procedure.
Note: a 64-bit capable compiler is required if you are building the device driver for a 64-bit Solaris kernel. Compatible 64-bit compilers include Sun Workshop or Forte compiler and, as of DPT release version 1.4.0, GCC version 3.2 or higher. If a 64-bit compiler is not available, use the prebuilt_driver option when configuring the software as described above.
Compiling the Linux device driver for 2.4 version kernels requires the Kernel source to be installed. This is normally installed with the kernel-source RPM.
Compiling the Linux device driver for a 2.6 version kernel requires that the kernel development packages are installed. These are normally installed with the kernel-devel RPM and, for multi-CPU systems, the kernel-smp-devel RPM.
Check the installation using the commands appropriate for the kernel version you are using:
# rpm -q kernel-source
or
# rpm -q kernel-devel
# rpm -q kernel-smp-devel
If the command displays a message saying the package is not installed you must install the required RPMs from your Linux distribution. If your kernel was installed using other means than the RPM system, you may have to use the --with-ksrcdir option when running the software configuration script to specify the location of the installed kernel source or build directory.
To compile and install the Linux device driver, change your current directory to the linuxdev directory of the software distribution and run make install-dev. For example:
# cd /usr/cac/dpt-version/linuxdev
# make install-dev
This will compile the driver code to create the loadable kernel module, load the module and create device entries in the /dev directory. It also copies the driver module into the /lib/modules directory of the system for use by the boot-up initialization script (see below). The exact location depends on the current kernel version:
/lib/modules/kernel-version/misc
As of version 1.4.1, the device driver will be properly compiled for SMP if the system is running in SMP mode. When the driver is installed on a system running in SMP kernel mode the module is copied to the /lib/modules/directory for SMP modules. To install the module for both SMP and non-SMP kernel modes, after installing the driver while running in the current kernel mode (SMP or non-SMP), reboot the system in the other kernel mode and run:
# cd /usr/cac/dpt-version/linuxdev
# make clean
# make install-dev
This will force the driver module to be rebuilt and installed for the new kernel mode. Now both versions will be installed in the appropriate modules directories. For example:
/lib/modules/2.4.18-3smp/misc/dptdrv.o - the SMP driver
/lib/modules/2.4.18-3/misc/dptdrv.o - the non-SMP driver
When installing a new device driver on a system that has a DPT4 driver already loaded the module must be unloaded before the new one can be installed. To do this, run this command prior to the make install-dev command:
# make unload-drv
If you need to uninstall the device driver completely, run the command:
# make uninstall-dev
Whenever the device driver is loaded or re-loaded, the dpinit
program must be run to initialize the DPT boards (see below).
The device driver module must be re-loaded and the device nodes re-created whenever the system is rebooted. To automate this process you can install cacdpt.sh initialization script to be included in the system's boot-up initialization procedure. It is recommended that this be installed after you have verified that the driver loads and operates properly in your system and you can successfully run the dpinit program.
To install the DPT initialization script run the command:
# make install-rc
This will copy the cacdpt.sh shell script to the system's init.d directory
and create links in other RC directories to run the boot-up sequence when the
system boots into run-level 3 or 5 and to run the shutdown sequence when the
system switches to run level 6 or 0 (reboot or halt).
The DPT initialization script's boot-up sequence loads the device driver module, creates device entries in /dev and runs the dpinit program to start the embedded code on the DPT boards. The script loads the device driver module from the appropriate modules directory for the kernel mode that is running (i.e. SMP or non-SMP).
During system start up, the init-script will be indicated by the message, "Starting cacdpt". It may pause for several seconds while initializing the DPT boards, especially if FPGA's on smPCI expansion modules are being configured. Check the system log file (/var/log/messages) for details on the initialization sequence.
The script's shutdown sequence halts the embedded code on the DPT boards to stop interrupts and other automated PCI activity.
If you need to remove the DPT init-scripts from the system run the command:
# make uninstall-rc
5c. Cross-Building the Device Driver
Device drivers are generally much more dependent on the specific version of an operating system. The default configuration and build for the device driver assumes that the device driver is to be installed for the currently running version of the operating system on the current hardware platform.
Cross-compiling the device driver, building it for installation on a different version of the operating system is supported to a limited extent by the configure program. Compiling a device driver for a different hardware platform is not supported.
When cross-compiling the device driver to be installed later for a different version of the kernel, do not use the make install-dev command as show in the previous sections. Instead, run
# make driver
This will compile the device driver to produce the loadable module
without attempting to install it on the current system.
The Solaris device driver has not typically been dependent on the version of the operating system. For example, a device driver built on Solaris 8 can be installed on a system running Solaris 9. The primary dependency for the Solaris device driver is whether or not it is build for a kernel that supports 64-bit addressing. A device driver built for the 32-bit version of the Solaris kernel will not load for the 64-bit version of Solaris, and vice-versa. If it is necessary to build a Solaris device driver for they kernel type (32-bit or 64-bit) that is not the currently running type, one of the configuration options, --enable-solaris64 or --enable-solaris32 may be used.
Linux kernel modules are much more dependent on the kernel version and, in some circumstances, on the version of the compiler used.
The main requirement for compiling the Linux device driver for a different version of the kernel is to have the kernel source for the target version installed. This is most easily accomplished by installed the appropriate RPM package; the kernel-source package for 2.4 kernels, or the kernel-devel and kernel-smp-devel packages for 2.6 kernels. The --with-ksrcdir configuration option may be used to direct the configuration to the kernel source (or build) directory for the desired target kernel version. Note: this option is available in release versions 1.4.6 or higher.
For 2.4 kernels, the kernel source directory must be configured and build up through the step of running make dep in order to have all the required module version information available.
This works on its own for building the Linux device driver for various kernel versions with the same Red Hat Linux release family (i.e. Red Hat 8, Red Hat 9, Enterprise Linux 3 and Enterprise Linux 4). Certain problems arise when attempting to build the device driver for a different Linux distribution. For example, to compile the driver for Red Hat Enterprise Linux 4 (a 2.6 kernel) while running Red Hat Enterprise 3, the version of the GCC compiler from the Red Hat Enterprise Linux 4 distribution must be used, and vice-versa. To specify the compiler, you should specify the full path to the gcc program as the environment variable, CC. For example:
# setenv CC /usr/local/rhel4gcc/bin/gcc
# make driver
or
# CC=/usr/local/rhel4gcc/bin/gcc
# export CC
# make driver
Compiling a device driver for Reh Hat 8 or Red Hat 9 while running newer Red Hat distributions may not work at all because of various differences in how the kernel is build and installed.
To ensure that the DPT4 boards are up to date run the dpflashup program from a shell window as shown below:
# dpflashup all
The program will compare the code versions in the flash of each DPT4 board with the versions supplied with the new software release. Any new versions will be loaded in the flash memory.
In some cases, depending on which flash data is updated, the changes will not take effect until the system is power-cycled. The dpflashup program will display a message if a power-cycle is required.
From a command shell window run the dpinit program as shown below.
# dpinit
The dpinit program starts the embedded code running on all of the DPT4 boards found in the system. It also configures FPGA's on any installed smPCI expansion modules. For each board initialized the program will display the word "Done". It takes a few seconds for the embedded code to initialize the channelization software on the board.
The device driver installation process includes installing a system start-up script that will automatically initialize the DPT boards as part of the system boot-up procedure. Although, it does not hurt to run the command more than once. When run a second time it first halts the embedded code and then restarts it to do a full initialization.
8. Creating a Software Package for Application Deployment
# make package
This will gather the necessary files, create device driver installation
scripts, and create a archive named
dpt-pkg-version.tar.
For example: dpt-pkg-1.3.1.tar.
The package includes the following file groups:
| directory | package files |
| ./bin | support and utility programs |
| ./dpt/soldev | Solaris device driver and installation scripts (Solaris systems only) |
| ./dpt/linuxdev | Linux device driver and installation scripts (Linux systems only) |
| ./dpt/flash | data files containing flash data and PLL configurations |
| ./smpci | support files for smPCI modules (if configured with --enable-smpci) |
The package must be installed on systems of similar configuration as the system the software was configured and compiled on. Solaris systems must use the same kernel address width (32-bit or 64-bit) as the build system or as specified to the configure command. Linux systems must be running the same kernel version. Additionally, the package should be installed in the same directory name specified by the --prefix option to the configure command, otherwise the boot-up initialization scripts will not find the dpinit program. It is also recommended the users on the target systems include the $CAC variable in their environment to facilitate using the dpflashup program, if necessary.
To install the package on target systems, create the top-level installation directory (same as the specified prefix) and extract the package archive. For example:
# mkdir $CAC
# tar xf dpt-pkg-1.3.1.tar
To install the device driver and boot-up initialization script
on the target system, run the following commands as the root user:
# cd $CAC/dpt/soldev
# ./install.sh
or, for Linux systems,
# cd $CAC/dpt/linuxdev
# ./install.sh
Run the dpinit program ($CAC/bin/dpinit) to make sure the
boards and device driver are functioning properly.
Should it be necessary to uninstall the device driver from the target system,
run the unintall.sh script in the appropriate device driver directory
($CAC/dpt/soldev or $CAC/dpt/linuxdev).
DPT4 Software Installation for Windows 2000 and XP Systems
Specific, step-by-step instructions are provided below in the following sections:
Install your DPT4 board(s) in appropriate PCI slots of your computer. When you first boot your system with the boards installed and before you have installed the DPT software, a "New Hardware Found Wizard" dialog will appear. Ignore this dialog for now and proceed to install the software.
The system will identify the boards based on which slots they are located in. If you are installing more than one DPT4 board, the board found closest to the CPU will be named "dpt0" and the others will be named in order, "dpt1", "dpt2", etc. The ordering may vary depending on PCI bus slot ordering.
On Windows systems the boards will always be designated in the order they are found by the system, with the first found being named "dpt0", etc.
It is recommended that the boards not be relocated after the initial installation to avoid confusion.
2. Download (if necessary) and Extract the Software Distribution
Download the distribution archive file to some temporary folder and unpack it. Most Windows installations include a program for unpacking ZIP files. Otherwise use a program such as Stuffit Expander from Aladdin Systems or winzip from Winzip.com
If you are receiving the software on the CDROM there is no need to download any additional software. Loading the CDROM should, in most cases, open a WEB browser to a page from the CDROM providing you with links to the software installer and documentation. In fact, you may be reading this document from the CDROM.
The distribution archive is found in the win2k directory of the CDROM named: dpt_version.zip where version denotes the version number of the software release (e.g. dpt_145.zip). An unpacked copy of the distribution is also available on the CDROM in a sub-directory of the win2k directory named dpt_version. You may extract the files from the ZIP archive to your local hard drive or run the installer directly from the CDROM if you prefer.
Whether you have extracted the software archive to your local hard drive or you choose to use the installer directly from the CDROM, you should see the following files in the folder where the installer is:
For CDROM distributions you may run the installer directly from a link on the "WEB" page that appears. If you are installing from the distribution folder double-click the setup.exe file to launch the installer.
It may take a few moments for the Windows Installer to initialize. In fact, the preliminary message boxes may disappear for several seconds before the installer actually starts up. Wait for the installer dialog to appear saying, "Welcome to the InstallShield Wizard for CAC DPT4 Software". Click on the "Next" button. Read the license agreement, select the radio button to accept the terms and click on the "Next" button.
The next dialog asks about the destination folder for the installed software. The recommended destination is c:\cac. You have the opportunity to select a different location.
The installer will now check your current program search path and environment variables and display a dialog named "Path and Environment Settings" with recommended changes. If no changes are required this dialog will be skipped.
The next dialog asks you to choose a "Setup Type". Most users should choose the "Typical" setup which includes the commonly used components. The "Complete" setup will install everything and may be used if you desire to have a debugging version of the API, source files and support for smPCI modules. The "Custom" setup allows you to choose the additional components. If you selected "Custom Setup" the next dialog asks you to select the components using pulldown menus.
The next dialog after selecting the setup type and components is named "Ready to Install the Software". This gives you a chance to go "Back" and modify your installation parameters. When you are ready to install the software click the "Install" button. The installer will now copy the DPT4 software files to the chosen destination and setup some items in the system registry.
When the installation is complete, the final dialog provides the opportunity to read information about installing the device driver. This information is also included here but the file displayed by the installer may contain updated information. Click the "Finish" button to terminate the Windows Installer.
where {SYSROOT} is the system root folder, e.g. C:\winnt or C:\windows.
There are varying steps to take to complete the device driver installation depending on your circumstances.
4a. Install Device Driver for a First Time Installation
In this case, the easiest method to complete the device driver installation is to reboot the system. Rebooting is also necessary to ensure that any new environment settings become effective.
To reboot the system click on the Windows "Start" button and select "Shut Down". In the dialog that appears choose "Restart" from the pulldown menu and click "OK".
When the system is rebooted and you log back on, Windows will detect the new DPT4 devices and should automatically install the device driver for them.
If you prefer not to reboot you can follow these steps to complete the device driver installation:
4b. Updating Device Driver for Upgrades After Version 1.1.1
To upgrade from earlier versions (0.06 or less) please read section C, below.
Update Method 1 (without requiring reboot)
Update Method 2 (requires reboot)
At this point you must reboot the computer to load the new device driver code.
4c. Replacing Device Driver from Versions Prior to 1.1.1
If you are upgrading from DPT4 software version 0.06 or earlier, you must now uninstall existing device driver(s) then reboot the system. Please follow the procedure below.
When the system is rebooted and you log back on, Windows will detect the new DPT4 devices and should automatically install the device driver for them.
To ensure that the DPT4 boards are up to date run the dpflashup program from a command shell window.
Click on the Windows "Start" button and select "Run". In the dialog that opens there is a text line labeled "Open" into which you should type the word, "cmd", (without the quotes). Then click the "OK" button. This should open a command shell window.
In the command shell window run the dpflashup program by typing
C:\> dpflashup all
Hit the "Enter" key on the keyboard. The program will compare the code versions in the flash of each DPT4 board with the versions supplied with the new software release. Any new versions will be loaded in the flash memory.
In some cases, depending on which flash data is updated, the changes will not take effect until the system is power-cycled. The dpflashup program will display a message about this if a power-cycle is required.
From a command shell window run the dpinit program as shown below.
C:\> dpinit
The dpinit program starts the embedded code running on all of the DPT4 boards found in the system. For each board initialized the program will display the word "Done". It takes a few seconds for the embedded code to initialize the channelization software on the board.
This program needs to be run each time the system is turned on. You may want to add the dpinit command to a startup script for your login session. It does not hurt to run the command more than once. When run a second time it first halts the embedded code and then restarts it to do a full initialization.