cpi library software interface manual · cpi library software interface manual ... multi-vendor...

IDX GLSTOC

CPI Library Software Interface Manual

P/N 9000-6436-15

Send Feedback to NMS Doc Dept

100 Crossing Boulevard, Framingham, MA 01702-5406 USAwww.nmscommunications.com

http://www.nmscommunications.com

http://www.nmss.com

http://www.nmss.com

mailto:[email protected]

IDX GLSTOC

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.

2001 NMS Communications Corporation. All Rights Reserved.

Alliance Generation, NaturalEdge, and The Circuit Man Logo are registered trademarks or service marks of NMS Communications Corporation. 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. 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 is a trademark, and MS-DOS, MS Word, and Windows are registered trademarks of Microsoft Corporation in the USA and other countries. Clarent and Clarent ThroughPacket are trademarks of Clarent Corporation. 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

Refer to the NMS web site (www.nmscommunications.com) for product updates and for information about NMS support policies, warranty information, and service offerings.

Revision Release Date Notes1.0 GJG1.2 March 1999 GJG1.3 November, 2000 GJG; SS7 3.61.5 August, 2001 GJG; SS7 3.8 Beta

This manual printed: August 30, 2001


http://www.nmss.com


IDX GLSTOC

Table of Contents

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.1 Development Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2 Library Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.1 Windows NT and Windows 2000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.2 UnixWare and Solaris. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

3 Alphabetical Function Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143.2 Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

cpia_get_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16cpia_intr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17cpia_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18cpia_rxnotify. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19cpia_send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20cpia_txnotify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21cpi_check_bs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22cpi_clear_stats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23cpi_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24cpi_cptoh_l . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25cpi_cptoh_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26cpi_exec_krnl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27cpi_force_bs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28cpi_get_board . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29cpi_get_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30cpi_get_eeprom. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31cpi_get_error_str. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32cpi_get_last_error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33cpi_get_resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34cpi_get_stats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35cpi_htocp_l . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36cpi_htocp_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37cpi_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

NMS Communications 3



Table of Contents CPI Library Software Interface Manual

IDX GLSTOC

cpi_load_krnl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39cpi_open. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40cpi_pre_boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41cpi_read_dpr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42cpi_send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43cpi_wait_msg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44cpi_wait_obj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45cpi_write_dpr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

4 NMS Communications



IDX GLSTOC

Chapter 1

Introduction

1.1 Development Environment 6

1.2 Overview 7




Chapter 1 Introduction CPI Library Software Interface Manual

IDX GLSTOC

1.1 Development Environment

The TX host application development environment consists of a series of API libraries that allow the application programmer to configure and control the various protocol engines loaded on the TX board. This manual describes the CPI Library. Refer to the appropriate API manual for further information on the other components illustrated here. For more information on using the CPI library, see the distributed example (txalarm) in the \nms\tx\samples directory for Windows NT and Windows 2000, and in the /opt/nmstx/src for UnixWare and Solaris systems.

Note: Always use the compile option ‘Structure Packing’ when compiling source code using these libraries and APIs.

Host Applications

TX Host Device Driver

NetworkInterface

Driver

MVIP-90API

T1/E1 API Virtual PortsAPI

LoaderAPI

SS7 APIs

CPI Library




CPI Library Software Interface Manual Overview

IDX GLSTOC

1.2 Overview

The CPI library was designed to facilitate development of applications over the TX series of boards from NMS Communications. This library gives developers a consistent communications mechanism to the TX board, regardless of the operating system employed on the host (Windows, UnixWare, Solaris).

The basic unit of communication to the boards is a channel. The channel mechanism provides a multiplexing/de-multiplexing packet based interface between the host operating system and one or more TX boards. The combination of board number (or CP number) and channel is known a logical port.

In order to implement this multiplexing and de-multiplexing, a six byte header is used on all packets between the PC and the TX boards:

Communications processors (TX devices) are numbered from 1 through 16. The PC is assigned a CP # of 0. The length field indicates the length of the entire data packet (including the 6-byte header). Channel numbers are numbered from 0 to 255 (Channel 0 is reserved).

Typically a particular channel number is assigned to a task on the TX board by a prior arrangement. This is similar to the well known ports concept used in TCP/UDP. The host-based application is free to use any unused channel on the host side. This provides the application programmer up to 255 channels (currently up to 64 channels for UNIX) for each TX board.

This communications mechanism is in fact very similar in function to UDP datagrams. Tasks on the TX board register to receive all data from a particular well know channel. Host applications pick an unused channel they wish to use and register to receive all packets on the chosen channel. Communications are accomplished via a connectionless datagram type of service. Due to the nature of such a service, most tasks on the TX board respond to requests from the Host application with a response indicating success or failure of the request. This response is at the application level, not at the CPI layer.

Source Channel Source CP Dest Channel Dest CP Length Data

1 Byte 1 Byte 1 Byte 1 Byte 2 Bytes 1-1512 Bytes




Chapter 1 Introduction CPI Library Software Interface Manual

IDX GLSTOC

The following list displays well known channels used by tasks on the TX board. These channels are defined in the file dpriface.h.

#define PT_NBX 0x01 /* NetBios to X25 Task */#define PT_HIP 0x02 /* Host IP Access Task */#define PT_FILEMNGR 0x03 /* File Manager Task */#define PT_X25 0x04 /* Board to Board X25 */#define PT_NETMNGR 0x05 /* Network Manager Task */#define PT_CONSOLE 0x06 /* Console Task */#define PT_LOADER 0x07 /* Loader Task */#define PT_DEBUG 0x08 /* Debug Task */#define PT_MVIP 0x09 /* MVIP Control Task */#define PT_T1E1C 0x0a /* T1/E1 Control Task */#define PT_T1E1S 0x0b /* T1/E1 Status Task */#define PT_INF 0x0c /* Alarm Mgr raw alarms */#define PT_VPD 0x0d /* Virtual Port Driver */#define PT_ICMP 0x0e /* ICMP Protocol Task */#define PT_SS7 0x0f /* SS7 API port */#define PT_RTCP 0x10 /* RTCP Control Task */#define PT_RTP 0x11 /* RTP Control Task */#define PT_ARP 0x12 /* ARP Protocol Task */#define PT_ISUP 0x14 /* ISUP Protocol Task */#define PT_MTP 0x15 /* MTP Protocol Task */#define PT_TCAP 0x17 /* TCAP Protocol Task */#define PT_TUP 0x1d /* TUP Protocol Task */#define PT_SCCP 0x1e /* SCCP Protocol Task */#define PT_RMTDPR 0x1f /* Remote DPR control */

Note: Many times NMS-developed host applications tend to use the same port number on the host side that is used on the TX board side. For example, the Ethernet NIC driver software on the host uses Port number 0x02 on the host. This makes this port unavailable to other applications on the host. In general, NMS Communications suggests that host application programmers use ports 33-63 in order to minimize any such conflicts.




IDX GLSTOC

Chapter 2

Library Overview

2.1 Windows NT and Windows 2000 10

2.2 UnixWare and Solaris 11




Chapter 2 Library Overview CPI Library Software Interface Manual

IDX GLSTOC

2.1 Windows NT and Windows 2000

The CPI library uses standard Windows NT and Windows 2000 routines to access the TX kernel mode device driver. The interface between the library and driver is based on a simple Windows file handle. The library opens a channel like a file, reads from and writes to the driver like a file, and closes the channel like a file.

Packets can be received by the host PC asynchronously. Windows NT and Windows 2000 provide standard mechanisms for receiving unsolicited packets. The library posts read calls to the driver which do not block. The application can then use Windows’ WaitForSingleObject or WaitforMultipleObjects to determine when those reads complete with a received packet from the TX device. The handle to pass to these Windows NT/Windows 2000 calls can be retrieved using the cpi_wait_obj call. Both Windows NT/Windows 2000 calls can be told to return immediately by passing zero in the dwTimeout parameter. This would be the equivalent of polling for packets. The same parameter could be set to INFINITE, in which case it would not return until there was a packet (when using WaitForSingleObject) or one of the list of handles had something to report (when using WaitForMultipleObjects).

The ISA device driver buffers packets for registered channels for an inactive read and during packet bursts. However, if the host application cannot process the packets fast enough, and the buffer limit configured is exceeded, the device driver will discard new receives until buffers become available. It is the user’s responsibility to determine the appropriate values to configure based on the application requirements.

Note: The user can configure the default number of receive buffers available for a channel and the number and size of receive buffers for specific channels. This is accomplished by accessing the NMS TX CPs applet in Control Panel. This configuration ability allows the user to specify how much system memory will be allocated by the low level kernel device driver.

For the PCI driver, a flow control mechanism has been implemented that will cause messages from the TX board to be queued on the board if the host-based application does not service received packets quickly enough. The flow control mechanism removes the possibility of the TX driver needing to drop received packets. A similar mechanism has been added for packets sent from a host-based application to the TX board.




CPI Library Software Interface Manual UnixWare and Solaris

IDX GLSTOC

2.2 UnixWare and Solaris

The TX driver for the UNIX systems (both UnixWare and Solaris) is a streams driver and is directly accessed via the standard system calls: open, close, putmsg, getmsg, ioctl, etc. The driver communicates to applications using a specific driver-to-application protocol, so direct access is not recommended. The CPI library uses a TX_HANDLE type as an object on which all I/O is done. In the UnixWare and Solaris systems, the TX_HANDLE can be passed to cpi_wait_obj, to obtain a standard UNIX File Descriptor. In particular, packets can be received by the host UnixWare or Solaris system from a TX board asynchronously by using either the poll system call or the select system call.

For example, if you care to wait on both input and packets from a TX board, you can use poll as follows:

. struct pollfd fds[2]; . .

cpi_init(0, &str); mode = CPIM_PORT; port = PORT((short)board, (short)chan);

if ((txhandle = cpi_open(port, mode, NULL)) < 0) { < Error handling code > } fd = cpi_wait_obj (txhandle); for (;;) { fds[0].fd = 0; /* fd for standard input */ fds[0].events = POLLIN; fds[0].revents = 0; fds[1].fd = fd; /* TXn000 fd */ fds[1].events = POLLIN; fds[1].revents = 0;

if (poll(fds, 2, -1) < 0) { < Error handling code > }

for (i = 0; i < 2; i++) { if (fds[i].revents & (POLLERR | POLLHUP | POLLNVAL))




Chapter 2 Library Overview CPI Library Software Interface Manual

IDX GLSTOC

{ < Error handling code > }

if (fds[i].revents & POLLIN) { /* TXn000 receive */ if (fds[i].fd == fd) { len = sizeof (CPIPKT); if (ret = cpi_get_data(txhandle,&inbuf,&len)) { < Error handling code > } . . < Code to process data > . . } /* Terminal input */ else if (fds[i].fd == 0) { } }

} /* for i */

} /* for ever */




IDX GLSTOC

Chapter 3

Alphabetical Function Reference

3.1 Introduction 14

3.2 Compatibility 14cpia_get_data 16cpia_intr 17cpia_open 18cpia_rxnotify 19cpia_send 20cpia_txnotify 21cpi_check_bs 22cpi_clear_stats 23cpi_close 24cpi_cptoh_l 25cpi_cptoh_s 26cpi_exec_krnl 27cpi_force_bs 28cpi_get_board 29cpi_get_data 30cpi_get_eeprom 31cpi_get_error_str 32cpi_get_last_error 33cpi_get_resources 34cpi_get_stats 35cpi_htocp_l 36cpi_htocp_s 37cpi_init 38cpi_load_krnl 39cpi_open 40cpi_pre_boot 41cpi_read_dpr 42cpi_send 43cpi_wait_msg 44

NMS Communications

Send Feedback to NM

cpi_wait_obj 45cpi_write_dpr 46

13

S Doc Dept


Chapter 3 Alphabetical Function Reference CPI Library Software Interface Manual

IDX GLSTOC

3.1 Introduction

This chapter provides a comprehensive, alphabetically-ordered reference to the CPI Library 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:

3.2 Compatibility

Not all CPI library functions can handle asynchronous I/O and synchronous I/O functions. Moreover, mixed-mode (synchronous and asynchronous) I/O on the same handle is not allowed. The following table summarizes the various CPI API functions and their modality (an asterisk (*) indicates a user-supplied function):

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 CPI_SUCCESS or an error code. For asynchronous functions, a return value of CPI_SUCCESS (zero) indicates the function was initiated; subsequent events indicate the status of the operation.

Function Synchronous Asynchronous

cpia_get_data No Yes

cpia_intr No Yes

cpia_open No Yes

cpia_rxnotify* No Yes

cpia_send No Yes

cpia_txnotify* No Yes




CPI Library Software Interface Manual Compatibility

IDX GLSTOC

cpi_check_bs Yes Yes

cpi_clear_stats Yes Yes

cpi_close Yes Yes

cpi_cptoh_l Yes Yes

cpi_cptoh_s Yes Yes

cpi_exec_krnl Yes Yes

cpi_force_bs Yes Yes

cpi_get_board Yes Yes

cpi_get_data Yes No

cpi_get_eeprom Yes Yes

cpi_get_error_str Yes Yes

cpi_get_last_error Yes Yes

cpi_get_resources Yes Yes

cpi_get_stats Yes Yes

cpi_htocp_l Yes Yes

cpi_htocp_s Yes Yes

cpi_init Yes Yes

cpi_load_krnl Yes Yes

cpi_open Yes No

cpi_pre_boot Yes Yes

cpi_read_dpr Yes Yes

cpi_send Yes No

cpi_wait_msg Yes No

cpi_wait_obj Yes Yes

cpi_write_dpr Yes Yes

Function Synchronous Asynchronous




cpia_get_data CPI Library Software Interface Manual

IDX GLSTOC

cpia_get_data

Description Obtains a packet of data from the specified channel.

Prototype short cpia_get_data (TX_HANDLE handle, CPIPKT *buffer, short *len);

handle TX_HANDLE associated with the asynchronous transmit completion.

buffer CPIPKT buffer to store the received packet.len Size of the buffer or length of received packet.

Return Values CPI_SUCCESS

CPI_ERROR

CPI_TRUNCATEDThe received packet was larger than the passed buffer.

CPI_INVALID_MODEHandle is not open for asynchronous I/O.

Details cpia_get_data obtains a packet of data from the channel. On entry, the passed length parameter is checked. If the length is less than the received message, then len bytes of the message will be copied to buffer and CPI_TRUNCATED will be returned. The length of the received packet is placed in len.

The cpia_get_data function should be called from within the user’s cpia_rxnotify routine. Calling cpia_get_data from outside cpia_rxnotify may result in communication errors.

For UNIX systems, the user’s cpia_rxnotify function should loop on calls to cpia_get_data until a len of zero is returned.




CPI Library Software Interface Manual cpia_intr

IDX GLSTOC

cpia_intr

Description Drains the asynchronous transmit acknowledgements and checks for any received packets waiting.

Prototype #include txcpi.h

CPI_ERR_TYPE cpia_intr (TX_HANDLE handle);

handle TX_HANDLE that has had an I/O event.


CPI_ERROR


Details The cpia_intr function should be called when an I/O event has been detected. Detecting such events is OS-specific (WaitForMultipleObjects for Windows or poll for UNIX).

Note: Asynchronous transmit complete messages are processed before received messages.




cpia_open CPI Library Software Interface Manual

IDX GLSTOC

cpia_open

Description Opens a channel for asynchronous I/O on the host.


TX_HANDLE cpia_open (void *chkey, unsigned short board, unsigned short channel, void ((*rxnotify)(TX_HANDLE handle,

void *chkey)), void ((*txnotify)(TX_HANDLE handle,

void*chkey)) CPIPKT *buffer, void*user_tx_key, CPI_ERR_TYPE, ccode)));

chkey User-controlled key that is passed back on all callback functions.

board Board number from which to receive packets.channel DPR channel from which to receive packets.rxnotify Pointer to a receive notification callback

function.txnotify Pointer to a transmit notification callback

function.

Return Values If successful, TX_HANDLE is returned.

CPI_INVALID_HANDLE

CPI_INVALID_BOARD_TYPEAsynchronous I/O is not supported for ISA boards.

Details A channel is open for either synchronous I/O (using cpi_open) or asynchronous I/O (using cpia_open). Mixed mode I/O on a given channel is not possible, either with a single TX_HANDLE or multiple TX_HANDLE’s.

See Also cpia_rxnotify, cpia_txnotify




CPI Library Software Interface Manual cpia_rxnotify

IDX GLSTOC

cpia_rxnotify

Description Notifies upper layers of messages to be received.

Prototype void cpia_rxnotify (TX_HANDLE handle, void *chkey);

handle TX_HANDLE on which the message was received.

chkey Channel key provided when the handle was opened.

Return Values Nothing.

Details cpia_rxnotify is provided by the user as a parameter to cpia_open. The CPI library calls this function as a result of a call to cpia_intr. cpia_rxnotify should call cpia_get_data to receive the incoming message.




cpia_send CPI Library Software Interface Manual

IDX GLSTOC

cpia_send

Description Sends a packet of data over the specified channel asynchronously.


short cpia_send (TX_HANDLE handle, CPIPKT *buffer, void *user_tx_key);

handle TX_HANDLE associated with channel.buffer Pointer to CPIPKT structure containing data to

send.user_tx_key User-defined key that is returned when I/O

completes.


CPI_ERROR

CPI_QUEUE_FULLMaximum number of pending asynchronous I/O requests are already in progress.


Details The value returned by cpia_send reflects the result of enqueing the packet for transmission. The ultimate disposition of the packet is passed back as a parameter to cpia_txnotify.

Once sent, a packet cannot be unsent (there is no cpia_cancel function).

Final I/O result notification is handled by cpia_intr and the cpia_txnotify callback function.

The CPIPKT structure pointed to by the buffer parameter cannot be freed/re-used/re-allocated until the final disposition of the packet has been determined with cpia_intr and cpia_txnotify. Failure to adhere to this requirement will cause unreliable and unpredictable results.




CPI Library Software Interface Manual cpia_txnotify

IDX GLSTOC

cpia_txnotify

Description Processes an asynchronous transmit complete message received from the TX board.

Prototype void cpia_txnotify (TX_HANDLE handle, void *chkey, CPIPKT *buffer, void *user_tx_key, CPI_ERR_TYPE ccode);

handle TX_HANDLE associated with the asynchronous transmit completion

chkey Channel key provided when the handle was opened.

buffer CPIPKT buffer pointer provided when cpia_send was called.

user_tx_key User key provided when cpia_send was called.

ccode I/O completion code.

Return Values Nothing.

Details When cpia_txnotify is called, or any time thereafter, the application can then free the corresponding CPIPKT passed in on the cpia_send call. Failure to adhere to this rule will result in communications errors.




cpi_check_bs CPI Library Software Interface Manual

IDX GLSTOC

cpi_check_bs

Description Determines whether the TX device, specified by handle, is in the boot state.


short cpi_check_bs (TX_HANDLE handle, CPIBS *bsp)

handle TX handle number.bsp Boot state.


CPI_ERROR

Details The handle parameter indicates which board to check and the bsp.state is then loaded with the boot state (low byte) and the CSR (high byte).

The CPIBS structure is as follows:

typedef struct _CPIBS{ unsigned short state; unsigned char reg[5];} CPIBS;

The boot state can be set to one of:

BS_BOOT 0 /* waiting to begin PREBOOT */ BS_READY 1 /* KERNEL loaded, initialized, and ready */ BS_INIT 2 /* KERNEL is initializing */ BS_DOWN 3 /* KERNEL not responding */ BS_BERR 4 /* Bus Error indicated by KERNEL */ BS_LOADING 5 /* Loading block of KERNEL */ BS_PREBOOTING 6 /* PREBOOT running, not ready for KERNEL */ BS_WAIT_KERNEL 7 /* PREBOOT complete, waiting for KERNEL */

The reg element in the structure is unused.




CPI Library Software Interface Manual cpi_clear_stats

IDX GLSTOC

cpi_clear_stats

Description Clears the statistics of the indicated channel or all channels for theTX board indicated by handle.


short cpi_clear_stats (TX_HANDLE handle, short chan)

handle TX handle number.chan Channel number.


CPI_ERROR

Details If the channel number chan is 0xffff, then the statistics will be cleared for all channels, otherwise the statistics for the channel indicated will be cleared.




cpi_close CPI Library Software Interface Manual

IDX GLSTOC

cpi_close

Description Closes the channel associated with handle.


short cpi_close (TX_HANDLE handle)

handle TX handle number.


CPI_ERROR

Details The only parameter is the handle returned from the cpi_open.

Applications that open a CPI channel should insure that all channels are closed before the application terminates. Failure to close a channel may result in resources being left in an indeterminate state.




CPI Library Software Interface Manual cpi_cptoh_l

IDX GLSTOC

cpi_cptoh_l

Description Converts the src value from Motorola format into host format.


unsigned long cpi_cptoh_l (unsigned long src)

src Location of source value.

Return Values The value passed in formatted properly

Details None.




cpi_cptoh_s CPI Library Software Interface Manual

IDX GLSTOC

cpi_cptoh_s

Description Converts the src value from Motorola format into host format.


unsigned short cpi_cptoh_s (unsigned short src)


Return Values The value passed formatted properly

Details None.




CPI Library Software Interface Manual cpi_exec_krnl

IDX GLSTOC

cpi_exec_krnl

Description Begins execution of the kernel.


short cpi_exec_krnl (TX_HANDLE handle, unsigned long startaddr, unsigned char uCode)

handle TX handle number.startaddr Start addressuCode Determines whether or not SS7 microcode is

enabled.


CPI_ERROR

Details cpi_exec_krnl is typically run after a series of load kernel functions. An application should use cpi_check_bs to determine when the kernel has completed its boot up. This function is ISA-board specific, as PCI boards have the kernel image in onboard flash memory.




cpi_force_bs CPI Library Software Interface Manual

IDX GLSTOC

cpi_force_bs

Description Forces the TX device, indicated by handle, into the boot state which prepares the board to load the operating system kernel.


short cpi_force_bs (TX_HANDLE handle)



CPI_ERROR

Details All current processing on the board is aborted. For PCI boards, cpi_force_bs also triggers the board to reboot from the TX operating system that is stored in onboard flash memory. For ISA boards, the TX operating system must be passed down to the board using cpi_load_krnl.




CPI Library Software Interface Manual cpi_get_board

IDX GLSTOC

cpi_get_board

Description Returns the board number and channel number associated with handle in board and chan.


short cpi_get_board (TX_HANDLE handle, unsigned char *board, unsigned char *chan)

handle TX handle number.board TX board number.chan Channel number.


CPI_ERROR

Details None.




cpi_get_data CPI Library Software Interface Manual

IDX GLSTOC

cpi_get_data

Description Recovers received packets from the channel associated with handle.


short cpi_get_data (TX_HANDLE handle, CPIPKT *buffer, short *len)

handle TX handle number.buffer Name of buffer to use.len Length of buffer.


CPI_ERROR

CPI_TRUNCATEDThe received length is longer than the buffer length specified.

Details Upon entry, the user specifies the length of the buffer in the len parameter. The function will return CPI_SUCCESS and len will be set to zero if there is no packet to receive. If there is a packet, the length will be placed in len and the packet will be copied into the buffer specified by the user.




CPI Library Software Interface Manual cpi_get_eeprom

IDX GLSTOC

cpi_get_eeprom

Description Fills the specified buffer with the contents of the indicated CP’s EEPROM, which is a 16-item array of 16-bit words.


short cpi_get_eeprom (TX_HANDLE handle, char *buffer)

handle TX handle number.buffer Name of buffer to use.


CPI_ERROR

Details cpi_get_eeprom fails only if the buffer is absent or too small.




cpi_get_error_str CPI Library Software Interface Manual

IDX GLSTOC

cpi_get_error_str

Description Returns a string that corresponds to the errnum passed into the function.


char cpi_get_error_str (CPI_ERR_TYPE errnum)

errnum CPI library error number.

Return Values NULL terminated string containing a description of the errnum passed.

Details If there is no match for the parameter, the string Unknown Error nnn is returned where nnn is the errnum.




CPI Library Software Interface Manual cpi_get_last_error

IDX GLSTOC

cpi_get_last_error

Description Returns the value of the previous error that occurred in the library.


CPI_ERR_TYPE cpi_get_last_error

Return Values Returns the previous error code that occurred.

Details cpi_get_last_error should be called if a CPI_ERROR is returned by another function.




cpi_get_resources CPI Library Software Interface Manual

IDX GLSTOC

cpi_get_resources

Description Identifies which TX boards, if any, are available.


short cpi_get_resources (short max_cps, long cps[])

max_cps Maximum CP number for which to return resource information.

cps Array of entries where CP types are returned.


CPI_ERROR

Details Each element of the array cps will be filled with 0 if there is not a CP of the corresponding index or will be filled with TX_1000, TX_2000, ... if a CP does exist for that index. The parameter max_cps indicates the number of CPs to check for. The cps array should have max_cps + 1 elements since the array is filled according to board number (there is no board number zero and this element is not used by this routine).




CPI Library Software Interface Manual cpi_get_stats

IDX GLSTOC

cpi_get_stats

Description Returns the statistics from the specified TX board channel or all channels indicated by handle into the buffer specified.


short cpi_get_stats (TX_HANDLE handle, short chan, CPIDRVSTATS *stats )

handle TX handle number.chan Channel number.stats Pointer to structure where statistics are

returned.


CPI_ERROR

Details If the channel number chan is 0xffff, then the statistics returned will be for all channels, otherwise the statistics for the channel indicated will be returned. The statistics are returned in the pointer stats.

typedef struct _txpdCtlSTATS{ unsigned short Channel; /* 0xffff for all or 0..255 */ unsigned short LowFreeCnt; /* Smallest free buffer count */ unsigned long PktsSentCS; /* # packets sent */ unsigned long BytesSentCS; /* # bytes sent */ unsigned long SendRejCS; /* # sends rejected as illegal */ unsigned long PktsRecvCS; /* # packets received */ unsigned long BytesRecvCS; /* # bytes received */ unsigned long RecvRejRegCS; /* # rcvd pkts rejected-no registration */ unsigned long RecvRejBfrCS; /* # rcvd pkts rejected- no buffer * available */ unsigned long RecvTruncCS; /* # rcvd pkts truncated */};




cpi_htocp_l CPI Library Software Interface Manual

IDX GLSTOC

cpi_htocp_l

Description Converts the src value from Host format into Motorola format.


unsigned long cpi_htocp_l (unsigned long src)


Return Values The value passed in formatted properly.

Details None.




CPI Library Software Interface Manual cpi_htocp_s

IDX GLSTOC

cpi_htocp_s

Description Converts the src value from Host format into Motorola format.


unsigned short cpi_htocp_s (unsigned short src)


Return Values The value passed in formatted properly.

Details None.




cpi_init CPI Library Software Interface Manual

IDX GLSTOC

cpi_init

Description Sets up the CPI library.


short cpi_init (short sInt, char *idstring)

sInt Not used.idstring Not used.


CPI_ERROR

Details The sInt and idstring parameters are unused and are retained for compatibility. This function should be called only once per application.




CPI Library Software Interface Manual cpi_load_krnl

IDX GLSTOC

cpi_load_krnl

Description Loads the kernel into the TX board indicated by handle.


short cpi_load_krnl (TX_HANDLE handle, char *buff, short len, short *seqnum, unsigned long destaddr)

handle TX handle number.buff Pointer to buffer.len Length of buffer.


CPI_ERROR

Details The parameter buff contains a pointer to a piece of the kernel image of length len. The seqnum and destaddr parameters should be set before each call. Typically, this function would be called many times during a single load of the kernel.

cpi_load_krnl is for ISA boards only. PCI boards have their kernel pre-loaded to onboard flash memory.




cpi_open CPI Library Software Interface Manual

IDX GLSTOC

cpi_open

Description Opens a channel for synchronous I/O on the host.


TX_HANDLE cpi_open (unsigned short port, short mode, short *rcvr (short handle, short len))

port Combination of the TX board number and the channel number. Use the PORT macro to combine a board number and channel number into a port.

mode Unused and retained for backwards compatibility.

rcvr Unused and retained for backwards compatibility.

Return Values handleif successful

CPI_INVALID_HANDLEif an error occurs

Details TX_HANDLE is operating system specific. Since this return value is only ever passed back to other CPI calls, it is not important to the application what this type actually is. When the handle needs to be used in a “wait” call (WaitForSingleObject in Windows, poll in UnixWare and Solaris), then use cpi_wait_obj(handle) to access the proper element for each operating system.

WaitForSingleObject (cpi_wait_obj (handle), 0);

Note: If writing multi-threaded applications, the thread that opens a channel should be the same thread that processes all I/O for that channel. Unpredictable behavior may result otherwise.




CPI Library Software Interface Manual cpi_pre_boot

IDX GLSTOC

cpi_pre_boot

Description Loads a small program into the TX board indicated by handle.


short cpi_pre_boot (TX_HANDLE handle, char *buffer, short len, unsigned short off, short xqt)

handle TX handle number.buffer Pointer to buffer.len Length of buffer.off Location where code is to be copied.xpt Indicates whether the preebooter should

execute.


CPI_ERROR

Details The parameter buffer contains a pointer to a segment of the load image of length len. The parameter off should be set to where to copy the code and xqt != 0 indicates that the prebooter should execute after the copy of the code into the CP is completed.

cpi_pre_boot is for ISA boards only. PCI boards have a preboot code in onboard flash memory.




cpi_read_dpr CPI Library Software Interface Manual

IDX GLSTOC

cpi_read_dpr

Description Reads from the dual-ported RAM of the TX board indicated by handle into the buffer specified.


short cpi_read_dpr (TX_HANDLE handle, char *buffer, unsigned long off, short len)

handle TX handle number.buffer Pointer to buffer.off Location where code is to be copied.len Length of buffer.


CPI_ERROR

Details The read starts at off in the DPR and reads len number of bytes.




CPI Library Software Interface Manual cpi_send

IDX GLSTOC

cpi_send

Description Sends a packet synchronously on the channel indicated by handle.


short cpi_send (TX_HANDLE handle, CPIPKT *buffer)

handle TX handle number.buffer Pointer to buffer.


CPI_ERROR

Details The buffer should be a properly formatted CP packet. The destination board and channel number is set by the application programmer in the header portion of the buffer.

Note: When posting cpi_send to a PCI board, the function will not return until the board acknowledges the sent packet.




cpi_wait_msg CPI Library Software Interface Manual

IDX GLSTOC

cpi_wait_msg

Description Waits specified amount of time (in milliseconds) and returns a packet if one is received.


short cpi_wait_msg (TX_HANDLE handle, CPIPKT *buffer, short *len, long millisecs)

handle TX handle number.buffer Pointer to buffer.len Length of buffer.millisecs Amount of time to wait.


CPI_ERROR

CPI_TRUNCATEDReceived length is longer than the buffer length specified

CPI_TIMEOUTNo packet to receive

Details cpi_wait_msg recovers received packets from the channel associated with handle. Upon entry, len contains the size of the buffer. If there is a packet to receive, the length will be placed in len and the packet will be placed in the specified buffer.




CPI Library Software Interface Manual cpi_wait_obj

IDX GLSTOC

cpi_wait_obj

Description Returns the wait object for the channel associated with handle.


CPI_WAIT_TYPE cpi_wait_obj (TX_HANDLE handle)


Return Values The host operating system specific element to use to wait.

Details The wait object should be used when calling the host operating system’s native wait routine, such as WaitForSingleObject in Windows NT and Windows 2000 or poll for UNIX.




cpi_write_dpr CPI Library Software Interface Manual

IDX GLSTOC

cpi_write_dpr

Description Writes to the dual-ported RAM of the CP indicated by handle.


short cpi_write_dpr (TX_HANDLE handle, char *buffer, unsigned long off, short len)

handle TX handle number.buffer Pointer to buffer.off Location where code is to be copied.len Length of buffer.


CPI_ERROR

Details cpi_write_dpr writes from buff, len number of bytes starting at off in the DPR.




IDX GLSTOC

Index

Aasynchrous mode 14

Ccpi_check_bs 22cpi_clear_stats 23cpi_close 24cpi_cptoh_l 25cpi_cptoh_s 26cpi_exec_krnl 27cpi_force_bs 28cpi_get_board 29cpi_get_data 30cpi_get_eeprom 31cpi_get_error_str 32cpi_get_last_error 33cpi_get_resources 34cpi_get_stats 35cpi_htocp_l 36cpi_htocp_s 37cpi_init 38cpi_load_krnl 39cpi_open 40cpi_pre_boot 41cpi_read_dpr 42cpi_send 43CPI_SUCCESS 14cpi_wait_msg 44cpi_wait_obj 45cpi_write_dpr 46cpia_get_data 16cpia_intr 17cpia_open 18cpia_rxnotify 19cpia_send 20cpia_txnotify 21

NMS Communications

Send Feedback to NMS

Ffunction compatibility 14

Llogical port 7

NNot 14

Pport conflicts 8

Ssynchronous mode 14

UUtilities

txalarm 6

47

Doc Dept


Index CPI Library Software Interface Manual

IDX GLSTOC

48

Send Feedb

NMS Communications

ack to NMS Doc Dept


cpi library software interface manual · cpi library software interface manual ... multi-vendor...

Documents