------------------------------------------------------------------------------
VERSION 2.3.9                                                     
------------------------------------------------------------------------------

Overview
--------

The VxWorks driver for the ZNYX NetBlaster PCI and CompactPCI network 
interface cards is written for use with SENS 1.1, and conforms
to the Wind River requirements for an Enhanced Network Driver (END). The 
driver includes embedded RAINlink technology. RAINlink provides critical 
link services such as link aggregation, link failover, and dynamic load 
balancing over multiple network ports. These ports can be a group of 
single-channel or multi-channel ZNYX adapter ports, up to a maximum 
of 32 ports. 

The VxWorks driver consists of an object file and configuration source
code and header files. The installation consists of placing files in
the correct build directories, and tailoring the build environment to
include the ZNYX driver in the VxWorks image.

These instructions install the ZNYX network driver and bring up four
individual ports without RAINlink features enabled. Examples are included 
to bring up the most common RAINlink configurations for four ports:
A system-to-system trunk, a Fast EtherChannel system-to-switch trunk, 
and a failover group.
----------------------------------
Installation for X86 (VxWorks 5.4)
----------------------------------

INSTALLATION:

1. Copy the following files into the $(WIND_BASE)/target/config/pcPentium
   (or pc486, or pcPentiumpro) directory

		if_zxe.obj		/* driver obj file */
		zxe_apps.obj	/* ZNYX application object file */

		if_zxePci.c		/* Znyx PCI Library */
		if_zxePci.h

		if_zxeRlk.c		/* Znyx RAINLink configuration */
		if_zxeRlk.h

		configZxe.c		/* Znyx startup routines(optional) */
		configZxe.h

2. Change to the $(WIND_BASE)/target/config/$(BSP) directory.
   Edit the Makefile, add "if_zxe.obj", "configZxe.o", "zxe_apps.obj" and "if_zxeRlk.o"

   The list should look similar to the following when you are finished:
	MACH_EXTRA = sysSpeed.o if_zxe.obj configZxe.o if_zxeRlk.o zxe_apps.obj

   If there are already other files in MACH_EXTRA, please leave them in.

3.  Edit $(WIND_BASE)/target/config/$(BSP)/config.h in the following way:

A.  After #define INCLUDE_END in the network driver options
	    area, add 

#ifndef IP_MAX_UNITS
#define IP_MAX_UNITS 16 /* NOTE: This overrides the setting in configNet.h
				   Adjust for your specific configuration */
#endif
		#define INCLUDE_ZXE
		#define STANDALONE_NET

		(the following are optional)

		#define INCLUDE_NET_SHOW
		#define INCLUDE_PING
		#define INCLUDE_TELNET
		#define INCLUDE_SHOW_ROUTINES /* Pentium Pro BSP only */

4
A.  In $(WIND_BASE)/target/config/$(BSP)/syslib.c, add the folowing includes.

    .
    .
    .
#include "sysNetif.c"		/* network driver support */
[add above only if it does not exist in your BSP version]

#ifdef	INCLUDE_ZXE

#define ZXE_INIT_STATE_MASK     (VM_STATE_MASK_VALID |                  \
                                 VM_STATE_MASK_WRITABLE |               \
                                 VM_STATE_MASK_CACHEABLE)
#define ZXE_INIT_STATE          (VM_STATE_VALID | VM_STATE_WRITABLE |   \
                                 VM_STATE_CACHEABLE_NOT)
#include "if_zxePci.c"

#endif


   and add the following to the initialization...

    .
    .
    .
    sys557PciInit ();
#endif	/* INCLUDE_FEI */

#ifdef	INCLUDE_ZXE
    zxePciInit ();
#endif	/* INCLUDE_ZXE */
    .
    .
    .

B.  At the end of sysHwInit2, add...

#ifdef	INCLUDE_ZXE
    zxePciInit2 ();
#endif	/* INCLUDE_ZXE */

C.  Ensure that there is at least one DUMMY_MMU_ENTRY for each port
     in the sysPhysMemDesc[] structure of sysLib.c.  If there are 
     not enough DUMMY_MMU_ENTRYs memory corruption and/or page faults
     will occur.

D.  Add #include "configZxe.h" to configNet.h. 

5.  Rebuild the vxWorks.st file.
    In the $(WIND_BASE)/target/config/$(BSP) directory execute:
		make vxWorks.st 
    This command is case sensitive.

Initializing the driver
-----------------------

A routine called zxeUp is provided in configZxe.c that activates either RAINlink or non-RAINlink ports.  It can also be used as an example for the creation of your own initialization routines.  For an example, to bring up the first two indivdual ports, use:

zxeUp "znb0", "10.0.0.1", 0xff000000, 0, 0
zxeUp "znb1", "11.0.0.1", 0xff000000, 0, 1

Or for a two-port system-to-system RAINlink trunk, use:

zxeUp "zrl0", "10.0.0.1", 0xff000000, 0, 3

The first parameter is the device name (znb for an individual port, zrl for a RAINlink port), the second is the IP address, third is the netmask, fourth is the media type (0 = autonegotiate), and the last is the physical port or RAINlink configuration type as set up in if_zxeRlk.c.

One way to have ports activated when vxWorks loads is to call zxeUp in the usrRoot() task in $(WIND_BASE)/target/config/all/usrConfig.c.

More information on zxeUp is contained later in this document.

Configuring RAINlink for VxWorks
--------------------------------

RAINlink features are statically added into your VxWorks image at compile time. 
The RAIN management configuration table in if_zxeRlk.c contains the available 
RAINlink configurations. ZNYX provides six standard configurations for basic 
two-port and four-port trunking and failover groups. The table below shows the 
provided RAINlink configurations, the name of the table entry, 
and the corresponding index number:

   Configuration				Name		Index 
   -------------                                ----    	-----
   System-to-System trunking between 4 ports	zxe_rlss4	  0
   Fast EtherChannel trunking between 4 ports	zxe_rlfe4	  1
   Fast Failover between 4 ports		zxe_rlff4	  2
   System-to-System trunking between 2 ports	zxe_rlss2	  3
   Fast EtherChannel trunking between 2 ports	zxe_rlfe2	  4
   Fast Failover between 2 ports		zxe_rlff2	  5

Standard single port ZNYX devices have the name znb. RAINlink-configured
devices have the name zrl. To use one of the provided configurations, create
an END table entry for the RAINlink configuration you wish to load, and 
then load the driver. Examine configZxe.c and implement the method that 
best fits your applications needs to bring up the network interfaces. 
Reference usrNetwork.c, and bootConfig.c for routines to bring up the
interface. A typical entry looks like:

   { 0, ZRL_LOAD_FUNC, "0:0:0:0:0:0:0", ZXE_BUFF_LOAN, NULL, FALSE },

The number at the beginning of the line specifies the unit number for the
device. The unit number in the line above is 0, therefore the device name it
loads is zrl0. ZRL_LOAD_FUNC is the name of the load function for a
RAINlink device.  Load functions for znb and zrl devices are:

   #define	ZNB_LOAD_FUNC	znbEndLoad	/* driver external interface */
   #define	ZRL_LOAD_FUNC	zrlEndLoad	/* driver external interface */


The next element is the init string, which contains all the device-specific 
parameters. For zrl devices, the first field of the init string is the 
RAINlink configuration table index  (zxe_rlk_config_tbl[] in if_zxeRlk.c). 
For znb devices, the first field refers to the ppa of that device. 
The init string format consists of:

   ppa|index:memBase:mediaType:mtu:recvBufs:xmitBufs:staticBufs:flags
  
   where:
  
    <ppa|index> 	specifies the ppa or configuration record to use.
    <memBase> 		defines main memory base as seen from PCI bus.
    <mediaType> 	defines the media type of the device.
    <recvBufs> 		defines the number of receive buffers per ppa
    <xmitBufs> 		defines the number of transmit buffers per ppa
    <staticBufs> 	defines the number of static buffers per ppa
    <flags> 		defines various interface flags.

The next element in the table entry defines buffer loaning:

   #define	ZXE_BUFF_LOAN	1		/* enable buffer loaning */

The last two elements are a NULL reserved for the BSP, and a TRUE/FALSE
indicator of whether or not the load request for that device has been
processed.

For example, an END table entry for a zrl device such as a 4-port 
Fast EtherChannel, Layer 3 trunk, would be the following:

   { 0, ZRL_LOAD_FUNC, "1:0:0:0:0:0:0", ZXE_BUFF_LOAN, NULL, FALSE },

If you wish to customize configuration for trunks for other than two or 
four ports, or disable the dynamic load balancing, go to the "Advanced Trunking" 
section. If you wish to configure failover groups for other than two or four 
ports, or set timeout parameters, then go to the "Advanced Failover" section. 
You can also configure failover groups of trunks themselves. Always configure 
trunks before failover groups.



Advanced Trunking
-----------------

To add a new trunk configuration, edit the file if_zxeRlk.c and add an 
entry for the trunk. Each entry corresponds to one device and contains the
RLK_TRUNK type, the desired mode, a 0 for the timeout field, and -1 terminated
list of ports to be included in that trunk. Acceptable modes for trunks are:

   Mode				Appropriate for
   ----                         ---------------
   IP_TRUNKING_MODE		System-to-system trunking.
   LAYER_2_MODE			System-to-switch trunking.
   LAYER_3_MODE			System-to-switch trunking.
   NO_BALANCE_MODE		Option. OR with LAYER_2 or LAYER_3.


For system-to-system trunking, use IP_TRUNKING_MODE. Both systems should be setup 
identically. In IP_TRUNKING_MODE, packets are sent to the driver as large 
datagrams and fragmented across the active links. 

For system-to-switch trunking, the default method of load balancing scheme 
uses Layer 3 Protocols. Layer 3 mode balances traffic across the available
ports based on IP addresses, as opposed to Layer 2, which is based on MAC
addresses. If you wish to use only Layer 2 protocols for load balancing, change 
the second element to LAYER_2_MODE.

For system-to-switch trunking, you can disable dynamic load balancing, which
is on by default. Dynamic load balancing periodically tries to balance the 
load across the available members of the trunk, and is normally left enabled. 
Disable it by performing a logical OR of NO_BALANCE_MODE and either 
LAYER_2_MODE or LAYER_3_MODE in the mode field.

You can use any available ports in any order. Port entries should not be 
duplicated in trunks. A trunk must consist of at least two ports, and cannot 
contain other trunks. You can have more than one trunk. Each trunk will have 
its own entry in the device table. For example, to configure two 
system-to-switch trunks of four ports each, use layer 3 mode, and disable dynamic
load balancing, you would add two table element definitions in if_zxeRlk.c:

   /*
    *  Two 4-Port Fast EtherChannel Trunks, layer 3 mode with 
    *  balance mode disabled.
    */
   zxe_rlk_ppa_list_t zxe_rlfe4a[] = {
      { RLK_TRUNK, LAYER_3_MODE | NO_BALANCE_MODE, 0,
      { 0, 1, 2, 3, -1 } },
      { 0, }
   };
   zxe_rlk_ppa_list_t zxe_rlfe4b[] = {
      { RLK_TRUNK, LAYER_3_MODE | NO_BALANCE_MODE, 0,
      { 4, 5, 6, 7, -1 } },
      { 0, }
   };

You would also need to add the entries to the zxe_rlk_config_tbl[] in if_zxeRlk.c:

   zxe_rlk_ppa_list_t *zxe_rlk_config_tbl[] = {
      zxe_rlss4,		/* 0 */
      zxe_rlfe4,		/* 1 */
      zxe_rlff4,		/* 2 */
      zxe_rlss2,		/* 3 */
      zxe_rlfe2,		/* 4 */
      zxe_rlff2,		/* 5 */
      zxe_rlfe4a, 		/* 6 new first trunk  */
      zxe_rlfe4b,		/* 7 new second trunk */
      0
   };

Add two END table entries for zrl0 and zrl1, and bring up the network
interfaces. 

Examine configZxe.c and implement the method that 
best fits your applications needs to bring up the network interfaces. 


Advanced Failover
-----------------

You can create link failover groups, assign ports and trunks to these 
groups and select a modes of failover. Failover groups are configured 
in the same manner as trunks: Edit the if_zxeRlk.c  file and 
rebuild the kernel. 

Acceptable modes for failover groups are:

   Mode			Appropriate for
   ----                    ---------------
   timeout_mode <time>	Failover mode; time parameter in milliseconds
   hub_mode			Only recieves packets on the active port, for use when connecting multiple
				ports to the same colision domain (i.e. a hub)

Failover groups can contain individual ports, trunks, or both ports and trunks. 
Always configure trunks before failover groups. Add an entry for each failover 
group containing the list of ports and trunks to be included in that group. 
The default mode of failover is fast failover. In this mode, RAINlink moves 
the traffic over to a redundant stand-by link in case of a link failure in as 
little as 500 milliseconds.

In addition to fast failover, timeout mode can be enabled for a failover 
group. By enabling timeout mode, if no traffic is received within the specified 
time interval, the active port is automatically switched to another available 
link. You can choose different failover modes for different groups. You can 
also specify different timeout intervals. To build a failover group of two 
trunks, first build the trunks, then the failover group and set the timeout 
mode on with a value of 30 seconds:

   /*
    * 2-Port Failover of 2 2-Port Trunks, timeout=30 seconds
    */
   zxe_rlk_ppa_list_t zxe_rlff2ss2[] = {
      { RLK_TRUNK, IP_TRUNKING_MODE, 0, { 0, 1, -1 } },
      { RLK_TRUNK, IP_TRUNKING_MODE, 0, { 2, 3, -1 } },
      { RLK_FAILOVER, TIMEOUT_MODE, 30000, { 0, 2, -1 } },
      { 0, }
   };

This results in one RAINlink device. You would also need to add the entries to the 
zxe_rlk_config_tbl[] in if_zxeRlk.c:

   zxe_rlk_ppa_list_t *zxe_rlk_config_tbl[] = {
      zxe_rlss4,		/* 0 */
      zxe_rlfe4,		/* 1 */
      zxe_rlff4,		/* 2 */
      zxe_rlss2,		/* 3 */
      zxe_rlfe2,		/* 4 */
      zxe_rlff2,		/* 5 */
      zxe_rlff2ss2, 		/* 6 new failover */
      0
   };

Add an END table entry for zrl0, and bring up the network
interface. 

Examine configZxe.c and implement the method that 
best fits your applications needs to bring up the network 
interfaces. 




RAINlink for VxWorks Utilities and Sample Routines
--------------------------------------------------

This section includes Unix-style man pages to be used as reference for the 
functions included in configZxe.c and zxe_apps.obj.


NAME

   zxeUp( ) Initializes the driver and the device.

SYNOPSIS

   int zxeUp(
      char *devString, 		/* device to initialize, e.g.  */
				/* "znb0", "zrl1" */
      char *pAddr, 		/* IP address of the interface */ 
      ULONG iMask, 		/* IP netmask of the interface */ 
      int mediaType, 		/* media type,  0-7 */
      int ppa|index		/* (non-RAINlink) physical port # to use */	
				/* (or RAINlink) Specifies the configuration */
	  			/* index to use for RAINlink */
      ) 

DESCRIPTION

   This routine initializes the driver and the device to the operational state.

   The following device strings are acceptable:

   znbn 				/* NetBlaster device  n=0-31*/
   zrln 				/* RAINlink device  n=0-31*/

   The following media types are defined:

   MEDIA_AUTO		0	/* auto negotiation */ 
   MEDIA_TP		1	/* 10 Mbit  - half duplex */
   MEDIA_BNC		2	/* not supported */
   MEDIA_AUI		3	/* not supported */
   MEDIA_TPFD		4	/* 10 Mbit  - full duplex */
   MEDIA_TX		5	/* 100 Mbit - half duplex */
   MEDIA_TXFD		6	/* 100 Mbit - full duplex */
   MEDIA_T4		7	/* not supported */

RETURNS

   OK or ERROR



NAME
   
   znbEndLoad, zrlEndLoad - initialize the driver and device

SYNOPSIS

   END_OBJ * znbEndLoad ( 
     char *initString, 		/* device specific parameters */
     void *pBsp 		/* not used by the driver */
     )
   END_OBJ * zrlEndLoad ( 
     char *initString, 		/* device specific parameters */
     void *pBsp 		/* not used by the driver */
     )
DESCRIPTION

   Initializes the driver and the device to the operational state.  All of the 
   device specific parameters are passed in the initString. The void pointer 
   parameter is currently not used by the driver.

      initstring format:
  
      unit:ppa|index:memBase:mediaType:recvBufs:xmitBufs:staticBufs:flags
  
      unit 		- The device unit to initialize  
      ppa|index 	- The ppa or configuration record to use.
      memBase 		- Main memory base as seen from PCI bus.  
      mediaType 	- Media type of the device.
      recvBufs 		- The number of receive buffers per ppa
      xmitBufs		- The number of transmit buffers per ppa
      staticBufs 	- The number of static buffers per ppa
      flags 		- Defines various interface flags.

   The following mediaTypes are defined:

      MEDIA_AUTO	0	/* auto negotiation */ 
      MEDIA_TP		1	/* 10 Mbit  - half duplex */
      MEDIA_BNC		2	/* not supported */
      MEDIA_AUI		3	/* not supported */
      MEDIA_TPFD	4	/* 10 Mbit  - full duplex */
      MEDIA_TX		5	/* 100 Mbit - half duplex */
      MEDIA_TXFD	6	/* 100 Mbit - full duplex */
      MEDIA_T4		7	/* not supported */

   The following flags are defined:

      END_NOCOPY_ON_TRANSMIT 	0x100

RETURNS

   An END object pointer or NULL on error.



NAME

   zxeVersion ( )  returns the version of the znb driver

SYNOPSIS

   int zxeVersion ( )

DESCRIPTION

   Returns the version of the znb driver

RETURNS

   OK or ERROR



NAME

   rlConfigShow  Displays current RAINlink configuration

SYNOPSIS

   int rlConfigShow( )

DESCRIPTION

   This routine displays the current RAINlink configuration

RETURNS

   OK or ERROR



NAME

   zxePortShow  Displays current port statistics

SYNOPSIS

   int zxePortShow(int port)  /* port == device unit */

DESCRIPTION

   This routine displays the current status for the designated port.

   port refers to the specific hardware port, not to a zrl|znb unit.

RETURNS

   Prints port statistics to console.

   OK or ERROR


NAME

   zxeDown( ) - Stop and unload an instance of the driver.

SYNOPSIS

   int zxeDown(
     int unit		/* device unit */
     )

DESCRIPTION

   This routine brings down an interface and stops and unloads the driver 
   and device for that interface.

RETURNS

   OK or ERROR

NAME

   zxeAllMultiSet( ) - Set Promiscuous Multicast on selected unit

SYNOPSIS

   int zxeAllMultiSet(
	char *name	/* device name */
   )

DESCRIPTION

   This routine sets promiscuous multicast on the selected unit.  String
format is "znb(x)" or "zrl(x)" e.g. "znb1", "zrl12", etc.  Strict string 
checking is performed against the name parameter. 

RETURNS

   0 on success, -1 on problem.  Problems are printed on the console.
 
NAME

   zxeAllMultiClear( ) - Clears Promiscuous Multicast on selected unit

SYNOPSIS

   int zxeAllMultiClear(
	char *name	/* device name */
   )

DESCRIPTION

   This routine clears promiscuous multicast on the selected unit.  String
format is "znb(x)" or "zrl(x)" e.g. "znb1", "zrl12", etc.  Strict string 
checking is performed against the name parameter. 

RETURNS

   0 on success, -1 on problem.  Problems are printed on the console.

Contact Information
-------------------

Telephone	(510) 249-0800
Toll-Free	(800) 724-0911 (USA Only)
FAX		(510) 656-2460
Website		www.znyx.com
E-mail		support@znyx.com
 

