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 labeled "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

 

Each card has one, two or four network interfaces associated with it, one for each line. These interfaces are labeled "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.

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.

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, 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 or includes 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 command 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 note about dual clocking below)
v24       - V.24 (aka good old RS232C)
rs232     - V.24
v35       - V.35
ux35c     - V.35 internal clocking with adapter cable     (valid for TxU, TxUe)
rs449     - RS449/530                                     (valid for T2U-PMC, T4E/T4E+, T2Ee, T4Ee, Flex)
rs530     - RS449/530                                     (valid for T2U-PMC, T4E/T4E+, T2Ee, T4Ee, Flex)
u530      - RS530 with adapter cable                      (valid for TxU, TxUe)
e1        - E1 (G703/G704)
t1        - T1 (G703/G704)
rs485     - RS485                                         (valid for T2Ee, T4Ee, Flex)
rs485_fdx - RS485 Full Duplex                             (valid for T2Ee, T4Ee, Flex (v2 only))
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.
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 allows more flexible clocking arrangements to be configured.  The values currently defined for this parameter are as follows:
dce_tt   - default configuration for DCE Terminal Timing (0x8B)
dte_tt   - default configuration for DTE Terminal Timing (0x84)
erx_etx  - set external rx and external tx clocks (0x80)
erx_itx  - set external rx and internal tx clocks (0x81)
irx_etx  - set internal rx and external rx clocks (0x82)
irx_itx  - set internal rx and internal tx clocks (0x83)
none     - disable extended clocking modes (0x00)
0xdd     - a hexadecimal representation of the extendedClocking byte in struct fstioc_info
           e.g. 0x83 is the same as irx_itx
(valid for T2U-PMC, T4E/T4E+, T2Ee, T4Ee, Flex v2.  The Flex v1 does not support dce_tt or dte_tt modes as it does not support terminal timing.)
LED   This parameter tests the LED operation for the device.  It can help identify 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)
1BITINSERT on Enable or Disable the One Bit Insert feature.  This parameter is only valid for FarSync Flex ports.  The values currently defined for this parameter are as follows:
on       - enable One Bit Insertion feature
off      - disable One Bit Insertion feture
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
Note that for the Flex, the number of buffers cannot be set to 1
SIZEBUFFERS 8192 This parameter specifies the size of the buffers configured. It can be any value from 1 to 32k-1 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 permitted value of the number of buffers is as follows:

Number of buffers     Maximum buffer size    Maximum buffer size
                                               for TE1 or TE1e
1                     32K-1                          32K-1
2                     32K-1                          32K-1
4                     16K                            32K-1
8                     8K                             32K-1
16                    4K                             16K
32                    2K                             8K
64                    1K                             4K
128                   0.5K                           2K

This is per port per direction. So for example on a two port card, port A could be configured for 2 x 32K-1 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 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
(valid for T4U, T4E/T4E+, T4Ee)
CODING hdb3/nrz This parameter can be used to select the line encoding methods as follows:

hdb3            (E1 default coding)     (valid for TE1, TE1e)
ami             (T1 default coding)     (valid for TE1, TE1e)
ami-zcs         (T1 only)               (valid for TE1, TE1e)  
b8zs            (T1 only)               (valid for TE1, TE1e)
nrz             (default coding)        (valid for T4E+, T2Ee, T4Ee, Flex)
nrz_clk_rec                             (valid for Flex (v2 only)
nrzi                                    (valid for Flex)
fm0                                     (valid for T4E+, T2Ee, T4Ee, Flex)
fm1                                     (valid for T4E+, T2Ee, T4Ee, Flex)
manchester                              (valid for T4E+, T2Ee, T4Ee, Flex (v2 only))
diff_manchester                         (valid for T4E+, T2Ee, T4Ee, Flex (v2 only))
TERMINATION none This parameter sets the line termination mode.  The parameter may take one of the following two values:
none      - no termination
resistive - resistive termination
(valid for T2U-PMC, T4E/T4E+, T2Ee, T4Ee, Flex)
NRZICLOCKING disable enable
disable
(valid for T4E+ and Flex)
SYNTH <string> This parameter can be used to define an internal clock rate that isn't already provided as one of the standard rates.  The string parameter is generated by using some additional tools, please click on this link for details of setting custom clock rates.
(valid for T2Ue, T2U-PMC, T4E/T4E+, T2Ee, T4Ee, Flex v2).
Note that when a custom clock rate is set with this command, and then farutil is used to assign the new internal clock rate to the port it may warn that the clock rate was unknown and that the nearest rate will be selected.  In this case this message can be disregarded.

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 only available on the T1U, T2U, T2Ue, T4U and T4Ue.

Async Parameters

Parameter Typical 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 signaling
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 its 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 its default.

 

TE1 Parameters

Parameter Typical 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.
In framed mode:
  For E1 64000 - 1984000 bps in increments of 64000.
  For T1 64000 - 1536000 bps in increments of 64000.
In unframed mode:
  For E1 64000 - 2048000 bps in increments of 64000.
  For T1 64000 - 1544000 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 - 31
  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 framed mode, timeslot 0 is reserved for synchronisation.
  For E1 the values are 1 - 31
  For T1 the values are 0 - 23

In unframed mode, the startslot is not applicable.
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.
EXTSYNCCLOCK disable Set to enable, to enable external synchronization clock for TE1e. The port's clocking MODE must be set to master if the external synchronization mode is required.
EXTSYNCCLOCKOFFSET false Set to true to enable d.c. offset on the external synchronization clock for TE1e.
EXTSYNCCLOCKRATE 1000000 Set the external synchronization clock clock rate for TE1e. Valid rates are:
 1000000
 1544000
 2048000
 5000000
10000000
PPS disable Set to enable, to enable the 1PPS input for TE1e.
PPSOFFSET false Set to true to enable d.c. offset on the 1PPS input for TE1e.

 

DSL Parameters

Parameter Typical 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 (for 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 training process will fail.
ENCAP ppp This specified the ATM AAL5 encapsulation procedures to use in the link.  There are currently two procedures supported.  Choose ppp for 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 for completeness.

OEM Network Parameters
Parameter Typical 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 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.
IPV6ADDR FEC0::3/64 The local address of the IPv6 Point-to-Point link. Note that the address is 'site local'. i.e. begins with FECO.

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 value 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 value 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-2021 FarSite Communications Ltd.