2.1 Introduction

2.1.1 Initializing the Virtual Port Library

2.1.2 Processing Return Values

2.1.3 Configuring Packet Fill

2.2 Virtual Port Configuration API

2.2.1 Configuring Virtual Ports

2.2.2 Opening the Virtual Port API

2.2.3 Setting the MVIP Clock Configuration

2.2.4 Defining Virtual Port Resources

2.2.5 Configuring Virtual Port Resources

2.2.6 Defining Virtual Ports

2.2.7 Closing the Virtual Port API

2.2.8 Example

2.3 Virtual Port Data Transfer API

2.3.1 Response Handling

2.3.2 Attaching and Detaching to Virtual Ports

2.3.3 Enabling and Disabling Virtual Ports

2.3.4 Receiving Data Through Virtual Ports

2.3.5 Receive Handling

2.3.6 Terminating Virtual Port Data Transfer

2.1 Introduction

This chapter describes the API functions available for the Virtual Port Configuration API and the Virtual Port Data Transfer API. Application can use these APIs directly, or indirectly by altering the script file passed to the vpdcfg utility. (see Appendix B).

The virtual port library provides functions for:

• Opening and closing the Virtual Port API

• Setting message trace level

• Receiving Virtual Port API error descriptions

• Configuring packet fill

• Controlling the MVIP clock and TX board T1/E1 interfaces

• Setting TX board resource definitions

• Configuring TX board resources

• Monitoring virtual port response packets

2.1.1 Initializing the Virtual Port Library

To access all other functions in the configuration API, invoke the function TxVpdOpen. This returns a TX_HANDLE that is used in other Virtual Port Configuration API functions.

2.1.2 Processing Return Values

All Virtual Port Configuration API functions return a short that contains a completion code for the requested operation. A completion code of 0 [SUCCESS] indicates that the request was successfully issued to the communication processor and a successful response was received from the communication processor.

A non-zero completion code indicates that a successful response was not received. The error can either be due to the CPI library (refer to txcpi.h), the VPD library (refer to vpdtype.h), or the communication processor itself (refer to cpkuser.h). The function TxVpdErrorStr returns a string describing the error code.

2.1.3 Configuring Packet Fill

The Virtual Port Configuration API provides a set of functions that manipulate the content of a provided dual port RAM packet (usually to be issued as a request after all manipulations are complete). These functions also assist in setting structures used as inputs to future Virtual Port Configuration API function calls. These functions are called by the higher level functions that issue requests and wait for responses.

2.2 Virtual Port Configuration API

Before TX-based processes can use TX board communications resources, applications must configure virtual ports. Virtual ports allow applications to use specific resources on TX boards. The Virtual Port Configuration API includes functions for:

1. Building dual port RAM packets.

2. Issuing requests to the communication processor (CP).

3. Waiting for responses.

4. Matching requests with responses.

5. Returning the results of the exchange.

2.2.1 Configuring Virtual Ports

When configuring the virtual ports, applications determine the following:

• The type of data the virtual port transmits (Ethernet or HDLC)

• The source from which the virtual port receives its data (physical interface or a stream and timeslot on the MVIP bus)

• The input and output MVIP stream and timeslot to which the virtual port is connected
  Note: 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.

2.2.2 Opening the Virtual Port API

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

2.2.3 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.

2.2.4 Defining Virtual Port Resources

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

• TxVpdResDflt

• TxVpdResDef

• TxVpdResTdm

• TxVpdDefine

The following example assumes a TX board with at least one QUICC32 chip. Each QUICC32 can handle 32 separate timeslots over the MVIP Bus. For example, a program using bonded timeslots of 2 MVIP channels 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 bandwidth capacity in packet-per-second.

For voice over IP, virtual port resources have a connection type of TDM (time division multiplexing).

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 being defined. 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, indicating 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 TDM stream. There are 32 timeslots (channels) per TDM stream.
   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.

2.2.5 Configuring Virtual Port Resources

After defining TX virtual port resources, you must configure these resources. While 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.

Note: You cannot reconfigure a virtual port resource while the resource is being used.

For example, when the application configures the resources it will use, it can loop through each defined resource and configure them in the following way:

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

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

2.2.6 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 defined resource 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. For example if the packets are HDLC packets, 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 Fusion sample gateway program specifies 0xFF, which is high priority. There is also low and medium priority.
   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 range from 1 - 128.
   addr	Pointer to the demultiplexing address structure provided in num_addrs of TxVpdAddrDef.

2.2.7 Closing the Virtual Port API

When an application has completed all virtual port configuration, the application should close the API (see TxVpdClose) to release the Virtual Port Configuration API dual port RAM channel.

2.2.8 Example

The following code sample demonstrates defining virtual ports (including demultiplexing addresses) in a Fusion gateway application 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;

2.3 Virtual Port Data Transfer API

Before any virtual port access is allowed, the application must open a dual port RAM channel (refer to the TX Series CPI Library Software Interface Manual for information about the cpi_open function). This channel need not be a well known channel number. The channel number for virtual port handling on the communication processor is well-known (channel #13). All requests sent from the application's source channel to the communication processor's well known channel are responded to by the communication processor swapping source and destination.

Because the data transfer interface involves asynchronous responses, it is recommended that the channel number selected be used only for virtual port communications. If the channel is shared with any API involving synchronous responses, data transfer responses and received frame indications could be lost while waiting for the other API response to be received.

This section describes the method of virtual port control using virtual port data transfer API functions to assist in building and issuing requests to the communication processor. No API functions are provided to assist with handling messages received from the communication processor. See Chapter 6 for a description of received message structures.

2.3.1 Response Handling

All API functions issue a request. This request is received by a KERNEL task running on the communication processor ($vpd). The $vpd task will perform minimal packet verification and then attempt to complete the request. If packet verification is successful, a response is generated by the $vpd task once the given request completes. This response indicates whether the request itself was successful.

There is no API function for handling virtual port API responses. These are dual port RAM packets (see Appendix A) with the structures defined in txcpi.h and vpdtype.h.

Each response includes a message ID field and a message key field to allow the application to match the response with a previously issued request. The message ID field is a sequence number generated by the API function that issued the request (viewable in the dual port RAM request packet on return from the API function). The message key field is provided by/completely controlled by the application.

2.3.2 Attaching and Detaching to Virtual Ports

Attaching to a virtual port registers the application as the owner of the virtual port. This may or may not represent exclusive ownership of the entire resource to which the virtual port is assigned. Applications can attach to virtual ports by invoking TxVpdAttach.

Applications can disable virtual ports to de-activate data transfer by calling TxVpdDetach. When applications invoke TxVpdDetach, all pending transmit requests are terminated (returning with a failure response) and receive indications cease.

2.3.3 Enabling and Disabling Virtual Ports

After successfully attaching to a virtual port, applications must enabled the virtual port to allow data to pass through. Applications can enable attached virtual ports by invoking TxVpdEnable. A successful response to TxVpdEnable indicates that transmit requests will be allowed and that receive notifications are now possible.

If the enable is the first received for the resource associated with the virtual port, TxVpdEnable configures and physically enables the resource.

If the enable is not the first received (if another virtual port assigned to the same resource had previously been enabled), TxVpdEnable activates data transfer. The physical resource is not affected in this case.

To de-activate data transfer through a virtual port, applications can invoke TxVpdDisable. When TxVpdDisable is called, any pending transmit requests are terminated (returning with a failure response) and all receive indications cease.The response to TxVpdDisable is generated when all outstanding data transfers have complete.

2.3.4 Receiving Data Through Virtual Ports

TxVpdTx allows applications to pass data frames over the physical resource with which the virtual port is associated. The application must then create correctly formatted frames (although certain features like HDLC CRC generation are provided by the communications processor).

The data area of dual port RAM request packets must be set (from msgdata field for datalen) before applications call TxVpdTx. Data is not passed to the API function to avoid a data copy. Refer to Chapter 6 for a description of the data structure used here.

The maximum data size that may be transmitted is determined by the literal MAXVPDDATA [1438 bytes]. This represents the largest data block that can be transferred over the dual port RAM (less all header information) in a single request.

Data is received over a virtual port as a receive notification dual port RAM packet. The maximum data that can be received in a single frame is determined by the literal MAXVPDDATA [1438 bytes].

This is the only type of packet the communication processor generates that is not a response to a previous request by the application. The communication processor issues a receive indication to the dual port RAM channel that issued the virtual port attach request.

2.3.5 Receive Handling

There is no virtual port API function provided for receive handling. The received data is simply a dual port RAM packet (see packet protocol for structure).

Applications should use the CPI library function cpi_wait_msg (after sending all transmissions possible) to wait for responses. This function will cause the application to sleep until a dual port RAM packet is received for the associated channel, or a timeout occurs if indicated on the call to cpi_wait_msg (refer to the TX Series CPI Library Software Interface Manual for information about CPI library functions).

2.3.6 Terminating Virtual Port Data Transfer

It is possible for an application to terminate cleanly or abruptly. A clean termination involves successfully disabling and detaching from all virtual ports before exiting the application. An abrupt termination involves exiting the application while some virtual port resources (some attaches) are being held by the application.

All applications should be written with clean termination logic whenever possible. The result of an abrupt termination is the creation of floating attaches. Since the communications processor has not been told that the owning application has terminated, there is no way for the application's virtual ports to be returned to the set of ports available to other applications. All data received will be past up (and discarded by the host driver). No other application will be allowed to attach to the floating virtual port. Rebooting the communications processor will return all virtual ports to the un-assigned state.

The final step of any termination should be to close the dual port RAM channel used by the application (cpi_close).