5.1 Developing GR-303 Applications

5.2 NMS GR303 Library Overview

5.3 Using the NMS GR303 Library

5.3.1 Initializing the NMS GR303 Library

5.3.2 Provisioning an NMS GR303 Interface

5.3.3 Starting and Monitoring an NMS GR303 Interface

5.3.4 Modifying an NMS GR303 Interface

5.3.5 Reprovisioning an NMS GR303 Interface

5.3.6 Sending and Receiving HDLC Channel Data

5.3.7 Retrieving Channel and Link Status Information

5.3.8 Stopping an NMS GR303 Interface

5.3.9 Destroying an NMS GR303 Interface

5.3.10 Exiting the NMS GR303 Library

5.3.11 NMS GR303 Library State Diagram

5.4 Access303, Exchange303, and NMS GR303 Functions

5.4.1 Initializing an Interface

5.4.2 Stopping and Restarting Without Reprovisioning

5.4.3 Stopping, Reprovisioning, and Starting

5.4.4 Modifying Standby Locations

5.1 Developing GR-303 Applications

The Platform Support for DLCP product provides a set of software APIs that enable applications to access on board devices (HDLC controllers and framers) necessary to support the upper layers of the GR-303 protocol. If the RDT
application requires additional functionality that is beyond the scope of the Platform Support for DLCP libraries (for example, robbed-bit signaling or a lower level switching fabric), developers can use other NMS products to access this functionality.

Note: The Platform Support for DLCP software is designed to work with the Aztek's Access303 or Exchange303 stack, but can also be integrated with third party GR-303 stack software.

5.2 NMS GR303 Library Overview

This section describes the operation states of the Platform Support for DLCP software. Platform Support for DLCP software represents the physical layer of the GR-303 protocol and provides applications with a set of GR-303 protocol-specific API functions. Applications can use these functions to support the upper layers of the GR-303 interface and to control HDLC and framer devices.

HDLC device controllers perform the following tasks:

• Dynamically create and destroy HDLC instances

• Initialize and reset HDLC instances

• Activate and deactivate HDLC instances

• Control the transmission and reception of HDLC frames

• Perform statistics monitoring and configuration tasks

• Control the transmission of asynchronous events and error reports

Framer device controllers perform the following tasks:

• Monitor T1 links for alarms and errors

• Control T1 links statistics queries and configuration

• Configure signaling operation modes (CAS or RAW mode) on a
  per-timeslot basis

5.3 Using the NMS GR303 Library

Developers can use NMS hardware and software and Platform Support for DLCP NMS GR303 library functions to create remote digital terminal (RDT) or integrated digital terminal (IDT) applications that perform the following tasks:

• Configure T1 boards.

• Configure up to four HDLC controllers per GR-303 interface.
  DS0 and DS1 locations for HDLC links are application-configurable, but for RDT applications must set these links to occupy timeslots 24 and 12 on two different T1 links.

• Perform automatic internal switching between CAS and RAW signaling modes when configuring HDLC channels.

• Send and receive HDLC data and transfer result reports.

• Provide buffering for outgoing and incoming messages on each HDLC data channel.

• Support ABCD robbed-bit signaling on a per timeslot basis.

• Support the switching fabric required for the TSI interface of the GR-303 protocol.

• Provide library tracing capabilities.

The NMS GR303 library also provides physical layer access to the upper layers of the Aztek Access303 protocol stack. NMS GR303 library functions allow applications to perform the following tasks:

Tasks	Library Functions
Managing the physical interface	· Initialize the software · Provision HDLC interfaces · Start and stop HDLC interfaces · Modify provisioned HDLC interfaces · Perform status and statistics queries
HDLC transmit and receive operations	· Send LAPD frames to HDLC channels · Receive LAPD frames from HDLC channels

5.3.1 Initializing the NMS GR303 Library

When the GR-303 system starts up, the application must invoke NMS_GR303Initialize to load the NMS GR303 library, start the library's internal processing tasks, and initialize its internal software structures.

Applications can invoke NMS_GR303SetTrace any time after loading the physical library. Arguments for NMS_GR303SetTrace specify the level of tracing performed by the library, and whether the library returns tracing information to the application or logs the information in a file.

5.3.2 Provisioning an NMS GR303 Interface

After initializing the NMS GR303 library, applications call NMS_GR303ProvisionInterface to specify the hardware-specific HDLC channel locations, configure HDLC data processing function callbacks, and allocate memory for receiving data from the physical layer. The NMS GR303 library configures and resets HDLC channels on the board, begins monitoring DS1 links associated with HDLC channels, and resets any internal statistics structures. The NMS GR303 library automatically sets the signaling mode to RAW for timeslots occupied by the HDLC channels.

Applications must start the provisioned interface to enable data to flow through HDLC channels. The NMS GR303 library starts to monitor DS1 links as soon as the links are provisioned. Therefore, applications can call NMS_GR303GetDS1Status and NMS_GR303ResetDS1Status to obtain DS1 link status information or reset the status of existing DS1 links.

NMS recommends that applications provision and start the upper layers of the GR-303 protocol after starting the NMS GR303 physical layer interface with NMS_GR303StartInterface. In some cases, the upper layers of the stack can expect incoming HDLC traffic after the interfaces are provisioned but before they are started.

GR-303 applications must establish a mapping between the physical layer structures for hardware-specific HDLC device locations and upper layer GR-303 protocol related structures. Because the physical layer is not aware of the protocol association for each hardware resource (for example, whether the DS1 link is active or standby mode, or whether a DS0 link is carrying EOC or TMC data) the application should map this information for the upper layers of the GR-303 protocol stack.

5.3.3 Starting and Monitoring an NMS GR303 Interface

After provisioning the NMS GR303 interface, applications invoke NMS_GR303StartInterface to start each interface. When the application starts the interface, the HDLC channels provisioned on the interface become operational and data begins to flow through the associated T1 links. When the IDT on the local exchange side of the interface is connected and started, the application can expect LAPD data. The application can invoke the NMS_GR303PhSendData to transfer data from the upper layers of the GR-303 stack to the physical layer. When the application invokes NMS_GR303PhSendData, the NMS GR303 library layer then sends the data to the specified HDLC channel.

Applications can invoke NMS_GR303GetDS1Status and NMS_GR303ResetDS1Status to obtain or reset status information associated with DS1 links, and NMS_GR303GetChannelStatistics and NMS_GR303ResetChannelStatistics to access or reset statistical information associated with HDLC channels.

5.3.4 Modifying an NMS GR303 Interface

The NMS GR303 library allows the application to add or modify HDLC channel locations on the interface at the physical layer without stopping and
reprovisioning the interface. Applications can use NMS_GR303ModifyChannelLocation to change the location of any provisioned HDLC channel or to add HDLC data links to a provisioned interface (when there are less than four existing provisioned channels).

Applications cannot remove existing channels from a provisioned interface. To reduce the number of HDLC channels at the physical layer, the application must destroy the existing interface, and then reprovision the interface with a smaller number of channels.

5.3.5 Reprovisioning an NMS GR303 Interface

In order to reprovision an interface, applications perform the following steps:

1. Stop the interface (if it is started) with NMS_GR303StopInterface.

2. Destroy the current interface with NMS_GR303DestroyInterface.

3. Reprovision the interface with NMS_GR303ProvisionInterface.

4. Start the interface NMS_GR303StartInterface.

Whenever possible, it is simpler to modify an interface with NMS_GR303ModifyChannelLocation than to destroy it and reprovision a new one.

5.3.6 Sending and Receiving HDLC Channel Data

After starting an interface, applications can invoke NMS_GR303PhSendData to asynchronously send data to a specific HDLC channel. The NMS GR303 library returns transfer request results to the application as soon as the data transfer is complete, and if necessary, performs any buffering necessary to transfer the data.

If the outgoing message queue overflows, the NMS GR303 library returns an EVENT_TX_QUEUE_FULL notification error. The library uses an
application-defined callback function to transfer the HDLC error message data from the physical layer to the application. The library copies the data into memory that was allocated when the application provisioned the interface.

5.3.7 Retrieving Channel and Link Status Information

As soon as an application provisions an interface, the NMS GR303 library begins to monitor any DS1 links that carry provisioned HDLC channels, and to maintain channel statistics for the channels.

Applications can query link status and channel statistic information by invoking NMS_GR303GetChannelStatistics and NMS_GR303GetDS1Status. NMS_GR303GetDS1Status returns current DS1 link alarm status information and error information collected over a specified period of time. NMS_GR303GetChannelStatistics reports success and error information for receive and transmit operations on a specified HDLC channel.

To reset DS1 link status information or HDLC channel statistics, applications should invoke NMS_GR303ResetChannelStatistics or NMS_GR303ResetDS1Status.

5.3.8 Stopping an NMS GR303 Interface

RDT applications can call NMS_GR303StopInterface to stop an existing interface. When the interface stops, all HDLC data transfer through the interface ceases, and the interface remains provisioned but not operational.

The NMS GR303 library continues to monitor DS1 links on stopped interfaces, and the library does not automatically reset HDLC channel statistics for these links. Therefore, applications can still access or reset DS1 link statistics for stopped interfaces by invoking NMS_GR303GetChannelStatistics or NMS_GR303ResetChannelStatistics.

To restart a stopped interface, an application must call NMS_GR303StartInterface.

5.3.9 Destroying an NMS GR303 Interface

Applications invoke NMS_GR303DestroyInterface to destroy an existing interface. When an application destroys an interface, the HDLC flow of data ceases, provision information is destroyed, and the NMS GR303 library stops maintaining statistics information for any DS1 links and HDLC channels associated with the interface.

NMS_GR303DestroyInterface also resets the signaling mode of timeslots formerly occupied by the HDLC channels to CAS mode.

5.3.10 Exiting the NMS GR303 Library

To exit the RDT system, applications call NMS_GR303Exit. When an application calls NMS_GR303Exit, the NMS GR303 library stops all provisioned HDLC and framer instances, configures the signaling mode of any timeslots associated with HDLC channels back to CAS, and destroys all existing interfaces.

Exiting the GR-303 application gracefully (that is, invoking NMS_GR303StopInterface and NMS_GR303DestroyInterface before invoking NMS_GR303Exit) brings the board to a known state as required by the GR-303 protocol. This allows the RDT application to restart without rebooting the board.

5.3.11 NMS GR303 Library State Diagram

Figure 7 shows a state diagram for interfaces controlled by the NMS GR303 library. Developers must comply with the illustrated conditions when integrating NMS GR303 library functions into GR-303 applications.

Figure 7. NMS GR303 Interface State Transitions

The following table describes the NMS GR303 library interface states:

State	Description
Null	The board is booted, configured, and initialized, but the NMS GR303 library is not loaded.
Idle	The NMS GR303 physical library is initialized. No communication link is established between the GR-303 application and the boards. Library tracing can be configured.
Provisioned	The interface is provisioned on the physical layer. All necessary connections are made between the application and HDLC/framer instances on the boards. HDLC channels are configured, reset, and initialized, but disabled for transmit and receive operations. DS0 timeslots assigned to HDLC channels are internally set to RAW mode. All other DS0 timeslots remain in CAS mode. Applications can query the status of HDLC channels and DS1 links, modify provisioned interface configurations, and modify the tracing configuration.
Started	The HDLC channels are enabled for transmit and receive operations. Applications can query the status of HDLC channels and DS1 links, modify provisioned interface configurations, and modify the tracing configuration.

5.4 Access303, Exchange303, and NMS GR303 Functions

The following diagrams illustrate scenarios for combining Aztek Access303 or Exchange303 library functions with NMS GR303 library functions to perform interface management and to conduct LAPD data communication over T1 connections. In these diagrams, solid arrows represent commands and dotted arrows represent data transfer.

Refer to the Aztek Access303 or Exchange303 documentation more information about Aztek GR-303 library functions.

5.4.1 Initializing an Interface

The following diagram shows functions used to initialize a GR-303 interface for the RDT application:

Figure 8. Initializing a GR-303 Interface

5.4.2 Stopping and Restarting Without Reprovisioning

The following diagram shows functions used to the stop and restart an GR-303 interface without reprovisioning layer 1:

Figure 9. Stopping and Starting a GR-303 Interface Without Reprovisioning

5.4.3 Stopping, Reprovisioning, and Starting

The following diagram shows functions used to stop, reprovision all layers, and start a GR-303 interface:

Figure 10. Stopping, Reprovisioning, and Starting a GR-303 Interface

5.4.4 Modifying Standby Locations

The following diagram shows functions used to modify GR-303 interface standby locations without stopping the interface:

Figure 11. Modifying Interface Standby Locations