FarSync Drivers

FarSync Configuration

About Configuration

The FarSync WAN and OEM drivers create network interfaces which can be configured in a number of ways:

Note that all configuration commands require root privileges.  This section explains about the Network devices created by the drivers and how to configure their operational and network parameters.

Device Names

The WAN and OEM driver create devices as follows:

OEM Driver Wan Driver

Each card has one, two or four network interfaces associated with it, one for each line. These interfaces are labelled "syncX" where X is 0, 1, 2... etc

For example if three cards are installed in a system with a 1 port card in the lowest numbered PCI slot, a 2 port card in the next numbered PCI slot and a 4 port card in a higher numbered slot, then the interface names would be:  

sync0 -- The only port on the one port card
sync1 -- First port (A) on two port card
sync2 -- Second port (B) on two port card
sync3 -- First port (A) on four port card
sync4 -- Second port (B) on four port card
sync5 -- Third port (C) on four port card
sync6 -- Fourth port (D) on four port card

These configuration files closely parallel the configuration files for other network devices. You will probably already have "ifcfg-eth0" and "ifcfg-lo" in the same directory for Ethernet and local loop back devices.

Each card has one, two or four network interfaces associated with it, one for each line. These interfaces are labelled "hdlcX" where X is 0, 1, 2... etc

For example if three cards are installed in a system with a 1 port card in the lowest numbered PCI slot, a 2 port card in the next numbered PCI slot and a 4 port card in a higher numbered slot, then the interface names would be:

hdlc0 -- The only port on the one port card
hdlc1 -- First port (A) on two port card
hdlc2 -- Second port (B) on two port card
hdlc3 -- First port (A) on four port card
hdlc4 -- Second port (B) on four port card
hdlc5 -- Third port (C) on four port card
hdlc6 -- Fourth port (D) on four port card

A configuration file will need to be created for each port that you wish to use. If using the Red Hat System described below, some template files (ifcfg-hdlc0 and ifcfg-hdlc1) will have been provided for you when the install command was run.

When there are FarSync PCI and Flex devices present in the same system, the Flex USB devices will be created after the PCI devices.

Configuration

There are two parts to the device configuration, that is the physical line parameters, which are FarSite specific, and the general Networking (IP) parameters.  If the Protocol running over the port is Frame Relay, then there are also specific Frame Relay and PVC parameters to configure as well.

The physical parameters specify the physical line type, the clock source and the low level protocol to be run over the port (e.g. PPP, CISCO or Frame Relay etc).  The setting of all of these parameters are FarSite specific and can be verified with the farutil command.

The Networking parameters specify the local IP address, the IP address of the Point-to-Point connection and the MTU size.  These parameters are Linux Networking parameters and can be verified with the ifconfig command.

For the WAN driver the configuration is best made through the configuration file.  For the OEM driver it is expected that the application will set the required port parameters explicitly, but a config file could be used if required.  Please note that some features, e.g. setting bit order or HDLC or transparent mode, are only available through a programmatic interface.

Configuration File Format

During the installation process some configuration files will have been copied to the configuration directory.  You can use these files as a template.  The configuration parameters for each network device are contained in a separate configuration file called

/etc/sysconfig/network-scripts/ifcfg-hdlcX for the WAN driver

or

/etc/sysconfig/network-scripts/ifcfg-syncX for the OEM driver

where X is is the port number e.g. 0, 1, 2 etc.  These config files can be edited with a standard text editor, but do not use a word-processor which reformats the lines on includes and non-text markers.

These configuration files closely parallel the configuration files for other network devices. You will probably already have "ifcfg-eth0" and "ifcfg-lo" in the same directory for Ethernet and local loop back devices.

Parameters are set (one per line) simply by saying:

PARAMETER = value

Lines that begin with a # are comments and are ignored. You can use this facility to make notes and reminders for yourself and others.

Please Note: The parameter name IS case sensitive.

The configuration parameters are described in detail in the next section.

Activating and deactivating Ports

Once the port configuration file has been created then the interface can be activated (brought up) with an ifup (for RedHat type systems) or farifup (for Debian type systems).  Similarly they can be deactivated (set down) with an ifdown/farifdown command  as follows:

ifup hdlc0 or ifdown hdlc0

or

ifup sync0 of ifdown sync0

The ifup/farifup command has the effect of reading the configuration files and building a farutil command followed by an ifconfig comand to configure the interface and set it up.

Farutil configuration Parameters

The following tables describe the parameters that can be used with a farutil command or appear in a configuration file (e.g. ifcfg-hdlc0 or ifcfg-sync0).  Example configuration files were installed when the driver was installed.  In general, you should just need to modify these files in order to start using your FarSync network interface.

General Parameters

Parameter Typical value Meaning
MEDIA X21 This parameter selects the hardware interface used. Possible settings are:
x21   -  X.21 (V.11 or RS422)
x21d  -  X.21 as above but with the Indicate signal used as an extra clock line
         (see notes about dual clocking below)
v24   - V.24 (aka good old RS232C)
v35   - V.35
rs449 - RS449/530
rs530 - RS449/530 
e1    - E1 (G703/G704)
t1    - T1 (G703/G704)
rs485 - Only available on FarSync Flex
PROTO ppp for the hdlc driver
raw for the oem driver
Protocol to use on the link. Possible settings are:
ppp      - Synchronous Point-to-Point Protocol.
cisco    - Cisco-HDLC.
hdlc    - Raw IP
hdlc_eth  Raw ethernet 
fr      - IP over Frame Relay PVC's
X25     - X.25 over LapB

raw      - Send and receive raw HDLC frames.
For the OEM driver, you can set this to raw from your application.
CLOCK 64000 The line speed to use. If set then the port will generate clocks (acting like a DCE). Alternatively use the value "ext" to select the external clocks and run at the line speed determined by the remote end.
Possible clock speeds are listed here and depend on the card type.
V.24 (RS232) interfaces are limited to a maximum speed of 128000.
For T4E, clock speeds can be configured as low as 300 and there are a great many speeds in-between.
PHASE normal The required phase of the receive clock with respect to the data. The valid values are normal meaning no change or inverted meaning invert the clock.
LINEMODE hdlc The line discipline to be used on this port.  Possible settings are:
hdlc        - use synchronous hdlc framing
async       - use asynchronous framing
transparent - use synchronous bit stream
EXTENDED erx_itx This parameter is only valid for the T4E/T4E+ and Flex devices.  It allows more flexible clocking arrangements to be configured.  The values currently defined for this parameter are as follows:
erx_etx - set external rx and external tx clocks
erx_itx - set external rx and internal tx clocks
irx_etx - set internal rx and external rx clocks
irx_itx - set internal rx and internal tx clocks.
none    - disable extended clocking modes.
LED   This parameter tests the LED operation for the device.  It can help indentify which port is on which card when you have a multi card installation.  This is probably not a very useful parameter to have in a configuration file.  One would expect it to be used for diagnostic purposes with an interactive farutil command. The values for this parameter are:
flash  - make the leds flash on the card
normal - restore the leds to their normal state.
CARRIER required  The default mode of operation of the driver is to ignore transmit requests unless the modem signals are present, i.e. there is a carrier.  This parameter allows this condition to be ignored and to transmit regardless.  The parameter values are:
ignore - allow transmit at all times
required - only allow transit when modem signals are present (e.g. Indicate on X.21).
NUMBUFFERS 8 Each port is allocated a number of receive and transmit buffers on the device.  The number of buffers can be configured.  This parameter will configure the number of tx and rx buffers to the number supplied as the parameter value.
Valid values are
1, 2, 4, 8, 16, 32, 64 or 128
SIZEBUFFERS 8192 This parameter specifies the size of the buffers configured. It can be any value from 1 to 32k but there are restrictions on the number/size combination.  The maximum buffer space per port per direction is 64K and the maximum number of buffers possible is 128. Therefore the maximum buffer size for each setting the number of buffers is as follows:

Number of buffers     Maximum buffer size
1                     32K
2                     32K
4                     16K
8                     8K
16                    4K
32                    2K
64                    1K
128                   0.5K

This is per port per direction. So for example on a two port card, port A could be configured for 2 x 32K buffer for transmit and receive, while port B could be configured for 128 x 512 byte buffers for transmit and 4 x 16K byte buffers for receive.
NUMRXBUFFERS 8 As NUMBUFFERS but configures the rx buffers only
SIZERXBUFFERS 8192 As SIZEBUFFERS but configures the rx buffers only
NUMTXBUFFERS 8 As NUMBUFFERS but configures the tx buffers only
SIZETXBUFFERS 8192 As SIZEBUFFERS but configures the tx buffers only
LOWLATENCY disable This parameter only applies to the 4 port cards, i.e. T4U, T4E and T4E+.
The card normally works in a mode that reduces interrupts to the host (delayed interrupt mode), but this has the effect of introducing a small degree of latency on receive.  This parameter allows the latency to be minimised.  The parameter may take the following values:
rx      -  enter immediate interrupt mode (low latency rx)
tx      -  notify the card that there is a frame to transmit (low latency tx).
txrx    -  both of the above (low latency rx and tx)
disable -  enter delayed interrupt mode
CODING hdb3/nrz This parameter can be used to select the line encoding methods for the TE1, T4E+ and Flex as follows:
TE1
    hdb3       - default coding E1
    ami        - default coding T1
    ami-zcs    - T1 only
    b8zs       - T1 only
T4E+
    nrz        - default coding
    manchester 
Flex
    nrz        - default coding
    nrzi
    fm0
    fm1
TERMINATION none This parameter sets the line termination mode.  This parameter only works with the Flex and T4E+ devices.  The parameter may take one of the following two values:
none      - no termination
resistive - resistive termination
NRZICLOCKING disable enable
disable
SYNTH <string> This parameter is currently only available for use with the T4E or T4E+ cards.  Its purpose is to define an internal clock rate that isn't already provided as one of the standard T4E/T4E+ rates.  The string parameter is generated by FarSite based the desired clock rate.  Please contact FarSite or your distributor for further details on how a specific clock rate can be generated.

Note on Dual Clocking
In order to be able to provide a clock with data in each direction on the X.21 interface requires that the Indicate signal line be reassigned as the second clock line. This means that the signal will always appear to be ON. The Control signal is not used in this configuration. In order to use this mode, appropriate changes are required to the X.21 cable.  Note that the Dual Clocking feature is not available on T2P or T4P, in addition is not available on the T1U either, as the T1U does not support internal clocking.

Note on Buffer Configuration
The maximum buffer space per port per direction is 64K and the maximum number of buffers possible is 128. The table below shows the maximum buffer size that can be configured for a given number of buffers.

Number of buffers Maximum buffer size
1 32K
2 32K
4 16K
8 8K
16 4K
32 2K
64 1K
128 0.5K


This is per port per direction. So for example on a two port card, port A could be configured for 2 x 32K buffer for transmit and receive, while port B could be configured for 128 x 512 byte buffers for transmit and 4 x 16K byte buffers for receive.

Async Parameters

Parameter Typical/example value Meaning
flow_control None The flow control mechanism to be used.  The possible values are:
None     - No flow control
hardware - Use hardware CTS/RTS signalling
software - Use software Xon and Xoff characters
stop_bits 1 The number of stop bits to follow the data bits.  The possible values are:
1        - Use 1 stop bit
1.5      - Use 1 and a half stop bits
2        - Use 2 stop bits
parity None The parity checking mode to be used.  The possible values are:
None     - No parity checking is performed
Even     - The number of bits per byte is checked to be even
Odd      - The number of bits per byte is checked to be odd
word_len 8 The number of data bits used per character.  The possible values are in the range 5 to 8 bits inclusive.
xon_char 0x11 When the software flow control mechanism has been configured, this is the character used to notify the remote end that it may continue sending data again.  This character value will not normally need to be changed from it's default.
xoff_char 0x13 When the software flow control mechanism has been configured, this is the character used to notify the remote end that it should stop sending data until further notice.  This character value will not normally need to be changed from it's default.

 

TE1 Parameters

Parameter Typical/example value Meaning
MODE master Defines if the card provides clock to the line (master) or regenerates clock from the line (slave).
DATARATE 64000 Defines the effective datarate required from the T1 or E1 line.
  For E1 64000 - 2048000 bps in increments of 64000.
  For T1 64000 - 1536000 bps in increments of 64000.
NUMSLOTS 1 An alternative way of requesting the effective data rate. Here you supply the number of timeslots you require to be allocated. The effective data rate is then numslots*64 KBps.
  For E1 the values are 1 - 32
  For T1 the values are 1 - 24
STARTSLOT 1 When a fractional rate has been defined, this parameter can be used to specify the starting slot number in which transmissions are made.
  For E1 the values are 1 - 31
  For T1 the values are 1 - 23
STRUCTURE crc4 Defines how the timeslots are allocated. The values can be as follows:
For E1
  unframed - all 32 timeslots used for data
  double   - Framed mode 31 timeslots for data
  crc4     - Framed mode 31 timeslots for data
  crc4m    - Framed mode 31 timeslots for data
For T1
  unframed - all 24 timeslots used for data
  f4       - Framed mode 23 timeslots for data
  f12      - Framed mode 23 timeslots for data
  f24      - Framed mode 23 timeslots for data
  f72      - Framed mode 23 timeslots for data
INTERFACE rj48c Which of the two line interfaces are being used.  Values can be either bnc or rj48c. Please note that this parameter must be consistent with the link setting on the TE1 card. Please see the Quick Start Guide for more details.
EQUALIZER short This should be set to match your cable length, and can have the values of short or long.
LBO short followed by -7.5 or -15 or -22 (T1 Only)
RANGE 0-133ft followed by a range in feet or meters as in the table below. (T1 Only)
0-133ft 0-40m
133-266ft 40-81m
266-399ft 81-122m
399-533ft 122-162m
533-655FT 162-200M
LOOP none Can be used to perform loopback tests at various points in the connection path, as follows:
none      - no loopback
local     - loop at the physical interface
remote    - loop at the remote interface
pload+ts0 - remote loop including ts0
pload-ts0 - remote loop excluding ts0
RXBUFFER 2Frame Values can be as follows:
none   - No buffering
96Bit  - buffer 96 bits
1Frame - buffer 1 frame
2Frame - buffer 2 frames
TXBUFFER 2Frame Values can be as follows:
none   - No buffering
96Bit  - buffer 96 bits
1Frame - buffer 1 frame
2Frame - buffer 2 frames
IDLECODE 0 The value that is transmitted for idle slots can be specified. Enter the idle code in hex. The range is from 0 to 0xFF.

 

DSL Parameters

Parameter Typical/example value Meaning
DATARATE 23040000 This parameter is used to negotiate the actual data rate of the SHDSL link. The actual data rate achieved may be slower than that requested.  Use the farutil command to show the negotiated data rate when the training up process has completed.  The datarate is in multiples of 64 KBps starting at 192 KBps and ending at 2304 KBps.
VPI 5 This defines the Virtual Path Identifier to use in the ATM encapsulation of the PPP protocol.
VCI 38 This defines the Virtual Circuit Identifier to use in the ATM encapsulation of the PPP protocol.
TERMTYPE remote This is a low level DSL link property that defines what role this end of the DSL link will perform.  The values are Central (for central office equipment) and Remote (fro remote office equipment).  If you are connecting to an ISP, then this value is likely to be Remote.  If you have a SHDSL leased line then this value could be either.  Note that for the link to complete the training process successfully, one end must be Central and the other Remote.  If both ends are the same type, the the training process will fail.
ENCAP ppp This specified the ATM AAL5 encapsulation procedures to use in the link.  There are currently two procedures supports.  Choose pppfor RFC 2364 and mpoa for RFC 2684.
ANNEX A This is a low level DSL link property that defines the SHDSL interface procedures to be used at the electrical interface.  Annex A procedures are for the US and Annex B procedures are for Europe.
BACKOFF This is a low level DSL link property that is used during transmit power negotiation in the training procedure. Value may be set between 0 and 31dB, the default 6dB is suitable for most line types. Each receiver determines the Power Backoff for the counterparts transmitter.  The value for the transmit power, which is chosen by each receiver, is the maximum Power Backoff value (minimum transmit power) of the downloaded capability list and the default Power Backoff according to the estimated power loss of the line.
TESTMODE 0 There are a number of loopback test modes that are possible.  Currently the following are supported:
0  -  No Loop for normal operation
4  -  Analog Transparent Loop
8  -  Analog Non Transparent Loop
SNRTH 5 Signal to noise ratio threshold.  This is used to configure the signal to noise ratio at which a signal to noise defect alarm is generated.  Values can be specified in the range 0 - 35.
LPATH 25 Loop attenuation path threshold.  This is used to configure the signal level at which the Loop Attenuation defect alarm is generated.  Values can be specified in the range 0 - 35.
 

Networking Parameters

The networking parameters are used to assign IP addresses to the interface.  For a network device that is going to be used by an OEM application, this may not be relevant, but is documented here fro completeness.

OEM Network Parameters
Parameter Typical/example value Meaning
DEVICE sync0 The network device to use. This is a required parameter and must match the interface name.
IPADDR 10.0.0.1 This parameter is not significant for the OEM driver.
POINTOPOINT 10.0.0.2 This parameter is not significant for the OEM driver.
NETMASK 255.255.255.252 This parameter is not significant for the OEM driver.
NETWORK 10.0.0.0 This parameter is not significant for the OEM driver.
MTU 1500 Set the link Maximum Transfer Unit. You will probably control this value from your application.
ONBOOT no Defines whether the system should bring the interface up automatically at system startup. Set to no so that your application can bring up the link without having to worry if it is already up.

WAN Network Parameters

Parameter Typical/example value Meaning
DEVICE hdlc0 The network device to use. This is a required parameter and must match the interface name.
IPADDR 192.168.0.1 The IP address of this end of the point-to-point link. This is a required parameter. When setting up private links between machines it is common to use "private internet" addresses such as the example.
POINTOPOINT 192.168.0.2 The IP address of the remote end of the point-to-point link.  Note the misspelling (missing T) in the parameter name.
NETMASK 255.255.255.252 Subnet mask for link.
NETWORK 192.168.0.0 Network address for the link. If present these last two values will be used (possibly in combination with POINTOPOINT) to define the remote network and a route to it via the link. This usage is at variance with the standard system of defining the local network but then any such local network would be accessed via a different network interface rather than the point-to-point link.
MTU 1500 Set the link Maximum Transfer Unit. Unless you have a specialist use for the link, leave this value as 1500.
ONBOOT yes Defines whether the system should bring the interface up automatically at system startup. Set to no if you are not using the interface or wish to start it manually.

Further WAN Interfaces Parameters

When the Cisco or Frame Relay protocols are configured then there are some additional associated parameters that can be configured, although in general the default values will suffice.

Cisco Protocol

When the protocol type is cisco the following additional parameters may be set:

Parameter Default Meaning
INTERVAL 10 Number of seconds before sending a keep alive packet down the link.
TIMEOUT 25 Number of seconds without activity before a link is assumed to be broken.

Frame Relay Protocol

When the protocol type is fr the following additional parameters may be set:

Parameter Default Meaning
LMI ANSI Sets the LMI type.
Possible values are: none, ANSI, CCITT.
DCE no Set to Y to enable operation as a FR DCE. This has nothing to do with clock generation.
T391 10 Polling verification timer (in seconds)
T392 15 Link integrity polling timer (in seconds)
N391 6 Full status polling counter
N392 3 Error threshold
N393 4 Monitored events count

Frame Relay can support multiple IP transport links on one physical interface using separate PVC's or Permanent Virtual Circuits.

The master interface configuration file (ifcfg-hdlcX) should be set up as normal but without any entries for IPADDR, POINTOPOINT , NETMASK or NETWORK parameters.

For each PVC create an ifcfg-pvcX configuration file with the following parameters.
Parameter (Example) Value Meaning
DEVICE pvc0 The PVC device being used.
MASTERDEV hdlc0 The master interface supporting this interface.
DLCI 16 The Frame Relay DLCI number used to identify this PVC.
IPADDR 192.168.0.1 IP parameters to use for this PVC.
POINTOPOINT 192.168.0.2 See standard interface documentation for usage.
NETMASK 255.255.255.252  
NETWORK 192.168.0.0  
MTU 1500  
ONBOOT yes Whether the interface should be loaded at boot time. If this is set to "yes" then the ONBOOT setting in the master interface configuration must also be set to yes.

Once all the parameters have been defined in the configuration files (and the system started if necessary) the PVC interfaces can be brought up and down with the standard interface control commands "ifup" and "ifdown". ie. To start the first PVC interface you would use the command:

ifup pvc0

To examine the state of the network parameter you could use the command:

ifconfig pvc0

Finally to set the state of the PVC down you could use:

ifdown pvc0

It is currently a limitation of the Generic HDLC driver module implementation that the devices created to support Frame Relay pvcs (i.e. network devices called pvc0, pvc1 etc) are created in ascending numerical order. Thus it is not possible to do ifup-pvc1 before ifup-pvc0.

Copyright 2001-2010 FarSite Communications Ltd.