1.1   Obtaining pci-bridge package

Test package is available via WWW download page:

http://www.liberouter.org/clients

You can also check latest news at our web pages:

http://www.liberouter.org/

1.2   Package structure

The pci-bridge package contains Linux kernel drivers, all necessary libraries (libcombo, libcommlbr, libtap) and tools svf(1) and csid(1). The package also contains installation system and README file.

/firmware   - firmware for PCI bridge in current stable version 
              (pci_contr - 04_07, netcope - 05_0a)
/base       - source codes for software tools and drivers
   /mk                       - build system
   /sys_sw
      /drivers/linux     - Linux kernel drivers
      /hwtools/csid      - identification tool for COMBO card family
      /lib*              - libraries necessary for tools
      /svf               - tool for PCI bridge firmware upgrade
      /projects/pci-bridge
         /src            - pci-bridgelkm script
/firmware   - card firmware (mcs files)     
README      - this file
RELNOTES    - differences against previous release 

2.1   Host computer

The Combo hardware has been designed to work on any PC-AT compatible computer running GNU/Linux or other "Unix-like" operating system. It has been tested only on computers that use the x86 family of processors. The hardware requirements necessary to run the SVF tool are:

• Intel Pentium or equivalent x86 based PC
• COMBO6X - 64-bit/66 MHz PCI bus

The "sandwich" consisting of COMBO6X and an interface card COMBO-4SFPRO/COMBO-2XFP2 fits into one PCI slot.

2.2   Supported hardware

2.3   Supported software

Software and drivers works on GNU/Linux OS with 2.4 and 2.6 kernels. The software has been tested on computers running Red Hat Enterprise Linux.

2.4   Installing COMBO6X cards

After plugging Combo card into your PCI slot, you should test connection between the card and your PC. We use lspci(8) utility for this purpose. lspci(8) is a utility for displaying information about all PCI buses in the system and all devices connected to them. For correct recognition of the Combo card you need update PCI ID Database used by lspci(8) or download pciutils-2.2.2 (program collection containing lspci(8)) or later. If the lspci(8) output contains the following line, your COMBO6X card is connected properly.

$ lspci -d 18ec:
03:01.0 Ethernet controller: Cesnet, z.s.p.o. COMBO6X (rev 01)

2.5   Building package

Compilation and installation process is covered by the build system located in the /base/mk directory. For more details about required tools necessary to build package see base/mk/REQUIREMENTS file.

To build kernel drivers needed by svf you will need fully configured Linux kernel source tree. More installation and compilation details about kernel drivers are available in the README file inside base/sys_sw/drivers/linux directory.

pkgtool(1) helps to build, install and uninstall a distribution package.

$ tar -xzvf pci-bridge-XX.YY.ZZ.tgz
$ cd pci-bridge-XX.YY.ZZ/base
$ ./pkgtool --build

If this is the first Liberouter's package you have ever installed, you can define installation directory with the --prefix=path option. But remember that this installation path MUST not exists (e.g. /usr/local is invalid installation path on most systems because this directory exists). This restriction is due to new installation framework which enables easy package uninstall or package switching. More information about these features can be found in liberouterpkg section in this README.

The --prefix option takes effect only during building package. If no prefix is set then /usr/local/liberouter path is used.

$ ./pkgtool --build --prefix=/usr/local/pci-bridge

If you have previously installed some Liberouter's package (nific, nic, ids, flowmon with liberouterpkg mechanism), the installation path is detected automatically as path used for the first installed package.

Remember that installation path given as --prefix parameter will contain next subdirectories for binaries, libraries, man pages, etc. These directories can be affected by future uninstalling or package switching so it could be used as installation directory only for Liberouter's packages.

2.6   Installing package

All these steps require root privileges. The tools and kernel drivers will be installed to the installation directory (by default /usr/local/liberouter).

# ./pkgtool --install

After successful installation some post-installation steps are required:

1. Set PATH variable to point to the installed tools directory -> ${PREFIX}/bin and add it to ~/.bash_profile for loading at login

   $ echo "export PATH=$PATH:/usr/local/liberouter/bin" >> ~/.bash_profile
   

2. Set /etc/ld.so.conf to point to the library directory -> ${PREFIX}/lib

   create file liberouter.conf with content /usr/local/liberouter/lib (by default or with {PREFIX}/lib if you have used option --prefix during building process) in /etc/ld.so.conf.d directory:

   # echo "/usr/local/liberouter/lib" > /etc/ld.so.conf.d/liberouter.conf
   # ldconfig
   

3. Set /etc/man.config file to point to the Liberouter's man pages -> ${PREFIX}/man

Add MANPATH /usr/local/liberouter/man entry to the /etc/man.config file.

4. Load needed kernel modules using pci-bridgelkm tool:

   # pci-bridgelkm -l
   

   If you want to load kernel modules when the PC starts up, add following lines to the /etc/modules file.

   For COMBO6X card:

   combo6core
   combo6x
   

   NOTE:	In some distribution (Red Hat Enterprise Linux 4) you have to use file /etc/rc.modules in place of /etc/modules file. This file contains commands to load kernel modules at boot time (it is actually script so it must be executable file), so such file for COMBO6X card will look like this:

   #!/bin/sh
   /sbin/modprobe combo6core
   /sbin/modprobe combo6x
   

   Don't forget to set the /etc/rc.modules as executable:

   # chmod +x /etc/rc.modules 
   

5.1) The driver needs device files in the /dev/combosix/ directory. To

create them, run the combo6devices script in the base/sys_sw/drivers/linux directory in package tree:

# ./combo6devices

5.2) To run as a non-privileged user set r/w permissions on

/dev/combosix/0 device.

You have to change the permissions of the device file so that the non-privileged user that will execute the SVF tool has read-write access. For example, you can create a new group, say combo-rw, add that user to this group and change the file group ownership and permissions as follows:

# chgrp combo-rw /dev/combosix/0
# chmod 664 /dev/combosix/0

5.3) Using recent 2.6 kernels it might be wanted to use the sysfs/udev

mechanisms to create device files. For more details about udev see http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html

Example udev rules are placed in the package in sys_sw/drivers/linux/combo6.udev.rules file. If you didn't use option --udev during package installation, copy this file to /etc/udev/rules.d directory and modify it (change group or permissions). Following line will create combo6 device files required by the package:

KERNEL=="combosix[0-9]*",       NAME="combosix/%n",     GROUP="combo-rw"

NOTE:	Depending on your version of udevd you must adjust syntax of your udev rule file. Older versions of udevd require '=' character to match KERNEL key e.g. KERNEL="combosix[0-9]*". The newer one require '==' characters to match KERNEL key e.g. KERNEL=="combosix[0-9]*".

6. Please copy (and rewrite any previous version) liberouterpkg script, located in the package base directory into your standard binary directory (e.g. /usr/local/bin/). This enables using liberouterpkg script as standard system tool:

   # liberouterpkg
   

2.7   Upgrading package

This Liberouter package is using liberouterpkg tool enabling package switching and fully package uninstalling. If you have installed any previous Liberouter package without liberouterpkg, please remove it completely (including all libraries and drivers) to ensure proper behavior of the installed package.

More information about these features can be found in the in the liberouterpkg tool section at the end of this README.

If you are installing new version of previously installed package (e.g. you have installed pci-bridge-1.2.0 and now you are installing pci-bridge-1.2.0 package) you will be asked by pkgtool(1) to decide if you wish to keep your own (but may be obsolete) configuration files or to overwrite them with our default (but up-to-date) configuration files.

If you have used some previous version of this package, please follow all building and installing steps described above. Post-installation steps can be skipped if you performed these steps during previous installation (and an installation path was the same!).

2.8   Uninstalling package

Before package uninstalling please remove kernel modules needed by package software using the pci-bridgelkm tool:

# pci-bridgelkm -r

This Liberouter package is using liberouterpkg tool enabling package switching and fully package uninstalling.

More information about these features can be found in the in the liberouterpkg tool section at the end of this README.

3.1   Requirements on jumper settings

Both upgrade options require these jumper settings on COMBO6X board for correct functionality:

jumper  J1 - short
jumpers J0, J2, J3 - open 

3.2   Important connectors and jumpers on COMBO6X card

Connectors JP4 and JP7 are in parallel connection. They share the JTAG signals TDO, TDI, TMS, TCK and TMSP.

+---------------------------------------------------+
| COMBO6X board                  JP5                |
|                                +-+                |
|                                | |                |
|                       J0-3     | |                |
|                       |||||    | |                |
|                  JP4           | |    JP7         |
|                  +-------+     +-+    +----+      |
|                  +-------+            +----+      |
+---+                    +--------------------------+
    |     PCI (64/66)    |
    +--------------------+

4.1   SVF tool

SVF tool is a part of all Liberouter installation packages. It is used for programming PROMs which store configuration of Xilinx FPGA's on COMBO6X cards. The programming data is read from Xilinx SVF file generated by Xilinx iMPACT Software.

Program is indeed a file parser and interpreter. It uses the libtap library to communicate with TAP controller in JTAG compliant devices. SVF file contains commands which specify the programming sequence and also the data, which should be shifted into the JTAG device.

SVF program has one necessary parameter - the input file. All other parameters are optional. The default device with TAP connector is COMBO6X device /dev/combosix/0. The program needs also access to devices in /dev directory. This may require root privileges.

Examples of usage

% cd /usr/local/mcs/chips/combo6x/pci_contr/04_07
  .. change to this directory before you use examples below

% svf -f combo6x.svf   
  .. upgrade firmware with Liberouter's shortcut cable on card /dev/combosix/0

% svf -d /dev/combosix/1 -f combo6x.svf   
  .. upgrade firmware with Liberouter's shortcut cable on card /dev/combosix/0

The programming may take several minutes to finish. The tool shows a progress bar for information about the programming progress. Don't kill the tool while programming is in progress. The PCI bridge firmware must be correct otherwise the card won't be detected by the computer at next start (no COMBO card in lspci listing).

4.2   Post installation steps

It is necessary to shutdown and power on the machine after the upgrade of the PCI bridge firmware (reboot is not enough). As root run the following command:

# shutdown -h now

WARNING: If you are using remote power control and access to your computer please use the command below.:

# halt

4.3   What to do when the card "dies" after corrupted programming

If the programming using Liberouter's shortcut cable failed and you restarted your workstation your COMBO6X card is not detected by the system. You can't use SVF tool, because it uses the card for access to the programming chip. You have two possibilities to enable your card:

1. Program the PCI bridge firmware using Xilinx JTAG cable and Xilinx ISE (see the next section).
2. Build a custom LPT cable (Xilinx DCL5 Type3) and use SVF tool

For more information about construction of a Xilinx DCL5 Type3 cable see

The cable should be connected to the board according to this scheme:

Xilinx DCL5 Type3                             JP4
     +---+                                   +---+
     |    \                                  | : |
     |     ----- TMS ------------------TMSP--- 7 |
     |     ----- TCK ------------------------- 8 |
     |     ----- TDI ------------------------- 9 |
     |     ----- TDO ------------------------- 10|
     |     ----- GND ------------------------- 12|
     |    /                                  | : |
     +---+                                   +---+

Then use SVF tool with the parallel port connected to COMBO6X board (/dev/parport/0 - LPT1 0x378; /dev/parport/1 - LPT2 0x278):

# svf -d /dev/parport/0 -f combo6x.svf -v

After the programming shutdown and restart the computer and the card should be detected.

5.1   Connecting Xilinx JTAG cable to COMBO6X board

The JTAG signals are available at connector JP7. The signals consist of TMSP, TCK, TDI and TDO pins. To these pins attach the Xilinx programming cable. For connection a "High-Performance Ribbon Cable" (with 14pin connector at both sides) or a "Flying Wire Adapter" can be used.

5.2   Upgrading firmware using Xilinx ISE

1. Start Xilinx
2. Select Accessories -> Impact
3. Discard project chooser
4. Choose Boundary-scan mode
5. Choose File -> Initialize Chain

The software should now auto-detect all available chips on the JTAG chain. For programming options use right click on desired chips (xc18v04 and xc18v512):

5. Choose Assign New Configuration - select MCS file according to the selected chip
6. Choose Program - program assigned configuration to the chip

5.3   Post installation steps

It is necessary to shutdown and power on the machine after the upgrade of the PCI bridge firmware (reboot is not enough). As root run the following command:

# shutdown -h now

6.1   List Of Installed Packages

liberouterpkg can be used to display list of all installed Liberouter's packages

# liberouterpkg --list
# Installed packages:
pci-bridge-1.2.0

or to display currently active package (only one package can be active at the same time)

# liberouterpkg
pci-bridge-1.2.0

6.2   Uninstalling Package

liberouterpkg tool is able to safely uninstall any previously installed Liberouter's package (covered by new Liberouter's package installation framework with liberouterpkg) by --uninstall=<PKG_ID> option where <PKG_ID> is a package identification string (that can be displayed by --list option)

# liberouterpkg --uninstall=pci-bridge-1.2.0

6.3   Switching Packages

If you are using a pci-bridge package (pci-bridge-x.y.z package is active) you are unable to use tools from e.g. ids package. Using liberouterpkg script you can switch to any installed package and change this way currently active package. For switching packages use --switch=<PKG_ID> option where <PKG_ID> is a package identification string of a package that will be activated. List of available packages can be displayed by --list option)

# liberouterpkg --switch=pci-bridge-1.2.0

7.1   Mailing lists

For any questions or general technical support issues, please send mail to the combo6@liberouter.org general mailing list.

7.2   Submitting problem reports

Suggestions, bug reports and contributions of code are always valued. Please do not hesitate to report any problems you may find. Bug reports with attached fixes are of course even more welcome. You can use our mailing list to report bugs or (preferably) our bug tracking system at http://www.liberouter.org/bugtrack/

7.3   Other COMBO6 based projects

Check our web pages for information about other projects, e.g. HW accelerated flow exporter or intrusion detection system.

http://www.liberouter.org/