(Page 1 of 1 in this chapter)

Chapter 1

Introduction

1.1 TX Software Architecture
1.2 Common Management APIs
1.2.1 Common Management Extension APIs
1.2.2 TelePathX (TPX) API
1.2.3 Ds0 Over IP API
1.2.4 X.25 API
1.3 CPI Library
1.4 Network Management
1.5 Platform-Specific Variations

1.1 TX Software Architecture

The TX Series host application development environment consists of a layered set of API libraries that enable the application programmer to configure and control the various protocol engines loaded on TX boards. As Figure 1, applications that use Common Management extension (TPX, Ds0 Over IP API, or X.25 API) functions, also need to use Common Management API functions to obtain access to TX board resources.

Figure 1. TX Series Software Architecture

1.2 Common Management APIs

The Common Management API allows host-based applications to configure, control, and examine the behavior of tasks executing on a TX board communications processor (communications processor). This API is actually a set of independent library modules that share a common core library. Access to all Common Management API modules is provided for C and C++ host-based applications.

The standard method for configuring/monitoring the behavior of a task executing on a TX board communications processor is to communicate with the task using IO packets. IO packets are sent between tasks as one of the basic methods of
inter-task communication. The Common Management API allows host-based applications to create images of these IO packets and pass the IO packet images across the dual port RAM of the communications processor. The communications processor task named NETMGR (Network Manager) then receives these dual port RAM packets and issues the actual IO requests on behalf of the host-based application. When NETMGR receives a response to an IO request, the response is transmitted back across the dual port RAM and the Common Management API provides the response to the host-based application.

Common Management API functions are described in detail in Chapter 3.

1.2.1 Common Management Extension APIs

The following TX Series APIs obtain access to TX board resources through Common Management API functions:

1.2.2 TelePathX (TPX) API

The TPX API is an extension library to the Common Management API that assists applications in interfacing to the TelePathX (TPX) task. The TPX task provides TCP/IP connectivity from a TX board communications processor. This API assists applications in building TX Common Management packets used to configure, control, and monitor the TPX task.

Note: This API does not interface directly to the CPI Library. Applications must use the Common Management API functions TxApiSendReq, TxApiGetResp, and TxApiReqRsp to actually send packets built using this API. See the Section 3 for more information.

The TPX API (TXTPX) includes the Interface Functions and Route Functions described in Chapter 4.

Access to the API is obtained by including the file tpxtype.h. This include file will include tpxtype.h to obtain definitions of the structures used by the TPX API.

1.2.3 Ds0 Over IP API

Applications on the Host PC communicate to tasks on the TX board through communications channels to the board. A low level interface to these channels is provided by the Communications Processor Interface Library (CPI Library). The Common Management DS0/IP API uses this low level interface to communicate with the TX board, but eases the application programmers task by managing the details of using this interface.

The Ds0 Over IP API includes the functions described in Chapter 5. For more information on the CPI Library, refer to the TX Series CPI Library Software Interface Manual.

1.2.4 X.25 API

The X.25 API is an extension library to the Common Management API that assists applications in interfacing to the X.25 task. The X.25 task provides X.25 connectivity from a TX board communications processor. This API assists applications in building TX Common Management packets used to configure, control, and monitor the X.25 task.

Note: The X.25 API does not Link directly to the CPI Library. Applications must use the Common Management API functions TxApiSendReq, TxApiGetResp, and TxApiReqRsp to actually send packets built using this API.

The X.25 API includes the functions described in Chapter 6. Access to the API is provided by including the file x25type.h which defines the structures used by the X.25 API.

1.3 CPI Library

The TX Series CPI Library provides the lowest layer interface between host-based applications and communications processor-based applications (by packet transmission across the dual port RAM). The Common Management API sits above the CPI Library and provides another layer for assisting applications in building the proper management packets (as shown in Figure 1).

The following CPI Library functions are used by the Common Management API:

Function

 Description

cpi_init

 Initializes the CPI Library for use by Common Management API.

cpi_open

 Registers to receive dual port RAM packets from the indicated TX board communications processor (or from all communications processors).

cpi_send

 Sends a dual port RAM packet to the communications processor number indicated within the packet header.

cpi_get_data

 Polls to determine whether any dual port RAM packet is pending to be received from the communications processor number indicated (or all communications processors).

cpi_close

 Deactivates registration for dual port RAM packet reception.

No other CPI Library functions are required by the Common Management API. See the CPI Library documentation for details on the functions listed above.

1.4 Network Management

Network Management for the TX board communications processor family is performed by a communications processor-based task named NETMGR. NETMGR acts as a bridge between dual port RAM packets and inter-task IO packets. NETMGR can also act as a bridge to remote NETMGR tasks which are accessed via UDP datagrams. When the NETMGR task begins execution on the communications processor, it registers for the network management DPR channel (channel 5) and waits to receive requests from the host processor.

The Common Management API communicates with communications processors solely via the network management DPR channel. The dual port RAM packets are of the format expected by the NETMGR task. In most instances, this structure is not manipulated by users of the Common Management API; but the entire structure is provided, and the API has been designed to allow user applications to directly control all fields prior to the actual transmission of that packet.

Note: Access to the Common Management API can be obtained by including the file txapi.h. This include file will include cpkuser.h to obtain TX board communications processor Kernel definitions of the IO packets that are issued by any Common Management API functions. Since cpkuser.h may only be included once, any host application that requires additional service-related Kernel definitions (e.g. QUEUE, TIMER, etc.) should include cpkuser.h before including txapi.h. Host-based applications being built for processors that do not use MC680x0 byte ordering should also include the following definition before including txapi.h:

#define TXAPI_HOSTSWAB /* host type requires swabbing */

1.5 Platform-Specific Variations

The main platform-specific consideration when using the Common Management API relates to the differences in the representation of short and long data fields on various processors. All short and long field values that are transmitted to or from a TX board communications processor must be in MC680x0 byte order (MSB first). This means that it is up to the host software to perform all byte swabbing that is necessary before sending any dual port RAM packet or after receiving any packet.

Whenever a field is one that byte swabbing may be required, it will be defined as type TXCP_SHORT, TXCP_USHORT, TXCP_LONG, or TXCP_ULONG. This definition is intended to remind the user that the field is in the format of the communications processor, not necessarily that of the host processor.

To aid in swab handling, the following macros are provided by the Common Management API (in the host-platform specific definition area):

Macro

 Description

TX_CPTOHL

 Convert a long or unsigned long from communications processor-specific byte order to host-specific order.

TX_CPTOHS

 Convert a short or unsigned short from communications processor-specific byte order to host-specific order.

TX_HTOCPL

 Convert a long or unsigned long from host-specific byte order to communications processor-specific order.

TX_HTOCPS

 Convert a short or unsigned short from communications processor-specific byte order to host-specific order.

Swabbing is not required when passing parameters to Common Management API functions. It is the responsibility of the API to perform any necessary swabbing of these types of parameters. The Common Management API has been defined to accept all standard field definitions via function parameters. User applications will therefore only have swabbing concerns when setting non-standard field values or when manipulating a structure for which no direct API access has been defined.


(Page 1 of 1 in this chapter)

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