SS7 MTP Layer 2 Developer s Reference Manual

Transcription

1 SS7 MTP Layer 2 Developer s Reference Manual P/N Crossing Boulevard, Framingham, MA USA

2 No part of this document may be reproduced or transmitted in any form or by any means without prior written consent of NMS Communications Corporation NMS Communications Corporation. All Rights Reserved. Alliance Generation is a registered trademark of NMS Communications Corporation or its subsidiaries. NMS Communications, Natural MicroSystems, AG, CG, CX, QX, Convergence Generation, Natural Access, CT Access, Natural Call Control, Natural Media, NaturalFax, NaturalRecognition, NaturalText, Fusion, PacketMedia, Open Telecommunications, Natural Platforms, and HMIC are trademarks or service marks of NMS Communications Corporation or its subsidiaries. Multi-Vendor Integration Protocol (MVIP) is a registered trademark of GO-MVIP, Inc. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd. Windows NT, MS-DOS, MS Word, Windows 2000, and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Clarent and Clarent ThroughPacket are trademarks of Clarent Corporation. Sun, Sun Microsystems, and the Sun logo are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and/or other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the United States and/or other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc. All other marks referenced herein are trademarks or service marks of the respective owner(s) of such marks. Every effort has been made to ensure the accuracy of this manual. However, due to the ongoing improvements and revisions to our products, NMS Communications cannot guarantee the accuracy of the printed material after the date of publication, or accept responsibility for errors or omissions. Revised manuals and update sheets may be published when deemed necessary by NMS Communications. Revision History Revision Release Date Notes B.1.0 July, 1998 GJG 1.1 September 15, 1998 GJG 1.2 March, 1999 GJG 1.4 November, 2000 GJG; SS GJG; SS August, 2001 GJG; SS7 3.8 Beta 1.7 February, 2002 MVH; SS7 3.8 GA This manual printed: January 31, 2002 Refer to the NMS web site ( for product updates and for information about NMS support policies, warranty information, and service offerings.

3 Table of Contents 1 Introduction Introduction Overview Getting Started Overview of the MTP 2 Installation and Configuration Process Installation Configuring TDM Ports Configuring MTP 2 Links Downloading the Board Running a Sample User Application SS7 Links and MTP Layer 2 Service Users Entity and Instance IDs TX Driver Interface TX Driver Message Format Byte Ordering Considerations Layer 2 Interface Procedures Binding Connection Establishment Data Transfer Status/Control Connection Clearing MTP 2 Messages MTP 2 Management Alphabetical Function Reference Introduction Mtp2GetLinkCfg Mtp2InitLinkCfg Mtp2LinkStats Mtp2LinkStatus Mtp2MgmtCtrl Mtp2MgmtInit Mtp2MgmtTerm Mtp2SetLinkCfg NMS Communications 3

4 Table of Contents 4 MTP 2 Sample Applications The MTP 2 Configuration Utility Using the MTP 2 Configuration Utility The MTP 2 Configuration File MTP2 Configuration Parameter Reference Sample Configuration Files The MTP 2 Manager Program Using the MTP 2 Manager Program The Sample Applications - mtp2app and mtp2itu Appendix A MTP 2 Message Reference Introduction Bind Request Connect Request Connect Confirmation Data Request Data Confirmation Data Indication Disconnect Confirmation Disconnect Request Disconnect Indication Disconnect Response Flow Control Request Flow Control Indication Flow Control Response Status Request Status Confirmation Status Indication Status Response NMS Communications

5 Chapter 1 Introduction 1.1 Introduction Overview 6 NMS Communications 5

6 Chapter 1 Introduction 1.1 Introduction The SS7 MTP Layer 2 Developer s Reference Manual describes the interface from the host processor to the resident SS7 MTP Layer 2 (link layer), independent of the host operating system and device driver employed. Subsequent sections of this document describe the general characteristics and operation on the MTP 2 APIs, as well as a detailed specification of the messages and function calls that comprise the APIs. 1.2 Overview A typical SS7/MTP 2 implementation consists of the following : Æ The SS7 MTP layer 2 running on the TX communications processor. The MTP2 process provides the signaling link functions defined by the ITU-T (Q.703) and ANSI (T1.111) standards: signal unit delimitation and alignment, error detection and correction, link alignment, link error monitoring, and flow control. Æ The TX Alarms Manager task. This task collects unsolicited alarms (status changes) generated by the MTP 2 task and forwards them to the host for application-specific alarm processing. Æ A TX driver for the host operating system which provides low level access to the TX Series from the host PC. Æ The txalarm application on the host for displaying and optionally saving to disk alarms from the MTP 2 task. Æ The TX MTP 2 interface is comprised of a set of messages passed between the user application (providing the SS7 MTP layer 3 functionality) and the MTP 2 process on the TX communications processor. These messages allow the (layer 3) application to initialize, transfer data, and exchange status information with layer 2, enabling the (layer 3) application to implement the link and traffic management procedures defined in the relevant standards for layer 3. Æ The mtp2cfg utility that downloads text file configurations to the MTP 2 task. mtp2cfg is provided in source and executable form. 6 NMS Communications

7 Overview Æ The mtp2mgr utility that allows a user to manage the MTP 2 task. mtp2mgr is provided in source and executable form. Æ The mtp2app and mtp2itu sample user applications also provided in source and executable form. These sample applications take user commands and send messages to the MTP 2 task. Æ The MTP 2 Management API that provides a series of calls for managing the MTP 2 task. The mtp2cfg and mtp2mgr both use this API. NMS Communications 7

8 Chapter 1 Introduction Host Txalarm utility Log file Application MTP Layers 2 & 3 API Config. utility MTP Layers 2 & 3 Mgmt. API Host TX driver SS7 TCAP task Alarms Manager task SS7 SCCP task SS7 ISUP/TUP task SS7 MTP Layers 2 & 3 Task TX communications processor SS7 Layer 1 driver Figure 1. SS7 System Architecture 8 NMS Communications

9 Chapter 2 Getting Started 2.1 Overview of the MTP 2 Installation and Configuration Process Installation Configuring TDM Ports Configuring MTP 2 Links Downloading the Board Running a Sample User Application SS7 Links and MTP Layer 2 Service Users Entity and Instance IDs TX Driver Interface TX Driver Message Format Byte Ordering Considerations Layer 2 Interface Procedures Binding Connection Establishment Data Transfer Status/Control Connection Clearing MTP 2 Messages 25 NMS Communications 9

10 Chapter 2 Getting Started 2.1 Overview of the MTP 2 Installation and Configuration Process The following sections provide a summary of the steps required to install and configure the MTP layer 2 software Installation First, the TX board needs to be installed properly. Remember which IRQ and memory address the board is set for before installing the card in the PC. See the appropriate installation manual for more information. Next, the software needs to be installed. Install the TX Base/Device Driver package and then the MTP 2 layer software. See the Installation Instructions in the SS7 CD-ROM booklet for information on the installation of the Base/Device driver package for your operating system Configuring TDM Ports If the TX board which will run the MTP 2 task will be sending and receiving on a T1, E1 or MVIP time slot, see the T1/E1/MVIP Interface Adapters Developer s Reference Manual for help with setting up TDM ports for use by the MTP 2 task. There are two sample configuration files included with the Base Software: tdmcp1.cfg and tdmcp2.cfg. These two samples will support a back-to-back arrangement of two TX boards using T1 s Configuring MTP 2 Links MTP 2 allows applications to configure the number of links as well as many parameters associated with those links. Four samples are included with MTP 2, two for ANSI and two for ITU-T. These samples are located in \nms\tx\config\ for Windows and /opt/nmstx/etc/ for UNIX. The sample configurations support back-to-back configurations. These examples contain a definition for one TDM port and a commented-out V.35 port. If the installation uses V.35 ports, then comment in the example serial port definition in the file and comment out the TDM port. 10 NMS Communications

11 Downloading the Board Downloading the Board Once the software and links are set up properly, the TX board can be downloaded with the software and configuration. The mtp2load batch file is included to assist in this action. The mtp2load file accepts one parameter, the board number to load. This loader file downloads the necessary software to the TX board, including the proper kernel, support tasks for alarms and debugging, a console program, the MVIP and T1/E1 managers, and MTP 2 itself. Finally, the configuration for MTP 2 is downloaded. Here is the Windows NT or Windows 2000 version of off REM set TXUTIL=c:\nms\tx\bin set TXCP=c:\nms\tx\cp set TXCONFIG=c:\nms\tx\config set BRD=1 if not "%1"=="" set BRD=%1 REM REM TXn000 COMMUNICATIONS PROCESSOR BOOT FILE REM REM REM Execute this file to boot/configure the TXn000 processor REM REM REM Get the model number %TXUTIL%\cpmodel -b %BRD% if errorlevel 3000 goto boot3000 if errorlevel 2000 goto boot2000 echo ERROR! Check board number goto end :boot3000 %TXUTIL%\cplot -c %BRD% -f %TXCP%\cpk3000.lo -k -a -u ss7 goto loadsw :boot2000 %TXUTIL%\cplot -c %BRD% -f %TXCP%\cpk.lo -k -a -u ss7 goto loadsw :loadsw REM %TXUTIL%\cplot -c %BRD% -f %TXCONFIG%\TDMcp%BRD%.bin -g tdm %TXUTIL%\cplot -c %BRD% -f %TXCP%\nmg.lot -n netmgr -p 5 -a %TXUTIL%\cplot -c %BRD% -f %TXCP%\console.lot -n console -p 2 -a %TXUTIL%\cplot -c %BRD% -f %TXCP%\inf.lot -n inf -p 10 -a REM REM download the MVIP and T1/E1 manager tasks to enable use REM of the MVIP and T1/E1 host APIs; NOTE: if you do not REM use either of these APIs, remove the following 2 lines. NMS Communications 11

12 Chapter 2 Getting Started REM %TXUTIL%\cplot -c %BRD% -f %TXCP%\mvip.lot -n mvip -p 4 -a %TXUTIL%\cplot -c %BRD% -f %TXCP%\t1e1mgr.lot -n t1e1mgr -p 15 -a REM REM Load MTP2 stand alone task REM %TXUTIL%\cplot -c %BRD% -f %TXCP%\mtp2.lot -n mtp -p 10 -a -s %TXUTIL%\mtp2cfg -b %BRD% -f %TXCONFIG%\MTP2cp%BRD%.cfg :end set TXUTIL= set TXCP= set TXCONFIG= The Unix version of MTP2LOAD looks similar: # Reset board, clear driver stats # load CPK/OS and related tasks, # and configure SS7 if [ -z "$TX2BASE" ] then TX2BASE=/usr/lib/txn fi if [ -z "$CONFIGBASE" ] then CONFIGBASE=/etc/txn fi # reset board cputil -b$1 -R # clear driver stats cputil -b$1 -C # get board type BOARDTYPE= cputil -b$1 -i case $BOARDTYPE in TX3000) CPK="cpk3000.lo" ;; TX2000) CPK="cpk2000.lo" ;; *) echo "board $1 not available" exit 1 ;; esac # load CPK/OS cplot -c $1 -f $TX2BASE/$CPK -k -u ss7 -a # load Related tasks cplot -c $1 -f $TX2BASE/debug.lot -n debug -p 3 -a cplot -c $1 -f $TX2BASE/nmg.lot -n netmgr -p 5 -a cplot -c $1 -f $TX2BASE/console.lot -n console -p 2 -a cplot -c $1 -f $TX2BASE/inf.lot -n inf -p 10 -a 12 NMS Communications

13 Downloading the Board # load TDM configuration - note: remove this line if you use # serial (V.35) ports rather than T1/E1/MVIP cplot -c $1 -f $CONFIGBASE/TDMcp$1.bin -g tdm # load the MVIP and T1/E1 manager tasks to enable use # of the MVIP and T1/E1 host APIs. Note: if you do not # use either of these APIs, remove the following two lines cplot -c $1 -f $TX2BASE/mvip.lot -n mvip -p 4 -a cplot -c $1 -f $TX2BASE/t1e1mgr.lot -n t1e1mgr -p 15 -a # MTP2 stand alone task cplot -c $1 -f $TX2BASE/mtp2.lot -n mtp -p 10 -a # MTP2 configuration. mtp2cfg -b $1 -f $CONFIGBASE/MTP2cp$1.cfg The txalarm application is also included to help debugging the configuration and user applications. The following is a sample output from txalarm when the board is downloaded without sending a new MTP 2 configuration: <12/05/ :51:58> mtp 1 1 Registering MTP Layer 2 <12/05/ :51:58> mtp 1 1 Configuring MTP Layer 1 <12/05/ :51:58> mtp 1 1 MTP1 Initializing. <12/05/ :51:58> mtp 1 1 MTP1 General Configuration <12/05/ :51:58> mtp 1 1 MTP1 Configuring link 0: TDM, External <12/05/ :51:58> mtp 1 1 MTP1 Configuring link 1: TDM, External <12/05/ :51:58> mtp 1 1 MTP1 Configuring link 2: TDM, External <12/05/ :51:58> mtp 1 1 MTP1 Configuring link 3: TDM, External <12/05/ :51:58> mtp 1 1 MTP1 Configuration Done <12/05/ :51:58> mtp 1 1 Configuring MTP Layer 2 <12/05/ :51:58> mtp 1 1 MTP2: General Configuration <12/05/ :51:58> mtp 1 1 MTP2: Link 0 Configuration <12/05/ :51:58> mtp 1 1 MTP2: Link 1 Configuration <12/05/ :51:58> mtp 1 1 MTP2: Link 2 Configuration <12/05/ :51:58> mtp 1 1 MTP2: Link 3 Configuration NMS Communications 13

14 Chapter 2 Getting Started Running a Sample User Application When the board has been loaded, one of the sample applications can be started. mtp2app is an ANSI version and mtp2itu is an ITU-T (formerly CCITT) version of the sample application. See Chapter 4 for more details. If you are using the TX board with test equipment, run an application then hit <RETURN> to get a command prompt. Type connect 0 <ENTER> to ask the board to start the connect procedure on link 0. The txalarm output should look like the following sample if the link aligns properly: <12/05/ :52:45> mtp 1 1 Flushing Buffers (OPC=0) <12/05/ :52:45> mtp 1 1 Starting Alignment <12/05/ :52:45> mtp 1 1 IAC Rx SIO <12/05/ :52:45> mtp 1 1 IAC Rx SIO <12/05/ :52:45> mtp 1 1 Rx SIN <12/05/ :52:47> mtp 1 1 ALIGN TIMER 4 EXPIRED (Link Aligned) If you are using two TX boards back-to-back, after downloading each board separately, start an application on each board (mtp2app -b 2 to run on board 2), and type connect 0 on each. The txalarm output should look like the following sample if the link aligns properly: <12/05/ :52:42> mtp 2 1 Flushing Buffers (OPC=0) (Lnk 0) <12/05/ :52:42> mtp 2 1 Starting Alignment (Lnk 0) <12/05/ :52:45> mtp 1 1 Starting Alignment (Lnk 0) <12/05/ :52:45> mtp 2 1 Received SIOS (Lnk 0) <12/05/ :52:45> mtp 1 1 IAC Rx SIO (Lnk 0) <12/05/ :52:45> mtp 1 1 IAC Rx SIO (Lnk 0) <12/05/ :52:45> mtp 1 1 Rx SIN (Lnk 0) <12/05/ :52:45> mtp 2 1 IAC Rx SIO (Lnk 0) <12/05/ :52:45> mtp 2 1 IAC Rx SIO (Lnk 0) <12/05/ :52:45> mtp 2 1 Rx SIN (Lnk 0) <12/05/ :52:47> mtp 1 1 ALIGN TIMER 4 EXPIRED (Lnk 0) <12/05/ :52:47> mtp 2 1 ALIGN TIMER 4 EXPIRED (Lnk 0) The middle column that contains 1 s and 2 s identifies which board generated the alarm. 14 NMS Communications

15 SS7 Links and MTP Layer 2 Service Users 2.2 SS7 Links and MTP Layer 2 Service Users A TX communications processor can support up to 16 SS7 links (depending on the board model and hardware configuration), numbered 0 to 15. Additional TX boards can be added for more links. The MTP Layer 2 interface supports one or more user applications by way of service access points, or SAPs. Each SAP corresponds to a single SS7 link controlled by the MTP 2 process. A user application binds to a particular SAP at initialization time, specifying the link number to which the application wishes to bind (0-15). An application implementing MTP layer 3 would repeat the bind process for every SS7 link on every TX communication processor. Only one process is allowed to bind to each SS7 MTP 2 service access point (link). User MTP 3 Bind SAP 0 SAP 1 SAP n... MTP 2 SAPs MTP 2 LAYER... LINK 0 LINK 1 LINK n Figure 2. MTP 2 Service Access Points (SAPs) NMS Communications 15

16 Chapter 2 Getting Started 2.3 Entity and Instance IDs Each application must have a unique entity and instance number, which is used to route messages among the various processes in the system. Entity IDs are single byte values in the range 0x00 to 0x3f, assigned as desired by the application developer. The following entity IDs are reserved: Range 0x00-0x1F 0x20-0x3F Usage Reserved for use by system utilities, configuration utilities, and management utilities. Available for use by applications. Instance IDs identify the processor that the entity executes on. The host is always processor zero, so for all host-resident MTP 2 user applications this value should be coded to zero. All tasks on the TX board number one receive an instance ID of one, all tasks on TX board number two receive an instance ID of two, and so on. 16 NMS Communications

17 TX Driver Interface 2.4 TX Driver Interface The TX device drivers implement a message-passing interface between the host and TX processor (CP). The physical interface between the host and the CP (shared dual-port RAM, or DPR) is subdivided into a set of virtual channels to support communication between processes on the host and processes on the TX board. The channel concept allows multiple process on both the host and TX processor to exchange messages without interfering with each other. The TX board currently supports 256 channels (numbered 0 to 255). Channels 0 to 31 are reserved for use by NMS standard products. Channels 32 to 255 are available for application use. A process (on either the host or TX processor) wishing to receive messages registers with the driver for a particular channel number. For a host-resident process, the channel registration may be implicit with the device open request, or it may be a separate operation. Channel numbers are assigned statically at compile time. There is no built-in facility to dynamically learn the channel assigned to any particular function. Only one process may receive messages for a particular channel. Each message contains a header, supplied by the sender of the message, to identify the destination board and channel, the source board and channel, and the length of the message. Each process in an SS7 implementation, both on the CP and on the host, registers for the channel that corresponds to that layer s (or application s) entity ID. The MTP 2 layer registers for channel 0x16. To send a message to the MTP 2 layer on board n, the destination channel is set to 0x16, the destination board is set to n, and the source channel and board are set to the sender s entity ID and board number (the host is board number zero). The TX driver can be called through the CPI Library. Consult the CPI Library Software Interface Manual for more details. An application should call cpi_init before using any other CPI calls. A call to cpi_open should be issued to each board with which the application wishes to communicate. cpi_send and cpi_get_data are then called to send and retrieve data packets to and from the board. NMS Communications 17

18 Chapter 2 Getting Started 2.5 TX Driver Message Format This section describes the general format of messages passed between the MTP 3 process on the host and the MTP 2 task on the TX CP through the TX driver. Octet Message Format 0 Source Channel (Source Entity ID) 1 Source Board (Source Instance ID) 2 Destination Channel (Destination Entity ID) 3 Destination Board (Destination Instance ID) i i + 1 Message Length (2 octets) Message Start Offset (2 octets) Message End Offset (2 octets) Filler Message Type i MTP 2 Message Parameters n NMS Communications

19 Byte Ordering Considerations The destination entity/instance IDs and the source entity/instance IDs define the intended recipient and the sender of the message, respectively. The Message Length contains the byte length of the entire message, including headers, filler, and parameters. The Message Start Offset contains the number of octets of filler included following the Message End Offset before the Message Type parameter. It is recommended that at least four bytes of filler are included on messages sent to MTP 2 to guarantee MTP 2 has room to prepend its header to the actual data portion of a message without having to copy the data to a new buffer. On messages received from MTP 2, the layer 3 application must use this parameter to determine where in the buffer the actual message content (the Message Type field) begins (see Section 2.8). Several include files are available with the MTP 2 sample user application code. mtp2app.h or mtp2itu.h along with txcpi.h contain structures for message formats. 2.6 Byte Ordering Considerations The following byte ordering conventions for 16-bit and 32-bit parameters in the messages to and from MTP 2. This is not the same byte ordering used for short and long integers on Intel 80x86 machines. The host application is responsible for converting between network and host byte order, if necessary, in both the send and receive directions. Note: 16-Bit Fields: The Message Length field is part of the DPR header interface between the host application and the host device driver, and must be passed in host native byte order, not the byte order shown in this section. The Message Start and End offsets, on the other hand, are part of the interface between the host application and the MTP 2 process, and must be passed in the network byte order shown below: Address Low High High Order Byte (MSB) Low Order Byte (LSB) NMS Communications 19

20 Chapter 2 Getting Started 32-Bit Fields: Address Low High Order Word (MSB) High Order Word (LSB) Low Order Word (MSB) High Low Order Word (LSB) The following nomenclature is used for data types: Data Type U8 S16 U32 Description Unsigned 8-bit quantity Signed 16-bit quantity Unsigned 32-bit quantity 2.7 Layer 2 Interface Procedures This section describes the procedures (the sequence of messages) used to interface to the SS7 MTP 2 process on the TX board. The SS7 layer 2 interface consists of several distinct phases: binding, connection establishment, data transfer, connection clearing, and status/control Binding The binding phase establishes the host application (MTP layer 3) as the user of the layer 2 interface. Binding consists of a single BIND request from the application to layer 2, for which there is no response. A seperate bind request must be sent to MTP 2 for every link on every TX board that the application wishes to use. 20 NMS Communications

21 Connection Establishment Connection Establishment MTP layer 2 establishes a connection by sending a CONNECT request packet. This causes MTP layer 2 to attempt to bring up the link and initiate link alignment procedures with the far exchange. Layer 2 sends a CONNECT CONFIRMATION mesage back to the user when link alignment has been successfully established. Connection establishment is requested separately for each SS7 link Note: No data packets may be transferred until the CONNECT CONFIRMATION message has been received by the user application. Application (Layer 3) MTP 2 Process Far Exchange Connect Rqst Begin Link Alignment SIO SIN or SIE FISUs Connect Cfm Alignment Complete Figure 3. Message Flow for Connection Establishment NMS Communications 21

22 Chapter 2 Getting Started Data Transfer The data transfer phase is entered on a particular link once the MTP 2 process has returned a CONNECT CONFIRMATION message to the application. The layer 2 user application requests a SS7 packet to be transmitted on a particular link by sending a DATA REQUEST to layer 2. MTP 2 returns a DATA CONFIRMATION message back to the user application when the message has been acknowledged by the far exchange. The application may send multiple DATA REQUEST(s) to MTP 2 before receiving a DATA CONFIRMATION. The DATA CONFIRMATION message contains a credit field indicating the number of data requests being acknowledged by the data confirm. Application (Layer 3) MTP 2 Process Far Exchange Data Rqst Data Rqst Data Confirm MSU FSN (1) MSU FSN (2) FISU BSN (2) Figure 4. Message Flow for an Outgoing Data Transfer 22 NMS Communications

23 Status/Control Layer 2 notifies the user application of an incoming data packet by sending a DATA INDICATION packet (see Figure 5). There is no response to this packet from the user application back to layer 2. Application (Layer 3) MTP 2 Process Far Exchange Data Indication MSU Figure 5. Notification of an Incoming Data Packet During data transfer, the user application may request layer 2 to apply flow control to a link (or to stop flow control) by sending a FLOW request. There is no response from layer 2 back to the user application for this request. Layer 2 may also send an unsolicited FLOW INDICATION message to the user application to indicate that congestion has started or ended on a link Status/Control The MTP 2 status request supports a number of functions which help layer 3 implement link and traffic management procedures.the layer 3 application may use the status request to perform the following functions. Æ Retrieve the current BSN (last acknowledged sequence number) for a link (useful in implementing changeover procedures). Æ Retrieve all MSUs transmitted on a link but not yet acknowledged (also useful in implementing changeover procedures). Æ Request MTP 2 to drop all queued messages. Æ Notify MTP 2 of an emergency on or off condition on a link. Æ Notify MTP 2 of a local processor up or down condition (passed on to the far exchange). NMS Communications 23

24 Chapter 2 Getting Started MTP 2 returns a STATUS CONFIRMATION message containing the current BSN (last acknowledged sequence number) for a link to the application in response to a "retrieve BSN" status request. MTP 2 may also return a STATUS CONFIRMATION message in response to a "retrieve messages" status request, but only if there are no unacknowledged messages to be retrieved. If there are unacknowledged messages to be retrieved, a DATA CONFIRMATION indicating a status of "unacknowledged [more last]" is sent to the application for each message (the last indicates that it is the last). In this case, no STATUS CONFIRMATION message is returned to the application. Application (Layer 3) MTP 2 SAP (Failed Link) MTP 2 SAP (Good Link) Far Exchange Disconnect Ind Status Rqst (Retrieve BSN) Status Confirm (BSN) Data Rqst (Changeover Order) Data Indication (Changeover Ack) Status Rqst (Retrieve Msgs) COO COA Data Confirm (Unack d/more) Data Confirm (Unack d/last) Data Rqst (Resend)... MSU Figure 6. Use of "Retrieve" Status Requests to Implement Link Changeover 24 NMS Communications

25 Connection Clearing Connection Clearing The user application may request that the link be disabled by sending a DISCONNECT request to layer 2. There is no response from layer 2 to a DISCONNECT request. Layer 2 may send an unsolicited DISCONNECT INDICATION to the user application to notify it that a link has been disconnected and the reason for the disconnect. Layer 2 will send unsolicited STATUS INDICATION messages to the user application to notify it of changes in the link status (up or down). 2.8 MTP 2 Messages The following messages comprise the interface to the SS7 layer 2 task. All messages contain a message type and a link ID in addition to the parameters listed in the following table. Actual message layouts are specified in Appendix A. Message Direction Parameters Description BIND REQUEST MTP3 -> MTP2 Service User ID Service Prov. ID User Entity ID User Instance ID Binds user application as sole user of SS7 layer 2 link. CONNECT REQUEST CONNECT CONFIRM MTP3 -> MTP2 Status Requests layer 2 to bring up a physical link. Status parameter may be used to specify status to bring link up in (for example, normal, emergency, or power on only). MTP2 -> MTP3 None Notifies user application that link connect has successfully completed (link is aligned). DATA REQUEST MTP3 -> MTP2 Data buffer Requests layer 2 to transmit data buffer on a particular link. DATA CONFIRM MTP2 -> MTP3 Status Credit Acknowledges transmission of a data request back to user application; Status parameter indicates whether more DATA requests may be issued, Credit parameter indicated how many requests are being acknowledged. NMS Communications 25

26 Chapter 2 Getting Started Message Direction Parameters Description DATA INDICATION MTP2 -> MTP3 Data buffer Indicates received data packet to user application. DISCONNECT REQUEST DISCONNECT INDICATION MTP3 -> MTP2 Reason Requests layer 2 to disconnect a link. MTP2 -> MTP3 Reason Notifies user application that a link is disconnected. FLOW REQUEST MTP3 -> MTP2 Action Requests layer 2 to start or stop flow control on a link. FLOW INDICATION MTP2 -> MTP3 Action Notifies user application that congestion has started or stopped on a link. STATUS REQUEST MTP3 -> MTP2 Action Status Requests special status/control function. STATUS CONFIRM MTP2 -> MTP3 Action Status Response to status request for certain status/control functions. STATUS INDICATION MTP2 -> MTP3 Status Notifies user application that a link has gone up or come down. 26 NMS Communications

27 Chapter 3 MTP 2 Management Alphabetical Function Reference 3.1 Introduction 28 Mtp2GetLinkCfg 29 Mtp2InitLinkCfg 30 Mtp2LinkStats 37 Mtp2LinkStatus 39 Mtp2MgmtCtrl 42 Mtp2MgmtInit 43 Mtp2MgmtTerm 44 Mtp2SetLinkCfg 45 NMS Communications 27

28 Chapter 3 MTP 2 Management Alphabetical Function Reference 3.1 Introduction This chapter provides a comprehensive, alphabetically-ordered reference to the MTP 2 management API functions. A prototype of each function is shown with the function description, details of all arguments, and return values. Some of the fields in the function definition include: Prototype The prototype is shown followed by a listing of the function s arguments. NMS Communications data types include: Æ U8 Æ S16 Æ U32 Æ Bool Æ 8-bit unsigned Æ 16-bit signed Æ 32-bit unsigned Æ 8-bit unsigned If a function argument is a data structure, the complete data structure is defined. Return Values The return value for a function is either MTP2_SUCCESS or an error code. For asynchronous functions, a return value of MTP2_SUCCESS (zero) indicates the function was initiated; subsequent events indicate the status of the operation. 28 NMS Communications

29 Mtp2GetLinkCfg Mtp2GetLinkCfg Description Prototype Obtains the current data link configuration values of the specified link number. MTP2_STATUS Mtp2GetLinkCfg (U8 board, MTP2LinkCfg *plinkcfg, S16 linkno) Return Values board plinkcfg linkno MTP2_SUCCESS The TX board number on which the desired MTP 2 task resides. A pointer to an MTP2LinkCfg structure where the data link configuration values will be filled. The link number to obtain configuration information for (0 to maximum number of links - 1). MTP2_BOARD Invalid board number specified. MTP2_HANDLE Mtp2MgmtInit was never called for specified board. MTP2_TIMEOUT No response from board. Details This function obtains the current data link configuration parameters of the specified link on the specified board. An application must provide a pointer to a buffer large enough for the MTP2LinkCfg structure. This function may be called any time after Mtp2MgmtInit. Refer to the MTP2LinkCfg structure in the Mtp2InitLinkCfg reference for more information about its fields. NMS Communications 29

30 Mtp2InitLinkCfg Mtp2InitLinkCfg Description Prototype Initializes the data link configuration structure provided with default values and the link number and link type specified. MTP2_STATUS Mtp2InitLinkCfg (U8 board, MTP2LinkCfg *plinkcfg, S16 linkno, U8 linktype) board plinkcfg linkno linktype The TX board number on which the desired MTP 2 task resides. A pointer to the MTP2LinkCfg structure to be initialized. The link number to assign to this data link. This value must be from 0 to the maximum number of links-1 (Depends on hardware configuration). The type of link. This is one of: MTP2LNK_ANSI MTP2LNK_ANSI88 MTP2LNK_CCITT Return Values MTP2_SUCCESS MTP2_LNKTYPE Invalid link type specified. Details This function is provided as a quick way for an application to initialize an MTP2LinkCfg structure before calling Mtp2SetLinkCfg to set the data link configuration parameters. Mtp2InitLinkCfg sets the link number and link type as specified and initializes all other fields in the Mtp2SetLinkCfg structure to their defaults. 30 NMS Communications

31 Mtp2InitLinkCfg The following structures are used for individual data link configuration in the MTP 2 task. Typically, a pointer to an MTP2LinkCfg structure is passed to Mtp2InitLinkCfg where default values are set. These defaults are specified in the following table. If there is no default, the field is either unused or its value is passed as a parameter to Mtp2InitLinkCfg. In the latter case, the parameter name is specified in the table. After initialization, an application may override zero to all of these values and then pass the pointer to Mtp2SetLinkCfg, which actually sets the configuration. Most of the default values provided by Mtp2InitLinkCfg will be adequate for most applications. typedef struct _MTP2LinkCfg /* MTP level 2 data link SAP configuration */ { MemoryId mem; /* memory region and pool id */ MemoryId memmac; /* memory region and pool id for MAC */ S16 swtch; /* protocol type */ U8 priordl; /* priority for data link layer */ U8 routedl; /* route for data link layer */ U8 selectordl; /* upper interface selector */ U8 entmac; /* entity for MAC */ U8 instmac; /* instance for MAC */ U8 priormac; /* priority for MAC layer */ U8 routemac; /* route for MAC layer */ U8 selectormac; /* lower interface selector */ U8 maxoutsfrms; /* maximum outstanding frames */ Bool errtype; /* cyclical or normal error checking */ TimerCfg t1; /* timer 1 configuration structure */ TimerCfg t2; /* timer 2 configuration structure */ TimerCfg t3; /* timer 3 configuration structure */ TimerCfg t5; /* timer 5 configuration structure */ TimerCfg t6; /* timer 6 configuration structure */ TimerCfg t7; /* timer 7 configuration structure */ TimerCfg t10; /* timer 10 configuration structure */ TimerCfg t11; /* timer 11 configuration structure */ TimerCfg t12; /* timer 12 configuration structure */ TimerCfg t13; /* timer 13 configuration structure */ TimerCfg congtmr; /* congestion timer configuration structure */ U16 provemrgcy; /* emergency proving period */ U16 provnormal; /* normal proving period */ U8 lssulen; /* one or two byte LSSU length */ U8 align1; /* alignment byte */ U16 maxfrmlen; /* max frame length for MSU */ U8 cfmtype; /* when to send connect confirm */ Bool congdisc; /* congestion discard TRUE or FALSE */ U16 sdd; /* Error count decrement rate <JMP> */ U8 sdt; /* SUERM error rate threshold */ U8 sdtie; /* AERM emergency error rate threshold */ U8 sdtin; /* AERM normal error rate threshold */ NMS Communications 31

32 Mtp2InitLinkCfg U8 sdn1; /* maximum number of MSUs for retransmission */ U16 sdn2; /* maximum number of MSU octets for retrans */ U8 sdcp; /* maximum number of alignment attempts */ U8 align2; /* alignment byte */ S16 spidse; /* service provider id */ U16 dstprocid; /* processor id */ U16 isothresh; /* Number of packets to queue before sending * SIPOs */ U16 txqthresh1; /* Threshold level one on MTP2 s Tx Queue */ U16 txqthresh1abate; /* Abatement threshold for level two on * MTP2 s Tx Queue */ U16 txqthresh2; /* Threshold level two on MTP2 s Tx Queue */ U16 txqthresh2abate; /* Abatement threshold for level two on * MTP2 s Tx Queue */ U16 sapthresh; /* Threshold level on MTP2 s upward bound * SAP queue */ U16 sapthreshabate; /* Abatement threshold level for MTP2 s * SAP Queue */ /* MTP level 1 parameters <JMP> */ S16 baud; /* baud rate (4.8, 9.6, 19.2, 28.8, 38.4, * 56, 64) */ U8 portnum; /* port number */ U8 porttype; /* port type */ S16 physinttype; /* Physical interface type (DCE/DTE) */ U8 dataencoding; /* Data encoding (NRZ/NRZI) */ U8 flgshare; /* Share flags? */ U8 flgidle; /* Use idles (True) or flags (False) */ U8 numflg; /* Number of additional flag chars /* between frames */ U32 idlefreq; /* Transmit frequency of FISU s when done by */ /* software (in ms). Done at config */ U32 rtfreq; /* Retransmit frequency of other SU s when */ /* done by software (in ms). Done at transmit */ } MTP2LinkCfg; 32 NMS Communications

33 Mtp2InitLinkCfg Fields that do not appear in the following table are either unused or for internal use only. Those fields should not be modified by the user. Unless otherwise specified, the timer names correspond to the CCITT specification. Differences from the ANSI and/or CCITT specification are noted in parentheses in the description. Note: All timer values are specified in tenths of a second. Field Name Default Range Description swtch linktype parameter MTP2LNK_ANSI, MTP2LNK_ANSI88, or MTP2LNK_CCITT Protocol type. maxoutsfrm 2 Maximum outstanding frames to layer MTP 1. errtype ERR_NRM ERR_NRM or ERR_CYC Normal or cyclical (for PCR) error checking. t1 t2 t3 130 (ANSI) 400 (ITU) 115 (ANSI) 100 (ITU) 115 (ANSI) 15 (ITU) 1 to Timer aligned/ready. 1 to Timer not aligned. 1 to Timer aligned. t5 1 1 to Timer sending SIB. t to Timer remote congestion. t to Timer excessive delay of acknowledgement. t to Amount of time MTP 2 can be isolated from a remote MTP 3 before sending processor outage (SIPO). t to Time to wait for a flow control acknowledgement from MTP 3 before sending another flow control indication. NMS Communications 33

34 Mtp2InitLinkCfg Field Name Default Range Description t to Time to wait for a status confirmation from MTP 3 before sending another status indication. t to Time to wait for a disconnect confirmation from MTP 3 before sending another disconnect indication. provnormal provemrgcy 23 (ANSI) 82 (ITU) 6 (ANSI) 5 (ITU) 1 to Normal proving period. 1 to Emergency proving period. lssulen 2 1 or 2 One or two byte LSSU length. maxfrmlen to 1024 Max frame length for MSU. congdisc FALSE TRUE FALSE Congestion discard. sdt 64 1 to 255 SUERM error rate threshold. sdd to SUERM decrement rate. sdtie 1 1 to 255 AERM emergency error rate threshold. sdtin 4 1 to 255 AERM normal error rate threshold. sdn to 255 Max # of MSUs for retransmission (when using PCR). sdn to Max # of MSUs octets for retrans (when using PCR). sdcp 5 1 to 255 Maximum # of proving failures. 34 NMS Communications

35 Mtp2InitLinkCfg Field Name Default Range Description baud BD_56000 BD_4800, BD_9600, BD_19200, BD_28800, BD_38400, BD_48000, BD_56000, BD_64000 physinttype INT_DTE INT_DTE INT_DCE INT_DTE_MODEM INT_DCE_MODEM Baud rate (4.8, 9.6, 19.2, 28.8, 38.4, 48, 56, or 64). Physical interface type (DCE/DTE) with or without modem signal detection. Modem signal usage is the only way to assure detection of connection loss and reestablishment. Note: Modem signal detection requires an additional pod jumper on the DCE side connecting DSR and CD. dataencoding DAT_NRZ DAT_NRZ DAT_NRZ1 Data encoding (NRZ/NRZI). flgshare FLAG_SHARE FLAG_SHARE NO_FLAG_SHARE Share flags between frames. FlgIdle FALSE TRUE FALSE Use idles (True) or flags (False). numflg 0 0 to 15 Number of additional flag chars between frames. isothresh to Number of messages queued to MTP 3 while isolated that will cause MTP 2 to begin processor outage (SIPOs). txqthresh to Transmission queue length at which the outbound flow control level is raised to one. txqthresh1abate 20 1 to Transmission queue length at which the outbound flow control level is lowered to zero. NMS Communications 35

36 Mtp2InitLinkCfg Field Name Default Range Description txqthresh to Transmission queue length at which the outbound flow control level is raised to two. The subsequent indication causes MTP 3 to cease all transmission to MTP 2 until the flow control level returns to one or zero. txqthresh2abate to Transmission queue length at which the outbound flow control level is lowered to one. sapthresh to Number of messages queued to MTP 3 while inbound flow control is in effect that will cause MTP 2 to send busy indications (SIBs). sapthreshabate to Number of messages queued to MTP 3 while inbound flow control is in effect that will cause MTP 2 to stop sending busy indications (SIBs). idlefreq 0 1 to Transmit frequency of FISU s when done by software (in ms). rtfreq 0 1 to Retransmit frequency of other SU s when done by software (in ms). 36 NMS Communications

37 Mtp2LinkStats Mtp2LinkStats Description Prototype Obtains (and potentially resets) data link statistical information about the specified link number. MTP2_STATUS Mtp2LinkStats (U8 board, S16 linkno, MTP2LinkStats *pstats, BOOL breset) Return Values board linkno pstats breset MTP2_SUCCESS The TX board number on which the desired MTP 2 task resides. The link number to obtain statistical information about. The link number must have been previously defined through the Mtp2SetLinkCfg function. A pointer to a buffer provided by the application where the requested statistical information will be returned. Refer to the MTP2LinkStats structure. If true (non-zero), the statistics are reset (set to zero) after returning the current values. If false (zero) no reset is performed. MTP2_BOARD Invalid board number specified. MTP2_HANDLE Mtp2MgmtInit was never called for specified board. NMS Communications 37

38 Mtp2LinkStats Details There are a large number of link statistics. They include counts for the various message types and their acknowledgments both transmitted and received. All counts are U32 fields. Refer to the following MTP2LinkStats structure. typedef struct _Mtp2LinkStats /* MTP Level 2 link statistics */ { U32 inservice; /* start of in-service */ U32 lclbusy; /* duration of local-busy */ U32 slfailall; /* all reasons for a signaling link * failure */ U32 slfailab; /* Abnormal FIBR/BSNR link failure */ U32 slfailack; /* delay of acknowledgment link * failure */ U32 slfailerr; /* excessive error rate link failure */ U32 slfailcong; /* excessive congestion link failure */ U32 slfailalign; /* alignment link failure */ U32 slnsuerr; /* number of signal units in error */ U32 slnegack; /* number of negative acknowledgments */ U32 nsifsiotx; /* number of SIF/SIO packets * transmitted */ U32 nretrans; /* number of octets transmitted */ U32 mtx; /* information frames transmitted */ U32 ltx; /* receive ready frames transmitted */ U32 ftx; /* receive not ready frames * transmitted */ U32 nsifsiorx; /* number of SIF/SIO packets received */ U32 mrx; /* information frames received */ U32 lrx; /* receive ready frames received */ U32 frx; /* receive not ready frames received */ U16 txcnt; /* Number of messages on the transmit */ /* queue */ U16 hitxcnt; /* Hiqh water number of messages on */ /* the transmit queue */ U16 rtbcnt; /* Number of messages on the */ /* retransmit queue */ U16 hirtbcnt; /* Hiqh water number of messages on */ /* the retransmit queue */ U16 ltxcnt; /* Number of messages on the lower */ /* transmit queue */ U16 hiltxcnt; /* Hiqh water number of messages on */ /* the lower transmit queue */ U16 sapcnt; /* Number of messages on the inbound */ /* sap queue */ U16 hisapcnt; /* Hiqh water number of messages on */ /* the inbound sap queue */ } MTP2LinkStats; 38 NMS Communications

39 Mtp2LinkStatus Mtp2LinkStatus Description Prototype Obtains data link status information about the specified link number. MTP2_STATUS Mtp2LinkStatus (U8 board, S16 linkno, MTP2LinkStatus *pstatus) Return Values board linkno pstatus MTP2_SUCCESS The TX board number on which the desired MTP 2 task resides. The link number to obtain status information about. The link number must have been previously defined through the Mtp2SetLinkCfg function. A pointer to a buffer provided by the application where the requested status information will be returned. Refer to the MTP2LinkStatus structure. MTP2_BOARD Invalid board number specified. MTP2_HANDLE Mtp2MgmtInit was never called for specified board. Details This function obtains link status information about the specified link number. This information includes the link state, flow control state, queue sizes, and busy states. Refer to the following MTP2LinkStatus structure for detailed information: NMS Communications 39

40 Mtp2LinkStatus This structure is filled by the MTP 2 task in response to an Mtp2LinkStatus request. typedef struct _Mtp2LinkStatus /* MTP Level 2 - signaling link status */ { DateTime DT; /* Date / time stamp */ U8 hlst; /* sap state */ U8 psoutsfrm; /* outstanding frames to MAC */ S16 cntmadrop; /* frames dropped by MAC */ U8 llst; /* link level matrix state */ U8 lclbsy; /* local busy */ Bool rembsy; /* remote busy */ U8 fsn; /* forward sequence number */ U8 bsn; /* backward sequence number */ U8 flcst; /* flow control state */ } MTP2LinkStatus; Field Name Possible values Description hlst ST_UNBOUND, ST_CONFIGURED, ST_BND_DISABLED, or ST_BND_ENABLED Sap State psoutsfrm 0 to 0xFF Outstanding frames to MAC. cntmadrop 0 to 0xFFFF Frames dropped by MAC. llst ST_UNUSED, ST_OUT_OF_SERVICE, ST_INITIAL_ALIGNMENT, ST_ALIGNED_READY, ST_ALIGNED_NOT_READY, ST_PROC_OUT, ST_IN_SERVICE, ST_IDLE, ST_NOT_ALIGNED, ST_IS_ALIGNED, ST_PROVING, ST_LOCAL_PROC_OUT, ST_REMOTE_PROC_OUT, ST_BOTH_PROC_OUT, ST_MONITORING, ST_CONGESTION, or ST_POWER_OFF Link level matrix state. lclbsy TRUE FALSE Indicates whether the local MTP2 is sending SIB s. rembsy TRUE FALSE Indicates whether the remote MTP2 is sending SIB s. fsn 0 to 127 Last forward sequence number sent. 40 NMS Communications

41 Mtp2LinkStatus Field Name Possible values Description bsn 0 to 127 Backward sequence number to send next. flcst 0 to 2 Outbound flow control level (2 = congested). NMS Communications 41

42 Mtp2MgmtCtrl Mtp2MgmtCtrl Description Prototype Sends a control request to the MTP 2 task. MTP2_STATUS Mtp2MgmtCtrl (U8 board, S16 entity, U8 action) board entity action The TX board number on which the desired MTP2 task resides. Reserved for future use. The action to take on the entity specified, where action is one of the following: Return Values MTP2_SUCCESS MTP2_CTRL_FLOWCTL_ON Sets ALL links to the congested state (see Congestion Control section). MTP2_CTRL_FLOWCTL_OFF Returns all links to the non-congested state. MTP2_BOARD Invalid board number specified. MTP2_HANDLE Mtp2MgmtInit was never called for specified board. MTP2_PARAM Invalid action specified. Details There is currently one classification: flow control requests. 42 NMS Communications

43 Mtp2MgmtInit Mtp2MgmtInit Description Initializes internal structures and opens communication with the MTP 2 process on the TX board. Prototype MTP2_STATUS Mtp2MgmtInit (U8 board, U8 srcent, U8 srcinst) board The TX board number. srcent The source entity ID. srcinst The source instance ID. Return Values MTP2_SUCCESS MTP2_BOARD Invalid board number specified. MTP2_DRIVER Low level driver returned an error trying to open the specified dual port RAM channel. srcent should be from 0x20 to 0x31 and cannot be in use by another application. Details This function must be called before any other management primitive can be used. Source entity must be unique for each application accessing the MTP 2 (or other) task. Note: An application that opens both the management and data APIs must use different entity IDs for the Mtp2MgmtInit and Data Bind Request calls. NMS Communications 43