Linux COMBO Driver
==================

Devices
-------

The devices for communication between user and kernel space can be
created using the following scripts:

combo6devices		# base combo6 devices, required
szedatadevices		# can be omitted if szedata drivers are not used
flowdevices		# can be omitted if flow drivers are not used

Using recent 2.6 kernels (since kernel 2.6.12) it might be wanted to
use the sysfs/udev mechanisms to create devices. Example udev rules
are in combo.udev.rules file. Copy this file to /etc/udev/rules.d
directory and modify it (change group or permissions).


Source compilation
------------------

Required tools: binutils, gcc, autoconf, make.
Other requirements: fully configured linux 2.6 kernel tree

The fully configured kernel source tree can be obtained in different ways
and it highly depends on the used Linux distribution. Please, refer to
the used Linux distribution documentation for help, how can be
external drivers compiled with the distribution specific Linux kernel.

It is recommended using these commands to compile the Linux combo driver:

From distributed .tar.bz2 package:

  ./configure
  make
  make modules_install

From Git:

  make clean
  ./gitcompile
  make modules_install

Optional parameters for the configure/gitcompile script:

    --with-kernel=dir 		kernel build directory [default is your current]
    --with-source=dir		kernel source dir [it's guessed from builddir]


Kernel modules
--------------

 libermemalloc		- module to keep PCI pages reserved for combo;
			  load this module only once at machine boot
 combo6core		- core for the combo6 drivers
 combo6			- core for the first generation of combo adapter
			  (with PLX bridge)
 combo6x		- core for the second generation of combo adapter
			  (with PCI IP bridge in FPGA)
 combov2		- core for the third generation of combo adapter
			  (with specific PCI express bridge)
 combov2-boot		- special driver for initial design booting
 spacev2		- special debugging driver for the 3rd generation cards
 szedata		- straight zero-copy data interface API
 szedata2		- straight zero-copy data interface API v. 2
 combo6-c6eth		- NICv1 driver
 combo6-c6eth2		- NICv2 driver
 combo6-c6lr1		- NIC Liberouter v1 driver (LIBEROUTER1_00_04+)
 combo6x-c6pcreth	- Universal NIC driver for second generation of
			  combo adapter
 szedatax-c6pcr		- Universal SZEDATA driver for second generation
			  of combo adapter
 szedata2-c6x		- second generation cards szedata2 driver
 szedata2-cv2		- third generation cards szedata2 driver
 netflow-ph1		- netflow PH1 driver
 szedata-sc6ph1		- scampi PH1 szedata based driver
 szedata-sc6ph2		- scampi PH2 szedata based driver
 
Example:
  The command 'modprobe szedata2-cv2' loads driver for the szedata2 based
  design used on the third generation cards. Sans szedata2, combov2 and combo6
  modules.

Module options
--------------
Use modinfo to see complete module parameter list of each module.
E.g. modinfo combo6 will list (along with other info) parameter ('parm')
entries of that module.


combo6 module options
---------------------

 enable			- int array: 1 = enable (default), 0 = disable
 invalidmemsize         - int array: 1 = load even if the PCI memory window
                                     is greater than 256MB (window is wrapped
                                     to 256MB)
 systimestamp           - int array: use do_gettimeofday for 64-bit timestamps
 bootprotect		- int array: 1 = enable (default), 0 = disable;
			             for debugging purposes only - allows
				     load design without ID component

combo6x module options
----------------------

 enable			- int array: 1 = enable (default), 0 = disable
 invalidmemsize         - int array: 1 = load even if the PCI memory window
                                     is greater than 256MB (window is wrapped
                                     to 256MB)
 bootprotect		- int array: 1 = enable (default), 0 = disable;
			             for debugging purposes only - allows
				     load design without ID component

szedata2 module options
-----------------------

 no_eth			- bool: 1/y/Y = disables ethernet support for szedata2
					devices
				0/n/N = leaves the eth support enabled (default)


Ethernet interface names
------------------------

The old (pre-combov2) NIC drivers uses 'c6ethXY' names where X is the card
number and Y is the interface number (both values starting at zero).

Example: c6eth00, c6eth21 etc.

ComboV2 dependent drivers use slightly different naming. The device name start
with ceth and is numbered starting at zero. E.g. ceth0, ceth1, etc.


Scampi PH drivers
-----------------

You can limit maximum size of received packet with the 'packet_size'
option. The size includes 32-byte header and link layer (MAC addresses).

Example: modprobe combo6-sc6ph1.o packet_size=548


For packagers
-------------

This sequence will generate combo-driver tar.bz2 package.

GITCOMPILE_NO_MAKE=1 ./gitcompile
make pkg
ls -la combo-driver-*


Debugging / testing hw
----------------------

Modules combo, combo6x and all cv2 based (such as szedata2-cv2) support
'usemode' module option. The number is bitmask and is defined as follows:
0x00000001 - Skip CPLD detection.
0x00000002 - Skip localbus use (do not read design version number after boot).
0x00000100 - Combo6[XE] - skip PCI BAR12 use
0x00000200 - Combo6[XE] - skip PCI bridge version (PCI FPGA firmware)
	     detection

Final remarks
-------------

Keep in mind that to make the driver work, loading a firmware (MCS file)
into the card is necessary :-)
