(Page 1 of 1 in this chapter)


Chapter 5

Packet Network Interface Control


5.1 Introduction
5.2 TX Series Functionality
5.3 Managing the Packet Network Interface
5.3.1 Initializing and Configuring the Packet Network
5.3.2 Responding to Incoming Voice
5.3.3 Controlling Network
5.4 Using TX Series APIs
5.4.1 Downloading Programs to the TX
5.5 Configuring Virtual Ports
5.5.1 Opening the Virtual Port
5.5.2 Setting the MVIP Clock
5.5.3 Defining Virtual Port
5.5.4 Configuring Virtual Port
5.5.5 Defining Virtual
5.5.6 Virtual Port Example
5.5.7 Configuring TX Board
5.5.8 Using TX Board Level
5.6 Controlling RTP/RTCP Sessions
5.6.1 Managing RTP
5.6.2 UDP Port Number
5.6.3 RTP Sessions
5.6.4 Initializing RTP
5.7 Programming Guidelines
5.7.1 Multiple TX Boards in a Single PC
5.7.2 Multiple Call Control Protocols in a Single
5.7.3 Using Simplex Streams with
5.7.4 Using Multi-Purpose TX
5.8 H.323 Stack API
5.8.1 H.323 Call Control State

5.1 Introduction

Fusion gateway applications use TX Series hardware and software APIs to control the flow of data to and from a packet network. This chapter provides an overview of how gateway applications use TX Series APIs to configure and manage the packet network interface. The chapter also describes how to use the Fusion H.323 stack in combination with the TX Series APIs, in order to control packet network half-calls,

Note: Host-based Fusion systems use a different model for controlling the packet network interface. For more information about the model, refer to the Host-based Fusion Developer's Reference Manual.

Figure 21. Packet Network Interface Control

5.2 TX Series Functionality

The TX Series of hardware can provide the following types of interfaces to the packet network:

The TX Series network interface boards provides data interfaces for IP over Ethernet services. The control interface is composed of a series of APIs and libraries. The data interface uses an NDIS Communication Processor Interface (CPI) driver that enables the host operating system's TCP/IP Stack to use the TX board as a standard Network Interface Card (NIC).

Note: Windows NT provides the interface to its own TCP/IP stack.

5.3 Managing the Packet Network Interface

Fusion applications use TX series APIs to perform two sets of tasks:

  1. Download and configure static information to the TX board. Perform this step during either system or application initialization. If the Fusion gateway application loads and configures the TX board, it should do this at the same time that it initializes the PSTN interface.

    
    
  2. Control connections between voice streams and remote IP nodes. Connections are set up and torn down dynamically based on incoming calls/sessions, available resources, and the PSTN and IP call setup and termination protocols.

5.3.1 Initializing and Configuring the Packet Network Interface

To initialize the TX board and its software:

  1. Load all of the required software onto the TX board.

    
    
  2. Initialize the CPI libraryI used to communicate with the TX.

    
    
  3. Create and enable a TPX Ethernet interface.

    
    
  4. If required, define a default route to another router.

    
    
  5. Define and configure resources and virtual ports.

Refer to the TX series documentation for further information about loading and configuring TX Series software.

5.3.2 Responding to Incoming Voice Data

RTP and RTCP are protocols for controlling the transmission of real time audio and video data to and from packet switched networks. Fusion gateway applications set up and terminate gateway connections based on call setup and termination operations that occur on the PSTN and IP Network. The TX Series RTP/RTCP API provides functions for setting up and terminating connections between the PSTN data streams and a remote IP address.

To control RTP sessions:

  1. Establish and configure RTP sessions as needed in response to calls coming over the MVIP bus (from the PSTN interface), and from the packet network.

    
    
  2. Receive voice data from the MVIP bus (from calls originating at the PSTN interface), add IP, UDP, and RTP headers, and send the data to specific IP addresses.

    
    
  3. Receive data from the packet network interface, strip RTP, IP, and UDP headers, and direct the data to specific MVIP streams.

For more information about setting up RTP/RTCP connections, refer to Section 5.6 of this manual or to the TX Series RTP/RTCP Developers Guide.

5.3.3 Controlling Network Latency

Fusion applications use jitter buffer technology to manage the variable latency and sequencing characteristics of the packet data network. To better control these factors, the TX boards use a jitter buffer which stores a specified number of packets. These jitter buffer settings are programmable through TxRtpJbufCtlReq in the TX Series RTP API interface.

Setting the jitter buffer depth value determines the number of packets that the jitter buffer can hold. For example, in the case of G.723.1 (with 30ms buffers), one buffer provides one 30ms packet of buffering, while four packets provide 120ms of buffering. The max_hold_time value specifies the maximum time (in millisconds, with a 5 millisecond resolution) that the jitter buffer holds packets while waiting for the jitter buffer depth to be reached. For more information, refer to the TX Series RTP/RTCP Developers Guide.

A Fusion system can tolerate delays and out of sequence packets equivalent to the number of packets stored in the jitter buffer. However, as the depth of the jitter buffer grows so does the packet latency. To set a tolerable latency for your Fusion system, adjust the max_hold_time to the maximum amount of delay (in milliseconds) you require. If the jitter buffer fills up before the max_hold_time is reached, then play out will begin when the buffer is full. Otherwise, the first play out will begin when the max_hold_time value is reached.

Note: The jitter buffer depth is measured in number of packets and, depending on the packet type, can represent different amounts of voice data. However, the max_hold_time specifies the hold time in milliseconds and this is not effected by the amount of voice data in the packet.

5.4 Using TX Series APIs

Fusion provides several APIs for configuring and controlling operations on TX boards.
This API...

Provides functions to ...

Loader API

Configure the TX board environment to application requirements.

CPI Library

Send and receive board-level control requests, responses, and notifications from the TX board.

Common Management API

Configure, control, and examine the behavior of processes executing on the TX board. This includes support for full configuration and control of the TCP/IP and X.25 tasks.

Virtual Port API

Configure TX board communications resources to meet application requirements.

RTP/RTCP API

Connect and disconnect multimedia data streams to and from the MVIP bus and a packet network.

Note: Windows NT provides a interface to the native TCP/UDP/IP stack. The CPI library provides the network driver (NDIS) driver interface.

5.4.1 Downloading Programs to the TX Boards

When the TX board is initialized, TX program files are loaded into TX board memory. The Loader API provides functions for downloading TX program files to TX hardware. The application has complete control over when and how the TX board is initialized.

5.5 Configuring Virtual Ports

Before TX-based processes can use TX board communications resources, applications must configure virtual ports. Virtual ports are software entities that control specific resources on the TX boards.

When configuring the virtual ports, applications determine the following:

In Fusion gateway applications, AG TRAU channels use 128 kb channels on the MVIP bus to communicate with the TX board virtual ports. These hyperchannels carry voice data on different timeslots within a single MVIP stream. AG TRAU programs multiplex a number of voice channels over a single MVIP stream when passing the data to the TX board.

A demultiplexing address determines the MVIP stream and timeslot from which the virtual port receives data, and how the virtual port demultiplexes the data it receives. Use TxVpdAddrDef to define demultiplexing addresses for virtual ports.

5.5.1 Opening the Virtual Port API

To open the Virtual Port API use TxVpdOpen to open a data channel to the low layer OS driver for the TX board. All function calls between the TxVpdOpen and corresponding TxVpdClose call should be from the same thread.

5.5.2 Setting the MVIP Clock Configuration

Use TxVpdMvipCfg to set the MVIP clock configuration. Make sure you know the MVIP clocking parameters of other boards in the system when calling this function. In most cases, the primary MVIP clock is provided by another board in the system, in which case the TX board should be configured to reference the clock from the MVIP bus.

5.5.3 Defining Virtual Port Resources

Applications use the following functions from the TX Series Virtual Port API to define virtual ports resources:

The following example assumes a TX board with at least one QUICC32 Chip. Each QUICC32 can handle 32 separate time slots over the MVIP Bus. Since the Sample Gateway program uses bonded time slots of 2 MVIP channels, this provides 16 available resources per QUICC32.

Note: The number of voice connections supported by a particular TX board configuration is also determined by the amount of data the board can handle in packets-per-second. Exceeding this capacity can lead to packet loss in voice connections. Refer to your TX Series hardware documentation for more information about the board's bandwidth capacity in packet-per-second. Defining Resources

For voice over IP, virtual port resources have a connection type of TDM (Time Division Multiplexing). The Sample Gateway program defines 16 of these virtual port resources for use with a single QUICC32.

Take the following steps to define TX board virtual port resources. The first three steps set up fields in the virtual port resource structure. The fourth step defines the resources on the TX board.

  1. Pass a pointer to the resource structure to TxVpdResDflt. TxVpdResDflt initializes the entire structure with zero values, and then fills in relevant fields with default information.

    
    
  2. Set up protocol information for the port with TxVpdResDef. TxVpdResDef sets the type and number of hardware resources we are defining. It also specifies the protocol to use for that resource.

    
    TxVpdResDef takes the following parameters: 
    
    Parameter

    Description

    res

    Pointer to the resource structure to fill in.

    res_num

    Resource number to be defined. This can be any number.This example uses 1 - 16 (matching the loop variable).

    hw_type

    Type of hardware resource used. This example uses TXVPD_HWSCC to define a Serial Communication Controller resource.

    hw_num

    When QUICC32 mode is being used, 0 is used for the hardware number of all resources. This indicates to the TX board that QUICC32 resources are being defined.

    protocol

    The protocol to be used over this resource. in this example, HDLC is used for IP call control.

  3. Set virtual port TDM information with TxVpdResTdm.

    
    TxVpdResTdm sets up the resource as a Time Division Multiplexer stream. There are 32 timeslots (channels) per TDM stream so the Sample Gateway program assigns two timeslots per resource, all on stream 0.
    TxVpdResTdm takes the following parameters:
    Parameter

    Description

    res

    Pointer to the resource structure to fill in.

    stream

    MVIP Stream number. Can be 0 - 7 for standard direction, or 8 - 15 for reverse. The Sample Gateway program always uses 0.

    channel

    Starting channel (timeslot) number for this resource. The Sample Gateway program assigns 0, 2, 4, 6, 8, 10, 12...

    count

    Number of channels used by this resource. The Sample Gateway program uses two for a 128kb hyperchannel to the DSP resources.

  4. Use TxVpdDefine to define the virtual port resource on the TX board.

5.5.4 Configuring Virtual Port Resources

After defining TX virtual port resources, you must configure these resources. Defining resources identifies the physical hardware. Configuring resources identifies how that physical hardware is to be used. Dynamic resource definitions are commonly paired with a resource configuration. It is also possible to
re-configure a resource without re-defining the resource.

You cannot reconfigure a virtual port resource while the resource is in use. This process configures the resources that the Sample gateway program will use. The Sample Gateway program loops through each defined resource and configures them.

  1. Use TxVpdCfgDflt to initialize the configuration structure with the receive buffer size for this resource of 256 bytes.

    
    
  2. Use TxVpdConfig to perform the virtual port resource configuration.

5.5.5 Defining Virtual Ports

After configuring virtual port resources you need to define the virtual ports the application will use to communicate over the MVIP bus.

Loop through each resource we've defined and define three or four virtual ports per resource, depending on the encoding scheme specified.

  1. Use TxVpdAddrDef to set up the address structure used to define demultiplexing addresses for a virtual port.

    
    The demultiplexing address specifies what packets that port will receive. In the Sample Gateway program, packets are HDLC packets and for voice over IP the first byte in those packets will be between one and four. This allows four conversations (each using a separate virtual port) to take place over a single physical resource. 
    TxVpdAddrDef takes the following parameters:
    Parameter

    Description

    addr

    Pointer to the address structure to fill in..

    priority

    The priority of the virtual port. The Sample gateway program specifies 0xFF, which is high priority. There is also low and medium.

    flags

    The only flag currently defined is OverWrite (0x01). Use this for voice over IP

    num_addrs

    Specifies the number of demultiplexing address that this virtual port will receive. In the example one address is provided per virtual port so that conversations are not mixed. There can be up to four per virtual port.

    addrval

    First address value that this port will accept. This will be between one and four, one for each virtual port on this resource.

    addrval2

    Second address value that this port will accept. This is unused for voice over IP.

    addrval3

    First address value that this port will accept. This is unused for voice over IP.

    addrval4

    First address value that this port will accept. This is unused for voice over IP.

  2. Use TxVpdVport to define the virtual port on the TX board.

    
    TxVpdVport takes the following parameters: 
    
    Parameter

    Description

    handle

    Handle returned by TxVpdOpen.

    resource

    Resource number for associated with the virtual port. The example loops from 1 - 16.

    vport_num

    The number of the virtual port. Virtual port numbers to range from
    1 - 128.

    addr

    Pointer to the demuxing address structure provided in num_addrs of TxVpdAddrDef.

When finished defining the virtual port, use TxVpdClose to close the virtual port API.

5.5.6 Virtual Port Example Code

The following code sample demonstrates defining virtual ports (including demultiplexing addresses) based on AG TRAU program vocoder types:

printf ("Defining virtual ports\r\n");

  /* Loop through each resource defined and define 4 virtual ports */
    /* per resource, for a total of 64 virtual ports */
    for (i = 1; i <= 16; i++)
    {
        for (j = 1; j <= 4; j++)
        {
   // In this case the packets are HDLC packets. For 
   // voice over IP, the first byte in the packets will be 1 - 4 
   // specifying which virtual port gets which packets. This allows 4 
   // conversations (each using a separate virtual port) to take place 
   // over a single physical resource (an SCC).

    txstatus = TxVpdAddrDef( &addr, 0xFF, 0x01, 1, j, 0, 0, 0);
            if (txstatus != 0)
            {
     printf ("Demux addr def failed (%s)", TxVpdErrorStr( txstatus );
                rc = 1;
                break;
            }
    /*
    // TxVpdVport actual defines a virtual port to the TXn000.
  
            vportnum++; /* Increment vport number to next one */
            txstatus = TxVpdVport( VpdHandle, (uchar)i, vportnum, &addr );
            if (txstatus != 0)
            {
     printf ("VPORT definition failed (%s)",TxVpdErrorStr(      txstatus );
                rc = 1;
                break;
            }
        }
    }

    MaxVport = vportnum;

    if (rc == 0)
        printf ("Virtual ports successfully defined!\r\n");

    return rc;

Refer to the TX Series Virtual Port TDM Configuration Guide for more information about configuring virtual ports.

5.5.7 Configuring TX Board TCP/IP

Once TX programs have been loaded to the TX board and the virtual port resources have been configured, applications must set up TCP/IP processes for each TX board. In most cases, this involves configuring and activating the Ethernet interface. The IP address assigned to the Ethernet Interface should be the same IP address specified for the Windows NT TCP/IP stack. The Common Management and TPX APIs provide functions for configuring the TX board TCP/IP stack.

When the Ethernet interface has been configured and enabled, Windows NT TCP/IP applications can use the TX board. This includes standard Windows Sockets API applications like those used by the Fusion sample gateway application.

For more information about Windows NT TCP/IP, refer to your operating system documentation. For more information about configuring the TX board ethernet interface, refer to the TX Series TelePatheX (TPX) Application Programming Interface Guide

5.5.8 Using TX Board Level Resources

The CPI library provides a way for TX series APIs to access TX board-level resources. The basic unit of communication to the boards is a channel. The channels provide conduits for multiplexing/demultiplexing packet-based data between the host operating system and one or more TX boards. The combination of board or communication processor (CP) number and channel number is known as a logical port.

In order to implement this multiplexing and demultiplexing, a six-byte header is used in all packets between the PC and the TX board(s).

Source Channel

Source Processor

Destination Channel

Destination Processor

Length

Data

1 byte

1 byte

1 byte

1 byte

2 bytes

1 - 1512 byte

Communications processors on TX boards are numbered from 1 - 8. The host machine is assigned a CP number of 0. The length field indicates the length of the entire data packet (including the 6 byte header). Channel numbers are numbered from 0 - 255 (channel 0 is reserved).

Typically, a particular channel number is assigned to a process on the TX board during configuration (this is similar to the way available well known ports are used in TCP/UDP). Applications are free to use any unused channel on the host side. This provides applications with up to 255 channels for each TX board.

Tasks on the TX board register to receive all data from a particular well known channel. Host applications choose an unused channel, and register to receive all packets on the channel. Communication is conducted through a connectionless datagram service.

Note: Most processes running on TX boards respond to requests from applications, and provide responses indicating the success or failure of requests. Responses occur at the application level, not at the CPI layer.

For more information about controlling TX Series board-level resources, refer to the TX Series CPI Library Software Interface Guide.

5.6 Controlling RTP/RTCP Sessions

Internet RFC 1889 describes a pair of protocols (RTP and RTCP) for transmitting real-time data streams over a packet-switched networks (for example, IP networks). The Real-time Transport Protocol (RTP) specifies the method for transmitting real-time data. The Real-time Transport Control Protocol (RTCP) specifies the method for monitoring the quality of service associated with RTP sessions.

Note: Applications do not need to use the information that RTCP provides, even though RTCP is present and coupled to RTP. RTCP provides applications with quality of service information, but does not specify what applications must do with this information.

Encoded voice packets are sent to and received from TX boards over the MVIP bus. The RTP/RTCP API allows applications to connect RTP sessions (and pass the encoded voice packets) to other TX boards or PCs on the packet networks. The RTP/RTCP API also provides functions for formatting RTP/RTCP control packets, determining data types, and retrieving status and data from response or notification packets. For RTP/RTCP sample code, refer to Appendix C.

5.6.1 Managing RTP Threads

Application programmers have several choices in setting up the threading architecture in Fusion gateway applications. Gateway applications can manage threads in one of the following ways:

5.6.2 UDP Port Number Assignments

RTP and RTCP use the User Datagram Protocol (UDP) for data transmission over IP networks. The RTP/RTCP protocols specify the following stream numbering conventions:

5.6.3 RTP Sessions Values

Four values are required for setting up RTP sessions:

The combination of these four values (i.e., a source and destination transport address) identifies a unique full duplex RTP data structure. The four values must be determined by the application before RTP sessions are created.

5.6.4 Initializing RTP Sessions

The following sequence provides an overview of tasks performed to initialize an RTP session. For further information about TX series functions used to perform these tasks, refer to the TX Series RTP/RTCP Developer's Guide and to the TX Series CPI Library Software Interface Guide.

  1. Use cpi_init to initialize the CPI library.

    
    
  2. Use cpi_open to open a channel to receive data on the TX board.

    
    
  3. Fill a TX_RTP_CCB structure with parameters that configure the RTP session. The structure includes fields for the following information:

    
    -	 Handles related to one session

    - Virtual port to talk to DSP

    - IP information for source and remote

    - Source description item (used by the gateway application for
    session ID)

    - Schedule for each source description items item

    - Jitter buffer configuration

    - Starting sequence number

    - Timestamp frequency

    - Session bandwidth

    - Protocol used between TX board and DSP

    - Payload value

    - Version of the ccb structure

  4. Use TxRtpCreateReq to build a RTP session request packet from the TX_RTP_CCB structure.

    
    
  5. Use TxRtpPrepSend to build the RTP create request. (TxRtpPrepSend must be explicitly sent to the TX board with cpi_send).

    
    
  6. Use cpi_send to send the TxRtpPrepSend command to TX board.

    
    
  7. Use cpi_wait_msg to wait for an event from the TX board. cpi_wait_msg waits a specified period of time and returns a packet if one is received.

    
    
  8. If cpi_wait_msg returns CPI_SUCCESS

5.7 Programming Guidelines

The following guidelines apply to programming the packet network interface for Fusion gateway applications.

5.7.1 Multiple TX Boards in a Single PC Chassis

Some Fusion gateway applications use multiple TX boards on a host single system. Configuring the host system in this way requires special steps to ensure that the gateway application correctly reads source and destination address information from the packet data it receives.

Example

The following example shows setting up a gateway application with more than one TX board in a PC chassis.

Two Fusion gateway host systems reside on an IP network:

Both systems and all TX boards are on the same Ethernet segment, and in the same Class C subnet. The table below shows the network configuration of each board:

TX Board

IP Address

Fusion System

Subnet Address

TXA

198.62.153.10

System 1

255.255.255.0

TXB

198.62.153.20

System 2

255.255.255.0

TXC

198.62.153.30

System 2

255.255.255.0

The connections take place as follows:

  1. System 2 receives an incoming PSTN call and chooses to connect to
    System 1.

    
    
  2. System 2 determines that TXB is currently loaded, so it sets up a packet network half-call session on TXC.

    
    
  3. System 2 sends a call setup request to System 1. The Windows NT TCP/IP stack monitoring the IP address and subnet mask of TXB and TXC uses TXB to send the call setup request to System 1. (This can be accomplished using H.323 or a proprietary call setup scheme)

    
    
  4. System 1 receives the call setup request and sets up a call.

    
    Note:  If the Fusion gateway application determines IP addresses from the received IP packets, System 1 will incorrectly determine that it is connecting to TXB, not TXC. As a result, voice packets between the two systems will be routed to the wrong IP address on System 2. 
    
As the example shows, Fusion gateway call control mechanisms must read source IP and destination IP addresses from call setup packets (from H.323 or a proprietary IP call control protocol), not from the IP addresses within individual IP packets.

5.7.2 Multiple Call Control Protocols in a Single System

The Fusion gateway applications can use more then one IP call control protocol in a single host system. For example, they can use a proprietary call control protocol and the H.323 call control protocol at the same time.

Note: H.323 call control stacks typically use TCP well known port #1720 for call control. In order to guarantee that there are no conflicts with an H.323 stack, other proprietary call control stacks must use different well known port numbers.

5.7.3 Using Simplex Streams with H.323

H.323 supports both half-duplex and full duplex RTP data streams. Applications that use half-duplex data streams instead of full duplex data streams must open two separate RTP sessions in order to create a full duplex connection. For the receiving RTP session, the application only needs to specify the local IP address and local UDP port number. The remote IP address can be set to 255.255.255.255 to indicate that any address will match, and the UDP port number can be set to 0xFFFF to specify that any UDP port number will match.

For the transmitting RTP session, the application must specify the complete IP address for both the local and remote sides. However, the local UDP port number can be any value the user specifies as long as it is unique to this session.

5.7.4 Using Multi-Purpose TX Boards

In most cases, TX boards are used for RTP/RTCP and for providing Ethernet NIC capabilities to the host IP stack. When configured this way, the host IP stack and the TX board's embedded IP stack typically use the same IP address, even though they are running two separate IP stacks.

A conflict can occur if the gateway application runs other IP applications on the host system, and if the RTP is given a UDP port number used by one of the host-based IP applications. When this occurs, all data received on the UDP port is sent to the RTP process on the TX board, and is not forwarded through the NIC card interface to the host IP application.

To guarantee that no conflicts occur, when opening a UDP socket on the host, use the UDP port number returned by the host IP stack as the local UDP port number passed by the RTP API. Later, when the RTP session is terminated, close the socket with the host IP stack. By doing this, applications can use the host IP stack to generate unique UDP port numbers for each RTP session without creating address conflicts. However, a gateway application configured in this way must manage these port numbers so that no conflicts occurs between the RTP and RTCP UDP port numbers used by RTP/RTCP and host-based IP applications.

5.8 H.323 Stack API

The H.323 Stack API is an optional part of the Fusion application development environment. It consists of a ITU H.323-compliant software API that provides the necessary tools for conferencing over IP data networks. The H.323 Stack includes the following components:
Component

Description

H.323 Conference Manager (CM)

Directs all conference activities.

H.225 software (including Q.931, RAS and RTP/RTCP)

Handles the packetization and synchronization of media streams.

H.245 software

Controls the communication between the visual telephone system and the terminal equipment.

For more information about the H.323 Stack programming model or specific functions within the API refer to the Fusion H.323 Stack Programmer's Guide and Reference.

5.8.1 H.323 Call Control State Diagram

Figure 22 shows the state machine used for controlling calls at the packet network interface in the Fusion sample gateway program:

Figure 22. H.323 IP/LAN Call Control State Diagram




(Page 1 of 1 in this chapter)


tech_support@nmss.com
Copyright © 1998, Natural MicroSystems, Inc. All rights reserved.