ClearSpeed Software Installation Instructions

For use with Linux operating systems

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

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: Download the software

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 csx600_2.23_base containing the components of the package.
3. Change to the directory containing the contents of the Base Package; for example, cd ~/csx600_2.23_base (note that the actual directory name may vary).
   
   The files in this directory have names of the form csx600_m512_le-<component>-<version>.<target>.rpm
   
   where:
   <component> is the software component, runtime, csxl, etc.
   <version> is the release version and the build version of this component, for example: 2.23-1.82.1.49
   <target> is the target architecture, for example: x86_64

Release notes and other documentation can be found in the docs subdirectory.

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.

Step 2: Install the runtime package

The drivers package is provided as an RPM file and is installed using the rpm command:

rpm -i csx600_m512_le-runtime-2.23-1.118.1.25.x86_64.rpm

Note that the filename may vary depending on the version.

This copies the runtime software to your machine. Next you need to install the appropriate kernel driver.

Step 2.1: 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 ClearSpeed drivers.

CSX kernel driver (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 kernel driver (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.

Install the diagnostics package using the rpm command:

rpm -i csx600_m512_le-board_diagnostics-2.23-1.108.1.38.x86_64.rpm 

Note that the filename may vary depending on the version.

Step 4: Install CSXL library, if required

The CSXL library provides acceleration for functions such as DGEMM. This can be installed using the rpm command:

rpm -i csx600_m512_le-csxl-2.23-1.82.1.49.x86_64.rpm 

Note that the filename may vary depending on the version.

See the CSXL User Guide in the docs directory of the installation for more information on how to use the CSXL library.

Step 5: Install FFT library, if required

The CSDFT library provides acceleration for FFT functions. This can be installed using the rpm command:

rpm -i csx600_m512_le-csfft-2.23-1.39.1.25.x86_64.rpm 

Note that the filename may vary depending on the version.

See the CSDFT Reference Manual in the docs directory of the installation for more information on how to use the CSDFT library.

Step 6: 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:

   cd /tmp

2. Use the shell script provided to set up the environment variables:

   source /opt/clearspeed/csx600_m512_le/bin/bashrc

3. Run the program:

   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:
   
   source /opt/clearspeed/csx600_m512_le/bin/bashrc
   
2. Reset the board:
   
   csreset -Av
   
3. Run the Mandelbrot demo:

   /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

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 should delete the /opt/clearspeed directory to completely remove the installation.

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

Copyright ClearSpeed Technology plc 2006
Document number 06-UG-1328; revision: 1.36.1.11