(Page 1 of 1 in this chapter) Version

Chapter 2

Application Development

2.1 Introduction

2.2 MVIP/H.100/H.110 Interface API

: 2.2.1 MVIP/H.100/H.110 Initialization
: 2.2.2 Making and Breaking Connections
: 2.2.3 Diagnostic and Miscellaneous Functions

2.3 T1/E1 Interface API

: 2.3.1 Configuring and Initializing T1/E1 Interfaces
: 2.3.2 Monitoring Line Status
: 2.3.3 Statistics and Performance Measures
: 2.3.4 Carrier Alarms
: 2.3.5 Diagnostic and Miscellaneous Functions

2.4 Handling Unsolicited Notifications

: 2.4.1 Registering for Unsolicited Notifications
: 2.4.2 Unsolicited Message Formats
: 2.4.3 Byte Ordering Considerations
: 2.4.4 Dual Port RAM (DPR) Header
: 2.4.5 T1/E1 Unsolicited Message Common Header
: 2.4.6 Carrier Status/Alarm Change Message
: 2.4.7 Performance Report Messages

2.1 Introduction

This chapter describes the API functions available for the T1/E1 and MVIP/H.100/H.110 APIs. Each API is documented independently of the other.
Throughout the remainder of this document, stream selection will be denoted as DSin or DSon, where n is the stream number. This is the naming convention adopted for MVIP-90 type connections. For H.100/H.110 boards, you are referred to a given stream number. This distinction should be made, as applicable.

2.2 MVIP/H.100/H.110 Interface API

The MVIP/H.100/H.110 interface API supplies the basic functions for switching, clock control, and diagnostics. The API functions provided are compatible with the MVIP-90/MVIP-95 software standards, with some extensions. The general operation and use of these functions is described in the following sections.

2.2.1 MVIP/H.100/H.110 Initialization

MVIP/H.100/H.110 initialization consists of resetting the switch fabric to a known state (disabled with all connections cleared and all outputs tri-stated), setting the clock configuration, and enabling the switch fabric.
If you download the TDM configuration file, you don't need to perform this initialization. It is initialized automatically by the resident TX software. You may still use these functions to override the information in the TDM configuration file, if desired. Note: If you do not prepare a TDM configuration file and download it to the board (for example, if you have no dedicated data channels), you must perform the functions described below before attempting to set up any connections.
The switch fabric is reset with the TxResetSwitch function. This clears all connections and disables (tri-states) all outputs. Note: Using TxResetSwitch will disrupt any dedicated data channels configured. For TX 2000 and TX 3000 boards, these channels will automatically be re-established once the switch fabric is enabled. For TX 3220 and TX 3220C boards, the TDM configuration record must be reloaded (using either the cplot utility or the Loader API).
The clock configuration is set with the TxConfigClock function. It specifies whether or not the TX board drives the main (/C4, /F0, and C2) and secondary 8 Khz (SEC8k) clock signals. When driving clock signals, TxConfigClock also specifies whether the TX board's clock is free running or locked to one of its T1/E1 interfaces or the SEC8k signal.
After the switch is reset and clocks configured, the switch may then be disabled/re-enabled with the TxTristateSwitch function. Enabling the switch allows the TX board to transmit on the MVIP/H.100/H.110 bus once connections are established.

2.2.2 Making and Breaking Connections

Switched connections are established and cleared with the TxSetOutput and TxSetOutputFdx functions. These routines accept a destination stream/timeslot, a source stream/timeslot, and a connection mode as input and configure the switch fabric appropriately. The following connection modes are available: Connection Mode Description CONNECT_MODE Establishes a connection between the specified source stream/timeslot and destination stream/timeslot. TxSetOutput establishes a half-duplex connection in which data sampled from the specified source stream/timeslot is output on the specified destination stream timeslot only. TxSetOutputFdx sets up a full duplex connection. Data sampled from the specified source stream/timeslot is output on the specified destination stream timeslot and data sampled for the destination stream/timeslot's corresponding input is output on the specified source stream/timeslot's corresponding output. DISABLE_MODE Clears a connection by disabling (tri-stating) the output specified by the destination stream/timeslot (TxSetOutputFdx also disables the output side corresponding to the source stream/timeslot, effectively clearing both directions of a full duplex connection). PATTERN_MODE Forces a specified one-byte pattern to be output repeatedly on the destination stream/timeslot (source stream/timeslot is ignored). Figure 2. Half-Duplex MVIP Connection Figure 3. Full-Duplex MVIP Connection
TX board processors support both forward and reverse directions, in order to provide more flexibility in connecting to other boards. For example, if two boards both transmit on the DSoX output, they won't be able to receive from each other (one has to be able to receive on DSoX and transmit on DSiX). For any given MVIP/H.100/H.110 stream/timeslot, the TX board can output on either the DSiX bus line or the DSoX bus line. For H.100/H.110 boards, the TX board can output on any stream number. There is no restriction to even or odd stream numbers.
By default, the TX board uses the DSiX bus line as output and the DSoX bus line as an input. This is called a forward (or standard) connection. You get this behavior by specifying the source and destination stream numbers as 0 through 7 for MVIP-90, and 0 through 31 for H.100/H.110. To get the TX board to reverse which line it uses for input and which for output for MVIP-90, add 8 to the stream number (use stream numbers 8 through 15). For H.100/H.110, the convention is to pair even and odd stream numbers. This is done independently for both the source and destination sides of a connection. Note: Switch fabric streams that correspond to T1/E1 lines (streams 16 and 18 for MVIP-90, and streams 40 and 41 for H.100/H.110) don't switch between input and output on a given signal line. These are always considered to be in the forward direction.
Figure 4 shows an example of setting up a full-duplex connection between two T1 lines on different boards utilizing the MVIP bus. This example shows a connection between T1 line A, timeslot 2 on board 1 and T1 line B, timeslot 7 on board 2. The connection between the two boards is setup over MVIP bus stream 0, timeslot 1. The connections are setup as forward connections on board 1 and as reverse connections on board 2. Figure 4. Establishing Forward and Reverse Connections

Connection Mode	Description
`CONNECT_MODE`	Establishes a connection between the specified source stream/timeslot and destination stream/timeslot. TxSetOutput establishes a half-duplex connection in which data sampled from the specified source stream/timeslot is output on the specified destination stream timeslot only. TxSetOutputFdx sets up a full duplex connection. Data sampled from the specified source stream/timeslot is output on the specified destination stream timeslot and data sampled for the destination stream/timeslot's corresponding input is output on the specified source stream/timeslot's corresponding output.
`DISABLE_MODE`	Clears a connection by disabling (tri-stating) the output specified by the destination stream/timeslot (TxSetOutputFdx also disables the output side corresponding to the source stream/timeslot, effectively clearing both directions of a full duplex connection).
`PATTERN_MODE`	Forces a specified one-byte pattern to be output repeatedly on the destination stream/timeslot (source stream/timeslot is ignored).

2.2.3 Diagnostic and Miscellaneous Functions

The MVIP/H.100/H.110 API includes other functions which can be used for diagnostic or other purposes. The TxQuerySwitchCaps returns some bitmaps indicating the routing and blocking characteristics of the TX switch fabric and, more importantly, the number of channel time slots available on each of its network interfaces (0 if no T1 or E1 adapter is present, 24 for each T1 line, 32 for each E1 line). It can be used at run time to determine if the card is equipped for T1, E1, or neither.
TxQueryOutput can be used to determine the current mode (connect, disable, pattern) of any stream/timeslot, which input stream/timeslot its connected to (if any) or the pattern currently being output (if in pattern mode).
TxSampleInput can be called to retrieve the current input sample from a particular stream/timeslot. This is typically used to test a connection when a particular one-byte pattern is expected on the input side of the connection (for example, the side driving the input is in pattern mode).
TxTristateSwitch can be used to disable (and later re-enable) all outputs from the TX switch fabric. By contrast, TxResetSwitch disables the output of the switch fabric, but also clears all connections.
As mentioned earlier, TxSetOutput can be used to force a stream/timeslot into pattern mode, in which a single byte pattern is continually output on that timeslot. This can be used in conjunction with the TxSampleInput function to test the ability of two TX boards to switch a digital path across the MVIP bus and/or their T1/E1 interfaces, as shown in Figure 5. Note: The configuration shown here requires two TX boards connected via the MVIP/H.100/H.110 bus and a T1/E1 loopback cable. Figure 5. Testing TX ISA Switch Paths

2.3 T1/E1 Interface API

The T1/E1 interface API supplies the functions for configuring, monitoring, and collecting statistics on the T1/E1 interface adapter. The general operation and use of these functions is described in the following sections.

2.3.1 Configuring and Initializing T1/E1 Interfaces

The T1/E1 adapter and drivers support a number of different configuration options which must be set before communication can be established with remote equipment. These options are set with the TxT1E1ConfigCarrier function and include the type of framing employed on the line, the line coding format, and the clock source.
If you download the TDM configuration file, you don't need to perform this initialization. It is performed automatically by the resident software. You may still use TxT1E1ConfigCarrier to override the information in the TDM configuration file. Note: If you do not prepare a TDM configuration file and download it to the board (if you have no dedicated data channels), you must call TxT1E1ConfigCarrier before attempting to make connections utilizing the T1/E1 interfaces.
For T1 lines, if robbed bit signaling is enabled for the line as a whole, individual channels may be configured as transparent, or clear channels, with the TxT1E1ConfigChan function. This prevents the T1 framer chip from inserting signaling bits into these channels in outgoing frames. This step is not necessary for common channel signaling or data-only applications, where robbed bit signaling should be disabled for the line as a whole.

2.3.2 Monitoring Line Status

The TX software can report the current status of each T1/E1 line either on request through an API call or (optionally) whenever the line state changes through unsolicited messages.
The TxT1E1CarrierStatus function returns the current state of the line (carrier and frame synchronization status), whether or not an alarm is currently present, the current configuration parameters (framing mode, line coding, etc.), and the current performance statistics. This function can be called at any time to determine the current line status.
Optionally, the application can request to be notified any time the synchronization state of the line changes (carrier or synchronization established or lost) and/or any time an alarm condition is detected or cleared, via an unsolicited message. Unsolicited status messages are delivered out of band; that is, they come to the application through a separate interface to the TX device driver rather than directly through the API. The application must first call the TxT1E1SuperviseCarrier function to register which events of which it wants to be notified.

2.3.3 Statistics and Performance Measures

The statistics for the current 15-minute interval and the current 24-hour interval are returned by the TxT1E1CarrierStatus function. A full performance report for the previous 96 15-minute intervals plus the 24-hour summary totals is obtained from the TxT1E1PerfReport function.
In addition, the application can request that performance reports are automatically generated every 15 minutes and/or every 24 hours with the TxT1E1SuperviseCarrier function. These performance reports are returned to the application in the form of unsolicited messages using the same TX device driver interface as the unsolicited status/alarm messages.
The statistics and performance measures maintained by the TX software are as follows:
Event Counters TR 54016 Name RFC1406 Name Description ESF Error Event Path Code Violation Accumulated frame sync or CRC errors. Error Events N/A Line code violation, accumulated bipolar violations, or excessive zeroes errors. Controlled Slips Controlled Slip (CS) Accumulated replication or deletion of received frames due to timing slips. E-bit Error Events N/A Number of E-bit errors (CRC errors) reported back by far end through CRC4 multiframe E-bit indicator.
Performance Measures (all are counts relative to a 15-min. interval)

TR 54016 Name

RFC1406 Name

Description

Errored Seconds (ES)

Errored Seconds (ES)

Number of seconds (0-900) with one or more CRC/frame sync errors, out-of-frame declarations, or controlled slips.

N/A

Line Errored Seconds

Number of seconds (0-900) with one or more line code violations.

Bursty Errored Seconds

Bursty Errored Seconds

Number of seconds (0-900) with
(BES) 1 < path code errors < 320.

Severely Errored seconds (SES)

Severely Errored seconds (SES)

Number of seconds (0-900) with path code errors greater than or equal to 320.

Controlled Slip Seconds

Controlled Slip Seconds

Number of seconds (0-255) with one or more controlled slips.

Loss of Frame Count

N/A

Number of out-of-frame defects declared (0-255).
Event counters are 16-bit accumulators that are reset only on a request from the host application. Performance measures are counts maintained for: The current 15-minute interval The previous 96 15-minute intervals (24 hours) The sum total for the previous 24 hours
The current interval counts and the previous 96 interval counts are always available on request from the host application.
The following RFC 1406 (DS1/E1 MIB) measures are not explicitly supported: Severely Errored Framing Seconds Degraded Minutes

TR 54016 Name	RFC1406 Name	Description
ESF Error Event	Path Code Violation	Accumulated frame sync or CRC errors.
Error Events	N/A	Line code violation, accumulated bipolar violations, or excessive zeroes errors.
Controlled Slips	Controlled Slip (CS)	Accumulated replication or deletion of received frames due to timing slips.
E-bit Error Events	N/A	Number of E-bit errors (CRC errors) reported back by far end through CRC4 multiframe E-bit indicator.

TR 54016 Name	RFC1406 Name	Description
Errored Seconds (ES)	Errored Seconds (ES)	Number of seconds (0-900) with one or more CRC/frame sync errors, out-of-frame declarations, or controlled slips.
N/A	Line Errored Seconds	Number of seconds (0-900) with one or more line code violations.
Bursty Errored Seconds	Bursty Errored Seconds	Number of seconds (0-900) with (BES) 1 < path code errors < 320.
Severely Errored seconds (SES)	Severely Errored seconds (SES)	Number of seconds (0-900) with path code errors greater than or equal to 320.
Controlled Slip Seconds	Controlled Slip Seconds	Number of seconds (0-255) with one or more controlled slips.
Loss of Frame Count	N/A	Number of out-of-frame defects declared (0-255).

2.3.4 Carrier Alarms

The TX board monitors a variety of carrier alarm conditions. If requested by the application, the setting and clearing of these alarm states can be reported as unsolicited status events or can be returned on request with the TxT1E1CarrierStatus function. In addition, the TX board can report other carrier status changes such as establishment and loss of synchronization and the detection or loss of carrier signal.
The following table lists the alarms detected by the TX board: Alarm State Entry Criteria Typical Usage Blue alarm (AIS) Unframed all ones signal received for 3 ms (T1) or 2 full frames (E1). Far end cannot transmit normal signal (for example, a repeater which has lost the incoming carrier on the other side). Yellow alarm (Distant or Far End) · D4 - Bit 2 in every channel set to 0 for ~ 335 ms. · ESF - 16 consecutive patterns of 0x00FF appear in the facility data link (FDL). · E1 - Bit 3 of timeslot 0 in non-align frames set to 1 for 3 consecutive occasions. Far end has lost incoming signal from reporting node. Timeslot 16 Alarm Indication Signal (E1 only) E1 CAS mode only - Timeslot 16 contains all 1s for 16 consecutive frames (1 full multiframe). Far end has lost normal CAS signaling capability (for example, lost incoming CAS signal on other side). Timeslot 16 Signal Lost (E1 only) E1 CAS mode only - Timeslot 16 contains all 0s for 16 consecutive frames (1 full multiframe). Failure of equipment providing CAS signaling. Distant Multiframe Alarm (E1 only) E1 CAS mode only - Bit 6 of timeslot 16 of frame 0 set to 1 for 2 consecutive multiframes. Far end has lost CAS multiframe alignment.

Alarm State	Entry Criteria	Typical Usage
Blue alarm (AIS)	Unframed all ones signal received for 3 ms (T1) or 2 full frames (E1).	Far end cannot transmit normal signal (for example, a repeater which has lost the incoming carrier on the other side).
Yellow alarm (Distant or Far End)	· D4 - Bit 2 in every channel set to 0 for ~ 335 ms. · ESF - 16 consecutive patterns of 0x00FF appear in the facility data link (FDL). · E1 - Bit 3 of timeslot 0 in non-align frames set to 1 for 3 consecutive occasions.	Far end has lost incoming signal from reporting node.
Timeslot 16 Alarm Indication Signal (E1 only)	E1 CAS mode only - Timeslot 16 contains all 1s for 16 consecutive frames (1 full multiframe).	Far end has lost normal CAS signaling capability (for example, lost incoming CAS signal on other side).
Timeslot 16 Signal Lost (E1 only)	E1 CAS mode only - Timeslot 16 contains all 0s for 16 consecutive frames (1 full multiframe).	Failure of equipment providing CAS signaling.
Distant Multiframe Alarm (E1 only)	E1 CAS mode only - Bit 6 of timeslot 16 of frame 0 set to 1 for 2 consecutive multiframes.	Far end has lost CAS multiframe alignment.

2.3.5 Diagnostic and Miscellaneous Functions

Two other functions, TxT1E1ConditionChan and TxT1E1CtrlCarrier are available for diagnostics or other purposes.
The TxT1E1ConditionChan function can be used to force a single 8-bit pattern to be continuously output on one or all channels on the T1/E1 line.
TxT1E1CtrlCarrier can be used to generate an alarm condition on a T1/E1 line or to force the line into loopback mode. The various alarm modes are described in Section 2.3.4, Carrier Alarms.
The TX software supports the following loopback modes. Mode Description Local Loopback Data is transmitted as normal through the transmit side of the line, but the receive side of the line is replaced with the data being transmitted. Remote Loopback Data received from the Rx tip and ring pins is transmitted back out onto the Tx tip and ring pins, including any bipolar violations which might be present. The received data continues its normal path through the TX board in addition to being looped back onto the transmit side. This mode is used to implement the "line" loopback required by ANSI T1.403 and AT&T TR 62411.

Mode	Description
Local Loopback	Data is transmitted as normal through the transmit side of the line, but the receive side of the line is replaced with the data being transmitted.
Remote Loopback	Data received from the Rx tip and ring pins is transmitted back out onto the Tx tip and ring pins, including any bipolar violations which might be present. The received data continues its normal path through the TX board in addition to being looped back onto the transmit side. This mode is used to implement the "line" loopback required by ANSI T1.403 and AT&T TR 62411.

2.4 Handling Unsolicited Notifications

An application can choose to receive unsolicited notifications of T1/E1 line status changes, alarms, and/or periodic performance reports. The following events can be requested: Establishment and loss of carrier and frame synchronization Alarms set and cleared 15-minute performance reports 24-hour performance reports
These notifications are received directly from the TX device driver rather than through the API calls. The following subsections describe the procedures and message formats for these notifications.

2.4.1 Registering for Unsolicited Notifications

Registering for unsolicited status/performance notifications requires the following steps:

Initialize the TX Communications Processor Interface (CPI) library by calling cpi_init.

Open the CPI T1/E1 status channel by calling cpi_open.

Call the T1/E1 API TxT1E1SuperviseCarrier routine to enable the desired unsolicited notifications.

Periodically call cpi_get_data to check for messages. For most host operating systems, cpi_open returns a system file descriptor or handle which can be used to detect when a message is pending without blocking the application or requiring the application to periodically call cpi_get_data to check for packets. For example, under UNIX, the file descriptor returned by cpi_open can be used with the UNIX poll system call to determine when a packet is pending, and hence when to call cpi_get_data to retrieve the packet.

Note: The details of these steps may vary depending on the host operating system in use.

2.4.2 Unsolicited Message Formats

The general form of unsolicited messages is shown in Figure 6. Each packet consists of: A standard dual-port RAM (DPR) header used to interface with the device driver. A Unsolicited Msg Header (UHdr) which identifies the notification type and T1/E1 line. A parameter block which depends on the notification type. Figure 6. Unsolicited Status Message Format

2.4.3 Byte Ordering Considerations

All 16-bit and 32-bit fields ("C" short, int and long types) in the data portion of the DPR packet must be passed to/from the board in Motorola 680x0 byte order (most significant byte first). This is not the same as Intel 80x86 native byte ordering. This means that the host application must byte swap these fields in requests before sending and must also byte swap these fields in responses (for example, the status field) before attempting to interpret the contents.
Note: The length field in the DPR header is never byte swapped by the host application. The driver expects it in Intel byte order.
The following set of macros are provided in the txcpi.h file to assist in byte ordering: cpi_cptoh_s cpi_cptoh_l cpi_htocp_s cpi_htocp_l

2.4.4 Dual Port RAM (DPR) Header

All messages to and from a TX processor contain a DPR header. For T1/E1 status messages, the DPR header can be used to identify the sending board (srcbd field) and the byte length of the message (len field). Note: The source and destination channel numbers are always 11 for the T1/E1 status messages. Its layout is as follows: typedef struct __dprh { unsigned char srcch; /* Source channel number */ unsigned char srcbd; /* Source board number (1..8) */ unsigned char dstch; /* Destination channel number */ unsigned char dstbd; /* Destination board # (0 = PC) */ unsigned short len; /* Len of msg body (incl hdr) */ } DPRH;

2.4.5 T1/E1 Unsolicited Message Common Header

The UMsg header identifies the type of notification and the line to which it refers (A or B). typedef struct txT1E1UHdr { unsigned short statusCode; /* request codes from tdmuser.h */ unsigned char carrier; /* which T1/E1 line(A or B) */ unsigned char spare1; /* word align what follows */ } TxT1E1UHdr;
Possible values for the statusCode are: STATUS_CARRIER 0x80 /* Line status change */ CARRIER_ALARM 0x81 /* Change in alarm state */ PERFREP_15MIN 0x83 /* 15 minute performance report */ PERFREP_24HR 0x84 /* 24 hour performance report */
Possible values for the carrier field are: NET_T1A /* T1/E1 line A */ NET_T1B /* T1/E1 line B */

2.4.6 Carrier Status/Alarm Change Message

The unsolicited status structure is used for the carrier status and alarm notifications. typedef struct txT1E1UStat { TxT1E1UHdr uhdr; /* unsolicited msg headr */ unsigned char alarmState; /* alarm status (CARRIER_ALARM only) */ unsigned char lastAlmState; /* Previous alarm status * (CARRIER_ALARM only) */ unsigned char wordalign; /* filler for alignment */ unsigned char syncState; /* new synch state (STATUS_CARRIER only) */ } TxT1E1UStat;
The alarm state fields are bit maps with a 1-bit indicating that the alarm condition is present and a 0-bit indicating that the alarm condition is cleared. Including both the current and previous alarm states allows the application to determine which alarm(s) changed state and whether the alarm condition has just been detected or just cleared. Alarm conditions are defined in Section 2.3.4, Carrier Alarms. Possible values for these fields are: YELLOW_ALARM 0x01 BLUE_ALARM 0x02 TS16SIG_ALARM 0x08 TS16AIS_ALARM 0x04 ISTANTMF_ALARM 0x10
The syncState field is used only in the STATUS_CARRIER notification message. Possible values are: CARRIER_SYNC 1 Carrier signal fully synchronized CARRIER_NOSYNC 2 Carrier signal detected but not synchronized CARRIER_LOST 3 No carrier signal detected

2.4.7 Performance Report Messages

The 15-minute performance report contains the perform measures for the previous 15-minute measuring period plus the current values for the event accumulators. typedef struct txT1E1Perf15 { TxT1E1UHdr uhdr; /* unsolicited msg header */ TxT1E1Stats currStats; /* current interval stats */ unsigned short pcvs; /* Accumulated path code violations */ unsigned short lcvs; /* Accumulated line code violations */ unsigned short slips; /* Accumulated controlled slips */ unsigned short ebits; /* Accumulated E-bit Errors (E1) */ } TxT1E1Perf15;
The 24-hour performance report contains the performance statistics for the preceding 96 15-minute measurement intervals, the sum total of each performance measure for the last 24 hours, plus the current values for the event accumulators.
If less than 96 intervals are available, the validInts field contains the number of valid intervals actually included in the performance report message. typedef struct txT1E1Perf24 { TxT1E1UHdr uhdr; /* unsolicited msg header */ unsigned short validInts; /* number of intervals included */ TxT1E1Stats intStats[96]; /* last 96 15-min intervals */ TxT1E1Stats sumStats; /* 24-hour summary statistics */ unsigned short pcvs; /* Accumulated path code violations */ unsigned short lcvs; /* Accumulated line code violations */ unsigned short slips; /* Accumulated controlled slips */ unsigned short ebits; /* Accumulated E-bit Errors (E1) */ } TxT1E1Perf24;

(Page 1 of 1 in this chapter) Version

tech_support@nmss.com