ClearSpeed logo

Driver and Diagnostics Software Installation Instructions

For use with Linux operating systems

Note: To install the software for your ClearSpeed AdvanceTM Accelerator Board you will require root access. Some parts of the installation may have to be carried out by the system administrator.

Before you install

Checking and upgrading the board firmware

The Advance board contains an FPGA (field programmable gate array) which provides the PCI-X host interface and other logic. The data for this FPGA is stored in a flash memory on the board.

If you already have a version of the driver and diagnostics packages and a board installed then you can check, and upgrade if necessary, before continuing with the installation. Otherwise, you can do it after the installation instructions below.

The version of the FPGA image can be checked using the command csreset -Av. This will display information about the installed board including the version of the FPGA image. See the FPGA update release notes for the latest version numbers. If your board does not report the latest version number, it will need to be updated. The latest version can be downloaded from the ClearSpeed support web site. See the FPGA update release notes and the Advance Board User's Guide for instructions.

Step 1: Install the driver package

  1. Download the Base Package tarball from the ClearSpeed support site support.clearspeed.com/downloads/.
  2. Unpack the contents of the Base Package. This will create a directory called something similar to csx_600_2.21_base containing the components of the package.
  3. For the following steps you will need to be logged in as root.
    Note:
    if you use su to log in as root, please ensure you use the command su - to ensure that the correct environment and path is set up for the following steps.
  4. Change to the directory containing the contents of the Base Package; for example, cd ~/csx_600_2.21_base (note that the actual directory name may vary).
  5. The drivers package is provided as an RPM file and is installed using the rpm command:
  6. rpm -i csx600_m512_le-runtime-<version>.<arch>.rpm

    This copies the runtime libraries and the driver to interface with the board to your machine.

    Release notes and other documentation can be found in the docs directory of the installation.

Step 2: Install the kernel module

To complete the installation of the software drivers, a kernel module needs to be built and installed, and some configuration files need to be changed. Shell scripts are provided to do all of this.

The driver installation procedure depends on having the header files for the currently running kernel. If the configure or make steps fail, it is most likely that these header files are not available. To obtain the appropriate header files refer to the installation guide for your kernel distribution.

Depending on your kernel version, you will either have a Jungo or a CSX driver available. If you are running a 2.4 kernel, you will need to use the Jungo driver which is included with this package. Any Jungo driver from a previous installation must be removed. If you are running a 2.6 kernel then you will use the open source CSX driver, and again will need to uninstall any older Jungo drivers.

CSX installation (for 2.6 kernels)

To install the CSX kernel module (still logged in as root) execute the following commands (assuming the driver has been installed to the default directory):

cd /opt/clearspeed/csx600_m512_le/drivers/csx/
sh install-csx

Any error messages at this stage should be investigated as these may indicate problems that prevent the driver working properly. If the machine has previously had an older driver installed, you should remove any entries in /etc/rc.local that refer to windrvr6.

The driver should now be installed as a kernel module and should also restart after a reboot.

When the board is installed, the driver can be controlled manually via the following commands (as root).

To start the driver, execute the command:

/etc/init.d/csx start

To stop the driver, execute the command:

/etc/init.d/csx stop

Jungo installation (for 2.4 kernels)

To install the Jungo kernel module (still logged in as root) execute the following commands (assuming the driver has been installed to the default directory):

cd /opt/clearspeed/csx600_m512_le/drivers/jungo/
sh install-jungo
[See note]

Any error messages at this stage should be investigated as these may indicate problems that prevent the driver working properly. If the machine has previously had an older driver installed, you should remove any entries in /etc/rc.local that refer to windrvr6.

The driver should now be installed as a kernel module and should also restart after a reboot.

When the board is installed, the driver can be controlled manually via the following commands (as root).

To start the driver, execute the command:

/etc/init.d/csx600-windrvr6 start

To stop the driver, execute the command:

/etc/init.d/csx600-windrvr6 stop

Step 3: Install the board diagnostics package

After the drivers have been installed, you can install the diagnostics package. This contains tools which will verify the correct functioning of the board and drivers.

To install the board diagnostic package:

  1. Change to the directory board_diagnostics in the Base Package directory.
  2. Install the diagnostics package using the rpm command:
  3. rpm -i csx600_m512_le-board_diagnostics-<version>.<arch>.rpm 

Step 4: Install board

If your Advance board is not already installed, now is the time to install it. Refer to the Advance Accelerator Board Installation Guide for details.

Step 5: Verify the installation of the board and drivers

You can now run the diagnostic program to check that the board and associated drivers have been successfully installed. This utility runs a number of tests on the installed board(s) and reports any problems.

Diagnostic tests

To run the diagnostics tests:

  1. Go to a directory where you have write privileges; for example:
  2. cd /tmp
  3. Use the shell script provided to set up the environment variables:
  4. source /opt/clearspeed/csx600_m512_le/bin/bashrc
  5. Run the program:
  6. perl /opt/clearspeed/csx600_m512_le/bin/run_tests.pl

Note that some of these tests may take several minutes to run to completion.

The diagnostics write the results of the tests to the file test.log in the current directory. ClearSpeed technical support may require the output of this utility to help diagnose any installation problems.

If any tests fail, refer to the 'Troubleshooting' section of the Advance Board User's Guide for help. If the problem persists, please contact support@clearspeed.com.

Mandelbrot demonstration

A simple Mandelbrot program can also be run. This is a graphical program and requires X to be running. This can be run as follows:

  1. Use the shell script provided to set up the environment variables:
  2. source /opt/clearspeed/csx600_m512_le/bin/bashrc
  3. Reset the board:
  4. csreset -Av
  5. Run the Mandelbrot demo:
  6. /opt/clearspeed/csx600_m512_le/bin/app_mandelbrot

    When the program starts, it opens a window to display views of a Mandelbrot set. This program requires an X server to be running.

app_mandelbrot is based in part on the work of the FLTK project (www.fltk.org).

Uninstalling

The packages can be uninstalled using the rpm -e command. Packages must be uninstalled in the reverse of the order in which they were installed. You can get a list of the installed ClearSpeed RPMs with the command:

rpm -qa | grep csx

Before removing the driver package, you should remove the Jungo or CSX driver as appropriate. To remove the Jungo driver, you should first change to the directory /opt/clearspeed/csx600_m512_le/drivers/jungo/ and execute the following command:

sh uninstall-jungo
To remove the CSX driver, you should first change to the directory /opt/clearspeed/csx600_m512_le/drivers/csx/ and execute the following command:

sh uninstall-csx

These steps will remove the init.d script and stop the driver from running. You can then remove the RPM in usual way.

Finally, after all RPMs have been uninstalled, you must delete the /opt/clearspeed directory to completely remove the installation.


[Note] Kernel Tainted Message

The installation of the driver causes a message of the following format to be printed to the kernel log file:

machine kernel: windrvr6: no version for "struct_module" found: kernel tainted.

This message is normal and is caused by the fact that the kernel module windrvr6 is not open source.


© Copyright ClearSpeed Technology plc 2006
Document number 06-UG-1328; revision: 1.36.1.8
5 September, 2006