Sangoma S503 User manual

December 2001
FRAME RELAY SUPPORT FOR
SANGOMA CARDS
Hardware Interface Manual

LIMITED USE LICENSE AGREEMENT
Sangoma Technologies Inc. provides the computer software program contained on the medium in this package (hereinafter called the Program) and licenses its use.
THE LICENSEE SHOULD CAREFULLY READ THE FOLLOWING TERMS AND CONDITIONS BEFORE ATTEMPTING TO USE THIS PRODUCT. INSERTION OF ANY OF
THE DISKETTES IN THIS PACKAGE INTO ANY MACHINE INDICATES THE LICENSEE'S ACCEPTANCE OF THESE TERMS AND CONDITIONS. IF THE LICENSEE
DOES NOT AGREE WITH THE TERMS AND CONDITIONS, THE LICENSEE SHOULD PROMPTLY RETURN THE PACKAGE WITHIN 15 DAYS UNUSED AND
UNCOPIED IN ANY WAY SHAPE OR FORM, AND MONIES WILL BE REFUNDED.
LICENSE:
a. The purchaser of this license (hereinafter called the Licensee) is granted a personal, non-exclusive license to use the Program in accordance with the terms and conditions set
out in this agreement.
b. The Program may be used only on a single computer per license granted.
c. The Licensee and the Licensee's agents and employees shall protect the confidentiality of the Program and shall not distribute or make available the Program or
documentation to any third party.
d. The Licensee may copy the programs into machine readable or printed form for backup or modification purposes only in support of the Licensee's use on a single machine.
The Licensee must reproduce and include the copyright notice on any copy, modification or portion merged into another program.
e. Any portion of the Program merged into or used in conjunction with another program will continue to be subject to the terms and conditions of this agreement.
f. The Licensee may not assign or transfer the license or the program to any third party without the express prior consent of Sangoma Technologies Inc.
g. The licensee acknowledges that this license is only a limited license to use the Program and documentation, and that Sangoma Technologies Inc. retains full title to the
program and documentation.
h. The Licensee shall not use, copy, modify or transfer the Program or documentation or any copy, modification or merged portion, in whole or in part, except as expressly
provided for in this license. If the Licensee transfers possession of any copy, modification or merged portion of the program to a third party, the license is automatically
terminated under this agreement.
TERM:
The license is effective until terminated. The licensee may terminate the license at any time by destroying the Program together with all copies, modifications and merged portion in any
form. The Licensee agrees upon such termination to destroy the Program together with all copies, modifications and merged portion in any form.
LIMITED WARRANTY:
The Program is provided "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular
purpose. The entire risk as to the performance of the Program is with the Licensee. Should the Program prove defective, the Licensee (and not Sangoma Technologies Inc. or an authorized
dealer) shall assume the entire cost of all necessary servicing, or correction. However, Sangoma Technologies Inc. warrants the diskettes on which the Program is furnished will be free of
defects in materials or workmanship under normal use for a period of 90 days from the date of delivery to the Licensee. In no event will Sangoma Technologies Inc. be liable for any
damages, including incidental or consequential damages arising out of the use or inability to use the Program, even if Sangoma Technologies Inc. or an authorized dealer have been advised
of the possibility
of such damages, or for any claim by any other party.
The Licensee acknowledges that the Licensee has read this agreement, understands it, and agrees to be bound by its terms and conditions. The Licensee further agrees that it is the complete
and exclusive statement of the agreement between the parties and supersedes any proposal or prior agreement, oral or written, and any other communications between the parties relating
to the subject matter of this agreement.

3Frame Relay for Sangoma Cards (C) Sangoma Technologies Inc. 1999,2000,2001 Page 3 of 78
1. Introduction
The Sangoma cards are general co-processor communication adapters capable of supporting any
communication protocol autonomously, and providing information transfer into PC work space.
This document describes the support of the Frame Relay protocol on the card, and the hardware level
PC to Card API required for development of device drivers. Where drivers have been developed, the
details of the hardware interface are transparent to the user, and this document becomes a reference for
command and return codes. The hardware/software solution handles the link Information Rates and
local signalling autonomously, without PC intervention. The PC accesses the system as required to send
or receive data, configure the link or to obtain statistics.
The implementation of Frame Relay on the S508 adapter includes the following features:
!ANSI T1.617, Annex D, LMI or Q.933 Local in-channel signalling.
!Up to 100 DLCIs are supported.
!A maximum information packet length of 15356 bytes.
!Line speeds up to 4Mbps.
!Control of transmission Information Rates on a per DLCI basis to maximize line utilization while
keeping each DLCI data rate strictly inside the set parameters.
!Dynamic Frame Relay configuration facilities.
!Complete Frame Relay statistics package.
!A built in datascope with frame time stamping.
!Configurable as both a CPE (customer premises equipment) and an Access Node.

4Frame Relay for Sangoma Cards (C) Sangoma Technologies Inc. 1999,2000,2001 Page 4 of 78
Conventions used in this manual
Programming conventions used are as follows:
Variables described with an 0x prefix or an hsuffix are hexadecimal values. All other variables
are decimal.
For bit mapping, the least significant (low) bit is denoted as bit 0.

5Frame Relay for Sangoma Cards (C) Sangoma Technologies Inc. 1999,2000,2001 Page 5 of 78
2. Hardware
S503
This is a short 4 layer card, compatible with the ISA bus and it supports hardware interrupts as well as
operating in a passive polled mode. The RS232 or V.35/X.21 interface is jumper selectable.
Clock speed:
This is factory set by Jumper JP1. Do not change without consulting your Sangoma dealer.
I/O port address:
This is set by Jumper JP3.
Pins 5-6 Pins 3-4 Pins 1-2 I/O Address Selection
Not Jumpered Jumpered Jumpered 250-252 (Hex)
Jumpered Jumpered Jumpered 254-256 (Hex)
Not Jumpered Jumpered Not
Jumpered 300-302 (Hex)
Jumpered Jumpered Not
Jumpered 304-306 (Hex)
Not Jumpered Not
Jumpered Jumpered 350-352 (Hex)
Jumpered Not
Jumpered Jumpered 354-356 (Hex)
Not Jumpered Not
Jumpered Not Jumpered 360-362 (Hex)?
Jumpered Not
Jumpered Not Jumpered 364-366 (Hex)
?Factory default.

6Frame Relay for Sangoma Cards (C) Sangoma Technologies Inc. 1999,2000,2001 Page 6 of 78
IRQ Selection
The optional IRQ is set using JP2.
Pins 1-2 Pins 3-4 Pins 5-6 Pins 7-8 Pins 9-10 Selection
In Out Out Out Out IRQ 2
Out In Out Out Out IRQ 3
Out Out In Out Out IRQ 4
Out Out Out In Out IRQ 5
Out Out Out Out In IRQ 7?
? Factory default.
Interface Level Selection
This is set by Jumper JP3.
Pins 9-10 Interface Level
Jumpered RS-232
Not Jumpered V.35
S514 PCI card
No jumpers need to be set on this card as it is configured by the PC BIOS.
S508 ISA Card
Jumpers JP1 on the S508 define the card I/O address range as specified in Table 3-1. The specified
card I/O addresses must not conflict with I/O addresses in use by any other hardware installed on the
server. Use the SNOOPER utility if you are in any doubt as to hardware settings.
Note that JP1-1 on the S508 is furthest to the left if the board is held such that the connectors are to
the right. JP1-4 is reserved.

7Frame Relay for Sangoma Cards (C) Sangoma Technologies Inc. 1999,2000,2001 Page 7 of 78
The 8k (2000 Hex) byte shared memory address and the IRQ level are set in software for the S508.
Internal Line Clocking
For back-to-back connections, the cards can provide their own Transmit and Receive clock signals,
which, with the appropriate cable, can also provide the clock for third party devices.
All cards are capable of generating the transmit and receive clocks as long as the appropriate back-to-
back cable is used. The generated line speed is set by software.
However, the cards have a very large configurable range and therefore cannot easily be tabulated.
When asked for the line speed during setup, you may specify any value in kbps from 1 to 2600. The
actual generated line speed will be reasonably close the specified value, but will deviate more as the line
speed increases.
S514 Port Pinouts
NB: Port PA is the Primary 4Mbps port
Port PB is the Secondary 512Kbps port.
PIN # PA:RS232 PA:V.35 PB:RS232 PB:V.35
1RTS RTS
2CTS CTS
3GND GND GND GND
4DCD DCD
5DTR DTR (V.10)
6TXD
7RXD
8TXC
9RXC
10 RTS RTS
11 CTS CTS
12 DCD DCD
13 DTR DTR (V.10)
14 TXD
15 RXD
16 TXC
17 RXC

PIN # PA:RS232 PA:V.35 PB:RS232 PB:V.35
8Frame Relay for Sangoma Cards (C) Sangoma Technologies Inc. 1999,2000,2001 Page 8 of 78
18 TXA
19 TXB
20 RXA
21 RXB
22 TX Clock A
23 TX Clock B
24 RX Clock A
25 RX Clock B
26 DTR A (V.11)
27 DTR B (V.11)
28 TXA
29 TXB
30 RXA
31 RXB
32 TX Clock A
33 TX Clock B
34 RX Clock A
35 RX Clock B
36 DTR A (V.11)
37 DTR B (V.11)

9Frame Relay for Sangoma Cards (C) Sangoma Technologies Inc. 1999,2000,2001 Page 9 of 78
S503/S508 Port Pinouts
RS232
Pin # Function
2TxD
3RxD
7GND
4RTS
5CTS
20 DTR
6DSR
8DCD
15 TxC
17 RxC
24 BxC
V.35/X.21
Pin # Function
4RTS
5CTS
6DSR
7GND
8DCD
10 TxA
9TxB
12 RxA
11 RxB
19 Tx Clock A
20 DTR (V10 signal)
13 DTRA (V11 signal)
14 DTRB (V11 signal)
21 Tx Clock B
22 RI
23 Rx Clock A
25 Rx Clock B
18 Aux. Clock A (On board clock
source)
16 Aux. Clock B (On board clock
source)

10Frame Relay for Sangoma Cards (C) Sangoma Technologies Inc. 1999,2000,2001 Page 10 of 78
3. The programmer's interface
Using the Frame Relay Shared Memory Interface
The SDLA card is operated by reading and writing structures to positions in the shared memory
window. For details of moving the structures to/from the board, see the section “Example Code”.
The application program accesses the frame relay software by completing the required parameters
within the control block defined below and then setting the OPP_FLAG. The SDLA processor will
carry out the defined command and then update this control block with the required return code and, if
applicable, the associated data buffer, data length etc. Once the command has been completed, the
OPP_FLAG will be reset by the SDLA processor.
This control block structure is found at the physical offset 0xE000 on the adapter. For example if
S508LOAD is executed with a command line definition of '- mDC', then the physical address of the
control block is 0xDC00:0xE0000.

11Frame Relay for Sangoma Cards (C) Sangoma Technologies Inc. 1999,2000,2001 Page 11 of 78
The Shared Memory Control Block Structure
The control block structure is as follows:
Parameter Off-
set Lth Remarks
OPP-FLAG 00H 1A flag set by the application to inform the SDLA processor that a
COMMAND is pending. This flag is in turn reset by the processor
when the COMMAND has been completed.
COMMAN
D01H 1Command code.
BUFFER_
LENGTH
02H 2Length of the data buffer associated with this call.
RETURN_
CODE
04H 1Result of the previous command.
DLCI 05H 2The Data Link Connection Identifier concerned with this command.
FECN_
BECN_DE_
CR_BITS
07H 1FECN, BECN DE and C/R bits associated with the transmitted
Information frame.
RESERVED 08H 8Reserved for later use.
DATA 10H 102
4This is the transfer area for passing data associated with the various commands to and from the application level.

12Frame Relay for Sangoma Cards (C) Sangoma Technologies Inc. 1999,2000,2001 Page 12 of 78
4. COMMAND Codes
The valid commands are:
0x01 INFORMATION_WRITE
0x03 ISSUE_IN_CHANNEL_SIGNALLING_FRAME
0x10 SET_DLCI_CONFIGURATION
0x11 READ_DLCI_CONFIGURATION
0x12 DISABLE_COMMUNICATIONS
0x13 ENABLE_COMMUNICATIONS
0x14 READ_DLC_STATUS
0x15 READ_DLC_STATISTICS
0x16 FLUSH_DLC_STATISTICS
0x17 LIST_ACTIVE_DLCIs
0x18 FLUSH_INFORMATION_BUFFERS
0x20 ADD_DLCIs
0x21 DELETE_DLCIs
0x22 ACTIVATE_DLCs
0x23 DEACTIVATE_DLCs
0x30 READ_MODEM_STATUS
0x31 SET_MODEM_STATUS
0x32 READ_COMMS_ERR_STATS
0x33 FLUSH_COMMS_ERR_STATS
0x40 READ_CODE_VERSION
0x41 DISCARD_INCOMMING_I_FRAMES
0x42 BRIDGE_TRANSMITTER_AND_RECEIVER
0x50 SET_INTERRUPT_TRIGGERS
0x51 READ_INTERRUPT_TRIGGERS
0x60 SET_TRACE_CONFIGURATION
0x61 READ_TRACE_STATISTICS

13Frame Relay for Sangoma Cards (C) Sangoma Technologies Inc. 1999,2000,2001 Page 13 of 78
INFORMATION_WRITE (0x01)
Send data to the card for onward transmission to the network as an Information frame on the selected
Data Link Connection Identifier (DLCI).
Control Block values to be set on entry:
DLCI: The DLCI associated with this Information frame.
BUFFER_
LENGTH The length of the data in the Information frame to be transmitted. The maximum data
length is 15356 bytes and is dependent on the maximum I-frame length defined in the
SET_DLCI_CONFIGURATION command OR the maximum number of bytes which
may be transmitted in a single Tc interval.
FECN_BECN_
DE_CR_BITS: The status of the FECN, BECN, DE and C/R bits to be set in the transmitted
I-frame (represented by bits 3, 2, 1 and 0 respectively).
If the Discard Eligibility (DE) Indicator is reset, then the I-frame will only be transmitted
within the throughput limit defined by the Committed Information Rate (CIR). If this bit
is set, then the throughput will be limited to the Uncommitted Information Rate.
For a device configured as Customer Premises Equipment (CPE), only the Discard
Eligibility (DE) Indicator and the Command/Response (C/R) bits are valid. For a device
configured as an Access Node, the Forward Explicit Congestion Notification (FECN),
the Backward Explicit Congestion Notification (BECN) and the Command/Response
(C/R) bits are valid.
DATA: The actual data to be transmitted.

14Frame Relay for Sangoma Cards (C) Sangoma Technologies Inc. 1999,2000,2001 Page 14 of 78
Control Block values set on return:
RETURN_
CODE: 0x00 The data has been queued for transmission. Note that any return code other
than 0x00 indicates that no data was sent to the S508 card and this same
data should be re-sent in its entirety.
0x01 The ENABLE_COMMUNICATIONS command has not been executed and
information transfer is not possible.
0x02 The channel is currently inoperative and information transfer is not possible.
0x03 The DLCI is currently inactive and information transfer is not possible on this
particular DLCI.
0x04 The DLCI selected is invalid (i.e., it was not included in the DLCIs listed in the
SET_DLCI_CONFIGURATION command).
0x05 The BUFFER_LENGTH set by the application exceeded the maximum I-
frame length defined by the SET_DLCI_CONFIGURATION command. The
BUFFER_LENGTH is set to the maximum permitted length.
0x06 The BUFFER_LENGTH set by the application exceeded the maximum
number of bytes which may be transmitted in a single Tc interval. The returned
BUFFER_LENGTH indicates the calculated maximum number of bytes that
can be transmitted in a Tc period.
0x07 The current transmit throughput has exceeded that defined by the Committed
Information Rate (CIR) or the Uncommitted Information Rate. The application
is attempting to send data to the frame relay network at a rate faster than
transmit throughput constraints dictate.
0x08 The data was not queued due to the fact that all the transmit buffers are
currently occupied.

15Frame Relay for Sangoma Cards (C) Sangoma Technologies Inc. 1999,2000,2001 Page 15 of 78
0x10, 0x11, 0x12, 0x13, 0x14, 0x1F
See Section "Notes on Return Codes" for further details.
DATA (valid if a RETURN_CODEof 0x00 is received):
Offset 0x00-0x04: a pointer to the Transmit Status Element to be used for this
outgoing frame (see the section on Transmitting Information Frames for further
details).

16Frame Relay for Sangoma Cards (C) Sangoma Technologies Inc. 1999,2000,2001 Page 16 of 78
ISSUE_IN_CHANNEL_SIGNALLING_FRAME (0x03)
Issue a local In-channel Signalling message at a station configured as a CPE. Status enquiry messages
are automatically issued by a CPE at a period of T391 seconds. However, the user may wish to force
the transmission of these messages in cases such as recovery from an inoperative channel. This
command permits the application to issue either a Full Status Enquiry or a Link Verification Enquiry
message.
Control Block values to be set on entry:
BUFFER_
LENGTH: Set to 0x01.
DATA: Offset 0x00 indicates the type of Status Enquiry to be issued:
0x02 - issue a Link Verification Enquiry message.
0x03 - issue a Full Status Enquiry message.
Control Block values set on return:
RETURN_
CODE: 0x00 The action was performed successfully.
0x01 The ENABLE_COMMUNICATIONS command has not been executed and
no frames may therefore be issued.
0x06 The type of Status Enquiry frame set at offset 0x00 in the DATA area is invalid.
0x07 A Status Enquiry message may not be issued at a station configured as an
Access Node.
0x10, 0x11, 0x12, 0x13, 0x14, 0x1F

17Frame Relay for Sangoma Cards (C) Sangoma Technologies Inc. 1999,2000,2001 Page 17 of 78
SET_DLCI_CONFIGURATION (0x10)
Set the frame relay code configuration. This command may be used as a global configuration command
(on DLCI 0x00) or may be used to dynamically configure a specific DLCI.
After down loading the code to the adapter, a DISABLE_ COMMUNICATIONS and then a
SET_DLCI_CONFIGURATION command (DLCI 0x00) should be issued. This SET_DLCI_
CONFIGURATION command configures 'global' parameters pertaining to the In-channel Signalling
pragmatics such as T391 and N392, as well as DLCI-specific parameters such at the CIR, Bc and Be.
Note that this command executed with the DLCI set to 0x00 applies the DLCI-specific configuration
parameters to all DLCIs listed. Thereafter, if desired, each DLCI may be individually configured by
using the SET_DLCI_CONFIGURATION command with the DLCI set to a specific (non-zero)
value.
The use of this command with the DLCI set to zero also acts as a code 'reinitialization' - all transmit and
receive buffers are flushed, statistics are reset and In-channel Signalling numbering and timers are
zeroed. Note that a DISABLE_COMMUNICATIONS command should always be issued before a
global SET_DLCI_CONFIGURATION command (DLCI 0x00) is used.
Control Block values to be set on entry:
DLCI: Set to 0x00 for a 'global' configuration or to a specific DLCI.
BUFFER_
LENGTH: For DLCI 0x00:
Set to 0x20 plus twice the number of DLCIs to be used by this station. Note that if
automatic DLCI configuration is used at a CPE (bit 15 of the miscellaneous frame relay
configuration bits is set), then the BUFFER_LENGTH should be set to 0x20.
For a non-zero DLCI:
Set to 0x0E.

18Frame Relay for Sangoma Cards (C) Sangoma Technologies Inc. 1999,2000,2001 Page 18 of 78
DATA: For DLCI 0x00 (all parameters are 2-byte, unsigned values):
Offset 0x00: the station configuration
0x00: Customer Premises Equipment (CPE).
0x01: Access Node (switch).
Offset 0x02: miscellaneous frame relay configuration bits as follows:
Bit 0: if reset, then the transmission data rates for Information frames will be kept within
the limits set by the CIR, Bc and Be parameters. If set, then the transmission speed of
Information frames will be restricted only by the physical baud rate and no CIR
checking will be performed.
Bit 1: if reset, then no CIR checking will be performed on incoming Information frames.
If set, then the throughput of the incoming Information frames will be compared against
the defined backwards CIR and account will be kept of all frames exceeding this limit.
If the station is configured as an Access Node, then all I-frames received in excess of
the CIR will have the DE (Discard Eligibility) bit automatically set before passing to the
application.
Bit 2: reserved for later use.
Bit 3: if reset, then Information frames passed to the board with an
INFORMATION_WRITE command will not be queued if the Committed Burst Size
or Excess Burst Size will be exceeded by the transmission of this frame. If set, then the
Information frame will be stored in a transmit buffer (if there is a buffer available),
irrespective of the current transmit throughput.
Bit 4: if reset, then throughput calculations will not be performed. If set, then transmit
and receive throughput calculations will be performed for each DLCI and these results
may be accessed by using the READ_DLC_STATISTICS command.
Bit 5: if reset, then exception condition return codes (0x10, 0x11, 0x12, 0x13 and
0x14) will be passed to the application on an INFORMATION_WRITE command.
This bit may be set so as to disable the passing of these error codes when performing

19Frame Relay for Sangoma Cards (C) Sangoma Technologies Inc. 1999,2000,2001 Page 19 of 78
INFORMATION_WRITE command, thus simplifying error processing in the
application code, particularly in interrupt handlers.
Bit 6, 7: reserved for later use.
Bit 8: this bit should be set if the user is connecting to the MCI Frame Relay network.
Bits 9 - 11: reserved.
Bit 12: if this bit is set, then no In-Channel Signalling is used and Information frames
may be transferred on all configured DLCIs after communications have been enabled.
Bits 13 - 14: the transmit/receive buffer ratios as follows:
If bits 13 and 14 are reset, then the transmit/receive buffer ratio is 50/50.
If bit 13 is set and bit 14 is reset, then the transmit/receive buffer ratio is 70/30.
If bit 13 is reset and bit 14 is set, then the transmit/receive buffer ratio is 30/70.
Bit 15: (valid only at a station configured as a CPE)
If reset, then a list of DLCIs to be handled by this station must be included in this
SET_CONFIGURATION command. If set, then automatic DLCI configuration will
occur, and the first100 DLCIs listed by the node will be configured. The application will
be notified of theses DLCI additions by means of the return code 0x13.

20Frame Relay for Sangoma Cards (C) Sangoma Technologies Inc. 1999,2000,2001 Page 20 of 78
Offset 0x04: the baud rate of the access line (kbps). This parameter must be set correctly even
if external clocking is used, as this baud rate is used in CIR throughput checking. Valid
values are from 1 to 2666 kbps.
.
Offset 0x06: the clocking source and electrical interface.
If bit 0 is reset, then external clocking is used.
If bit 0 is set, then internal clocking is used.
If bit 1 is reset, then the electrical interface is V.35.
If bit 1 is set, then the electrical interface is RS232.
Offset 0x08: the maximum data length of the Information frames to be transferred (valid entries
from 300 to 15356 bytes).
Offset 0x0A: the T391 (Link Integrity Verification) timer. Valid entries are from 5 to 30
seconds and only pertain to a station configured as a CPE.
Offset 0x0C: the T392 (Polling Verification) timer. Valid entries are from 5 to 30 seconds and
only pertain to a station configured as an Access Node.
Offset 0x0E: the N391 (Full Status Polling Cycle) counter. Valid entries are from 1 to 255 and
only pertain to a station configured as a CPE.
Offset 0x10: the N392 (Error Threshold) counter. Valid entries are from 1 to 10 events and
pertain to both a CPE and Access Node.
Offset 0x12: the N393 (Monitored Events) counter. Valid entries are from 1 to 10 events and
pertain both a CPE and Access Node.
Offset 0x14: the forward Committed Information rate (CIR fwd). This is the rate (in kbps) at
which the network agrees to transfer Information frames generated at this station under
normal conditions. Valid values are between 1 and 512 kbps.
Offset 0x16: the forward Committed Burst Size (Bc fwd). This is the maximum amount of data
generated at this station (in kbits) that the network agrees to transfer, under normal
conditions, during a time interval Tc (the Committed Rate Interval). Valid values are