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.

Before you install

Please note that this is Beta software. Before you install, please check the release notes for any changes or limitations in this release.
You must uninstall any previous version of this software before installing this release; see the uninstall instructions below.

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

Download the Base Package tarball from the ClearSpeed support site support.clearspeed.com/downloads/.
Unpack the contents of the Base Package. This will create a directory called something similar to csx600_2.xx_base containing the components of the package.
Change to the directory containing the contents of the Base Package; for example, cd ~/csx600_2.xx_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.50-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.xx-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 must 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. See Installing kernel sources for details.

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]

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-<version>.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-<version>.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-<version>.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.

Note: Installing all components

If you wish to install all the components in the Base Package then you can use the command:

rpm -i *.rpm

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:

Go to a directory where you have write privileges; for example:
```
cd /tmp
```
Use the shell script provided to set up the environment variables:
```
source /opt/clearspeed/csx600_m512_le/bin/bashrc
```

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 ClearSpeed support via the support web site.

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:

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

source /opt/clearspeed/csx600_m512_le/bin/bashrc
Reset the board:

csreset -Av

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).

Installing kernel sources

The installation of the kernel driver requires that the kernel source files be installed. By default, most Linux distributions do not install these kernel sources and sobefore installing the kernel driver these sources must be installed.

How the source packages are obtained depends on the Linux distribution being used and varies with releases of these distributions. The guidelines that follow are believed to be correct with the distributions currently available but the reader should be aware that the area of updates tends to be subject to change and development.

Generally, sources are available as RPM packages which are obtained and installed like any other package, however, it is vital that the sources which match the kernel distribution are installed. The running kernel version number can be obtained via uname(1).

1. Red Hat

Generally these distributions do not bundle the kernel sources with the distribution. The simplest way to get the kernel sources is to use yum to install online. (yum, YellowDog Updater Modified, is an installer tool based on the standard RPM mechanisms.) You need to get the sources that match the running kernel.

To determine the running kernel do:

 uname -a

From the name of the kernel generate the yum command as follows:

 yum install kernel-devel-xxxxxx

where xxxxx is the version number reported by uname.

2. SUSE

Currently the kernel source package is called kernel-sources but this may change.

With SUSE, there are two tools provided to make RPM installation easier. YAST is the preferred method. Using YAST, the kernel source package can be found via an online update and installed.

The other tool available with SUSE is rug (Red-Carpet) which is a command line updater.

Using rug, the current kernel source tree can be obtained via the command:

 rug install kernel-source

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

Note: if you are not sure which kernel driver is installed on your system, you can safely run both uninstall scripts.

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.

[Note] Kernel Tainted Message

The installation of the Jungo 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.