Dialogic TX Series SS7 Boards

CPI Library Developers Reference Manual

July 2009

64-0458-01
www.dialogic.com

CPI Library Developer's Reference Manual

Copyright and legal notices

Copyright 1999-2009 Dialogic Corporation. All Rights Reserved. You may not reproduce this document in
whole or in part without permission in writing from Dialogic Corporation at the address provided below.
All contents of this document are furnished for informational use only and are subject to change without notice
and do not represent a commitment on the part of Dialogic Corporation or its subsidiaries (Dialogic).
Reasonable effort is made to ensure the accuracy of the information contained in the document. However,
Dialogic does not warrant the accuracy of this information and cannot accept responsibility for errors,
inaccuracies or omissions that may be contained in this document.
INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH DIALOGIC PRODUCTS. NO LICENSE,
EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY
THIS DOCUMENT. EXCEPT AS PROVIDED IN A SIGNED AGREEMENT BETWEEN YOU AND DIALOGIC, DIALOGIC
ASSUMES NO LIABILITY WHATSOEVER, AND DIALOGIC DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY,
RELATING TO SALE AND/OR USE OF DIALOGIC PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING
TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY INTELLECTUAL
PROPERTY RIGHT OF A THIRD PARTY.
Dialogic products are not intended for use in medical, life saving, life sustaining, critical control or safety systems,
or in nuclear facility applications.
Due to differing national regulations and approval requirements, certain Dialogic products may be suitable for use
only in specific countries, and thus may not function properly in other countries. You are responsible for ensuring
that your use of such products occurs only in the countries where such use is suitable. For information on specific
products, contact Dialogic Corporation at the address indicated below or on the web at www.dialogic.com.
It is possible that the use or implementation of any one of the concepts, applications, or ideas described in this
document, in marketing collateral produced by or on web pages maintained by Dialogic may infringe one or more
patents or other intellectual property rights owned by third parties. Dialogic does not provide any intellectual
property licenses with the sale of Dialogic products other than a license to use such product in accordance with
intellectual property owned or validly licensed by Dialogic and no such licenses are provided except pursuant to a
signed agreement with Dialogic. More detailed information about such intellectual property is available from
Dialogics legal department at 9800 Cavendish Blvd., 5th Floor, Montreal, Quebec, Canada H4M 2V9. Dialogic
encourages all users of its products to procure all necessary intellectual property licenses required to implement
any concepts or applications and does not condone or encourage any intellectual property infringement and
disclaims any responsibility related thereto. These intellectual property licenses may differ from country to
country and it is the responsibility of those who develop the concepts or applications to be aware of and comply
with different national license requirements.
Any use case(s) shown and/or described herein represent one or more examples of the various ways, scenarios
or environments in which Dialogic products can be used. Such use case(s) are non-limiting and do not
represent recommendations of Dialogic as to whether or how to use Dialogic products.
Dialogic, Dialogic Pro, Brooktrout, Diva, Cantata, SnowShore, Eicon, Eicon Networks, NMS Communications, NMS
(stylized), Eiconcard, SIPcontrol, Diva ISDN, TruFax, Exnet, EXS, SwitchKit, N20, Making Innovation Thrive,
Connecting to Growth, Video is the New Voice, Fusion, Vision, PacketMedia, NaturalAccess, NaturalCallControl,
NaturalConference, NaturalFax and Shiva, among others as well as related logos, are either registered
trademarks or trademarks of Dialogic Corporation or its subsidiaries. Dialogic's trademarks may be used publicly
only with permission from Dialogic. Such permission may only be granted by Dialogics legal department at 9800
Cavendish Blvd., 5th Floor, Montreal, Quebec, Canada H4M 2V9. Any authorized use of Dialogic's trademarks will
be subject to full respect of the trademark guidelines published by Dialogic from time to time and any use of
Dialogics trademarks requires proper acknowledgement.
Windows is a registered trademark of Microsoft Corporation in the United States and/or other countries. The
names of actual companies and product mentioned herein are the trademarks of their respective owners.
This document discusses one or more open source products, systems and/or releases. Dialogic is not responsible
for your decision to use open source in connection with Dialogic products (including without limitation those
referred to herein), nor is Dialogic responsible for any present or future effects such usage might have, including
without limitation effects on your products, your business, or your intellectual property rights.

Dialogic Corporation

Revision history
Revision

Release date

1.0

Notes
GJG

1.2

March 1999

GJG

1.3

November 2000

GJG, SS7 3.6

1.5

August 2001

GJG, SS7 3.8 beta

1.6

November 2003

MCM, SS7 4.0 beta

1.7

April 2004

MCM, SS7 4.0

1.8

June 2008

SRG, SS7 5.0

64-0458-01

July 2009

LBG, SS7 5.1

Last modified: July 7, 2009

Refer to www.dialogic.com for product updates and for information about support policies, warranty
information, and service offerings.

Table Of Contents
Chapter 1: Introduction .................................................................................7
Chapter 2: Overview of the CPI library ..........................................................9
Development environment............................................................................ 9
CPI library definition ...................................................................................10
Accessing the TX device driver using Windows................................................11
Accessing the TX device driver using UNIX .....................................................11
Chapter 3: Function reference .....................................................................13
Function summary......................................................................................13
Using the function reference ........................................................................15
cpia_chkey ................................................................................................16
cpia_get_data............................................................................................17
cpia_intr ...................................................................................................18
cpia_open .................................................................................................19
cpia_rxnotify .............................................................................................20
cpia_send .................................................................................................21
cpia_txnotify .............................................................................................22
cpi_check_bs .............................................................................................23
cpi_close...................................................................................................24
cpi_cptoh_l ...............................................................................................25
cpi_cptoh_s ...............................................................................................26
cpi_force_bs ..............................................................................................27
cpi_get_board............................................................................................28
cpi_get_data .............................................................................................29
cpi_get_dev_info........................................................................................30
cpi_get_error_str .......................................................................................31
cpi_get_last_error ......................................................................................32
cpi_get_resources ......................................................................................33
cpi_htocp_l ...............................................................................................34
cpi_htocp_s ...............................................................................................35
cpi_init .....................................................................................................36
cpi_nmi ....................................................................................................37
cpi_open ...................................................................................................38
cpi_read_control ........................................................................................39
cpi_read_dpr .............................................................................................40
cpi_send ...................................................................................................41
cpi_set_cpid ..............................................................................................42
cpi_show_stats ..........................................................................................43
cpi_stats ...................................................................................................44
cpi_wait_msg ............................................................................................45
cpi_wait_obj ..............................................................................................46
cpi_write_control........................................................................................47
cpi_write_dpr ............................................................................................48

Dialogic Corporation

Introduction

The CPI library provides a consistent communications mechanism to the TX board,

regardless of the operating system employed on the host (Windows or UNIX). The
Dialogic TX Series SS7 Boards CPI Library Developer's Reference Manual explains
how to use the CPI library to facilitate application development on NMS
Communications TX boards.
Note: The product(s) to which this document pertains is/are among those sold by
NMS Communications Corporation (NMS) to Dialogic Corporation (Dialogic) in
December 2008. Certain terminology relating to the product(s) has been changed,
whereas other terminology has been retained for consistency and ease of reference.
For the changed terminology relating to the product(s), below is a table indicating
the New Terminology and the Former Terminology. The respective terminologies
can be equated to each other to the extent that either/both appear within this
document.
Former terminology

Current terminology

NMS SS7

Dialogic NaturalAccess Signaling Software

Natural Access

Dialogic NaturalAccess Software

Dialogic Corporation

Overview of the CPI library

Development environment
The TX host application development environment (shown in the following
illustration) consists of libraries that enable you to configure and control the protocol
engines loaded on the TX board. This manual describes the CPI library.
Host application

T1/E1
library

H.100/H.110
library

TX SWI
library

Loader
library

CPI library

TX board resources

Dialogic Corporation

Overview of the CPI library

CPI Library Developer's Reference Manual

CPI library definition

A channel is the basic unit of communication to the TX boards. The channel provides
a multiplexing or de-multiplexing packet-based interface between the host operating
system and one or more TX boards. The combination of board number (CP number)
and channel is known as a logical port.
To implement multiplexing and de-multiplexing, a header is inserted on all packets
transferred between the host and the TX boards. The header includes the following
information:
Source channel

Source CP

Destination
channel

Destination
CP

Length

Data

1 byte

1 byte

1 byte

1 byte

2 bytes

1 through 1512 bytes

TX boards are numbered 1 through 16. The host is assigned the CP number of 0. The
length field indicates the length of the entire data packet, including the header.
Channels are numbered 0 through 255, and channel 0 is reserved.
A channel number is assigned to a task on the TX board by a prior arrangement,
similar to the ports concept used in TCP/UDP. To minimize conflicts, NMS
recommends the following channel usage:
Channel

Usage

0 through 31

Reserved

32 through 127

Available for use by applications

128 through 255

Reserved

The communications mechanism is similar to UDP datagrams. Tasks on the TX board

register to receive all data from a particular channel. Host applications pick an
unused channel to use and register to receive all packets on the chosen channel.
Communications are accomplished through 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 by returning an indication of success or failure of
the request. This response is at the application level, not at the CPI layer.
The following code sample provides a list of channels used by tasks on the TX board.
These channels are defined in the dpriface.h file.
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define

10

PT_MGR
PT_OACDRV
PT_SWI
PT_CONSOLE
PT_LOADER
PT_DEBUG
PT_MVIP
PT_T1E1C
PT_T1E1S
PT_INF
PT_SS7MON
PT_ARP
PT_SS7MON2
PT_ISUP
PT_MTP
PT_TCAP
PT_IUP
PT_TXMON
PT_TUP
PT_SCCP

0x00
0x01
0x03
0x06
0x07
0x08
0x09
0x0A
0x0B
0x0C
0x0F
0x12
0x13
0x14
0x15
0x17
0x18
0x19
0x1D
0x1E

/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*

Host Control Manager [$manager channel] */

Open Access Interface to driver */
Switching Control Channel */
Console Channel */
Loader Channel */
Debug Channel */
MVIP Control Channel */
T1/E1 Control Channel */
T1/E1 Status Channel */
Alarm Manager (raw alarm channel) */
SS7 Monitor API port #1 */
ARP Protocol Channel */
SS7 Monitor API port #2 */
SS7 ISUP Task Channel */
SS7 MTP Task Channel */
SS7 TCAP Task Channel */
SS7 IUP Task Channel */
TX Monitor Task Channel */
SS7 TUP Task Channel */
SS7 SCCP Task Channel */

Dialogic Corporation

CPI Library Developer's Reference Manual

Overview of the CPI library

The txcpi.h include file provides all CPI library function prototypes and literal
definitions. Always use the structure packing compile option when compiling source
code that uses functions from this library.

Accessing the TX device driver using Windows

The CPI library uses standard Windows routines to access the TX kernel mode device
driver. The interface between the library and the driver is based on a 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.
The host can receive packets asynchronously. Windows provides standard
mechanisms for receiving unsolicited packets. The library posts read calls to the
driver that 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. Use cpi_wait_obj to retrieve
the handle to pass to these Windows calls. Pass zero in the dwTimeout parameter,
which is equivalent to polling for packets, to tell Windows calls to return
immediately. The same parameter can be set to infinite, in which case it does not
return until there is a packet (when using WaitForSingleObject) or one of the list
of handles had something to report (when using WaitForMultipleObjects).
A flow control mechanism queues TX board messages 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 exists for packets sent from a host-based application
to the TX board.

Accessing the TX device driver using UNIX

The TX driver for UNIX systems is a streams driver and is directly accessed through
the standard system calls, open, close, putmsg, getmsg, and ioctl.
Because the driver communicates with applications using a specific driver-toapplication protocol, direct access is not recommended.
The CPI library uses a TX_HANDLE type as an object on which all I/O is done. In
UNIX systems, pass the TX_HANDLE to cpi_wait_obj to obtain a standard UNIX file
descriptor. The host UNIX system can asynchronously receive packets from a TX
board by using the poll system call or the select system call.

Dialogic Corporation

11

Overview of the CPI library

CPI Library Developer's Reference Manual

For example, to wait on both input and packets from a TX board, use poll on a UNIX
system as follows:
.
struct pollfd fds[2];
.
.
cpi_init(0, &str);
mode = CPIM_PORT;
port = PORT((S16)board, (S16)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;
/* TX 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))
{
< Error handling code >
}
if (fds[i].revents & POLLIN)
{
/* TX 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 */

12

Dialogic Corporation

Function reference

Function summary
The CPI library provides synchronous and asynchronous interfaces to the TX board:
Interface

Description

Synchronous

Can allow packet loss and can introduce data overload conditions.

Adequate for simple applications but not as efficient as asynchronous interfaces.

Can stall multiple-threaded calling applications until a response is received from

the TX host-based driver.

Does not include a flow control mechanism, causing dropped packets and
resource depletion during heavy packet traffic, whether from host to TX board or
from TX board to host.

Asynchronous

Used when opening a CPI channel using cpi_open.

Recommended for all development because it is more efficient than synchronous

interfaces.

Does not stall the calling application because all responses from the driver are
handled as independent events. For certain operating systems, multiple-threaded
applications must use an asynchronous interface. For operating systems that do
not impose this restriction, an asynchronous interface is still recommended.

Includes flow control mechanisms to ensure that no packets are dropped and no
depletion conditions are introduced due to host traffic.

Used when opening a CPI channel with cpia_open.

Not all CPI library functions can handle asynchronous I/O and synchronous I/O
functions. Mixed-mode (synchronous and asynchronous) I/O on the same handle is
not allowed. The following table summarizes the CPI functions and their modality. An
asterisk (*) indicates a user-supplied function.
Function

Synchronous

Asynchronous

cpia_chkey

No

Yes

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_check_bs

Yes

Yes

cpi_close

Yes

Yes

cpi_cptoh_l

Yes

Yes

Dialogic Corporation

13

Function reference

CPI Library Developer's Reference Manual

Function

Synchronous

Asynchronous

cpi_cptoh_s

Yes

Yes

cpi_force_bs

Yes

Yes

cpi_get_board

Yes

Yes

cpi_get_data

Yes

No

cpi_get_dev_info

Yes

Yes

cpi_get_error_str

Yes

Yes

cpi_get_last_error

Yes

Yes

cpi_get_resources

Yes

Yes

cpi_htocp_l

Yes

Yes

cpi_htocp_s

Yes

Yes

cpi_init

Yes

Yes

cpi_nmi

Yes

Yes

cpi_open

Yes

No

cpi_read_control

Yes

Yes

cpi_read_dpr

Yes

Yes

cpi_send

Yes

No

cpi_set_cpid

Yes

Yes

cpi_show_stats

Yes

Yes

cpi_stats

Yes

Yes

cpi_wait_msg

Yes

No

cpi_wait_obj

Yes

Yes

cpi_write_control

Yes

Yes

cpi_write_dpr

Yes

Yes

14

Dialogic Corporation

CPI Library Developer's Reference Manual

Function reference

Using the function reference

This section provides an alphabetical reference to the CPI library functions. A typical
function definition includes the following:
Prototype

The prototype is shown followed by a listing of the function arguments. Dialogic data
types include:

U8 (8-bit unsigned)

S8 (8-bit signed)

U16 (16-bit unsigned)

S16 (16-bit signed)

U32 (32-bit unsigned)

S32 (32-bit signed)

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 that the function was initiated.
Subsequent events indicate the status of the operation.

Dialogic Corporation

15

Function reference

CPI Library Developer's Reference Manual

cpia_chkey
Returns the user-provided key associated with the specified handle.
Prototype
#include txcpi.h
void *cpia_chkey ( TX_HANDLE handle)
Argument

Description

handle

TX_HANDLE associated with the channel.

Return values
Return value

Description

NULL

Provided TX handle is not a handle to an asynchronous channel.

Details
One of the parameters provided to cpia_open is a user-controlled key named
chkey. Applications can use cpia_chkey to get the key associated with the open.
For asynchronous receive and transmit complete notifications, it is not necessary to
call cpia_chkey since the users key is provided as a parameter to cpia_rxnotify
and cpia_txnotify.

16

Dialogic Corporation

CPI Library Developer's Reference Manual

Function reference

cpia_get_data
Obtains a packet of data from the specified channel.
Prototype
#include txcpi.h
S16 cpia_get_data ( TX_HANDLE handle, CPIPKT *buffer, S16*len)
Argument

Description

handle

TX_HANDLE associated with the asynchronous transmit completion.

buffer

Pointer to the CPIPKT buffer to store the received packet.

len

Pointer to the size of the buffer on input and the length of the received packet on output.

Return values
Return value

Description

CPI_SUCCESS

Packet successfully received.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

CPI_INVALID_MODE

Handle is not open for asynchronous I/O.

CPI_TRUNCATED

Received packet was larger than the passed buffer.

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 are copied to buffer and CPI_TRUNCATED is returned. The
length of the received packet is placed in len.
Call cpia_get_data from within cpia_rxnotify. Calling cpia_get_data from
outside cpia_rxnotify can result in communication errors.

Dialogic Corporation

17

Function reference

CPI Library Developer's Reference Manual

cpia_intr
Drains the asynchronous transmit acknowledgements and checks for any waiting
received packets.
Prototype
#include txcpi.h
CPI_ERR_TYPE cpia_intr ( TX_HANDLE handle)
Argument

Description

handle

TX_HANDLE that has had an I/O event.

Return values
Return value

Description

CPI_SUCCESS

Asynchronous processing completed successfully.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

CPI_INVALID_MODE

Handle is not open for asynchronous I/O.

Details
Call cpia_intr when an I/O event is detected. Detecting such events is operating
system-specific (WaitForMultipleObjects for Windows or poll for UNIX).
Note: Asynchronous transmit complete messages are processed before received
messages.

18

Dialogic Corporation

CPI Library Developer's Reference Manual

Function reference

cpia_open
Opens a channel for asynchronous I/O on the host.
Prototype
#include txcpi.h
TX_HANDLE cpia_open ( void *chkey, U16 board, U16 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)))
Argument

Description

chkey

User-controlled key 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
Return value

Description

CPI_INVALID_HANDLE

Unable to open the channel.

Details
Use cpia_open to open a channel for aynchronous I/O. Use cpi_open to open a
channel for synchronous I/O. Mixed mode I/O on a given channel is not possible,
either with a single TX_HANDLE or multiple TX_HANDLEs. If successful, TX_HANDLE
is returned.
See also
cpia_intr, cpia_rxnotify, cpia_txnotify

Dialogic Corporation

19

Function reference

CPI Library Developer's Reference Manual

cpia_rxnotify
Notifies upper layers of messages to be received.
Prototype
void cpia_rxnotify ( TX_HANDLE handle, void *chkey)
Argument

Description

handle

TX_HANDLE on which the message was received.

chkey

Channel key provided when the handle was opened.

Details
Provide cpia_rxnotify as a parameter to cpia_open. The CPI library calls this
function as a result of a call to cpia_intr when receive packets are pending for the
given channel.
cpia_rxnotify calls cpia_get_data to receive the incoming message.

20

Dialogic Corporation

CPI Library Developer's Reference Manual

Function reference

cpia_send
Asynchronously sends a packet of data over the specified channel.
Prototype
#include txcpi.h
S16 cpia_send ( TX_HANDLE handle, CPIPKT *buffer, void *user_tx_key)
Argument

Description

handle

TX_HANDLE associated with the channel.

buffer

Pointer to a CPIPKT structure containing data to send.

user_tx_key

Pointer to a user-defined key returned when I/O completes.

Return values
Return value

Description

CPI_SUCCESS

Packet send successfully started. Completes when cpia_txnotify is called.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

CPI_INVALID_MODE

Handle is not open for asynchronous I/O.

CPI_QUEUE_FULL

Maximum number of pending asynchronous I/O requests 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 (that is, there is no cpia_cancel).
Final I/O result notification is handled by cpia_intr and cpia_txnotify callback.
The CPIPKT structure pointed to by the buffer parameter cannot be freed, re-used,
or re-allocated until the final disposition of the packet is determined with cpia_intr
and cpia_txnotify. Failure to adhere to this requirement causes unreliable and
unpredictable results.
See also
cpia_open

Dialogic Corporation

21

Function reference

CPI Library Developer's Reference Manual

cpia_txnotify
Processes an asynchronous transmit completion 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)
Argument

Description

handle

TX_HANDLE associated with the asynchronous transmit completion.

chkey

Pointer to the channel key provided when the handle was opened.

buffer

CPIPKT buffer pointer provided when cpia_send was called.

user_tx_key

Pointer to the user key provided when cpia_send was called.

ccode

I/O completion code.

Details
Provide cpia_txnotify as a parameter to cpia_open. The CPI library calls this
function as a result of a call to cpia_intr when previously issued transmit requests
(with cpia_send) complete for the given channel. When cpia_txnotify is called, or
any time thereafter, the application can free the corresponding CPIPKT passed in on
cpia_send. Failure to adhere to this rule results in communications errors.

22

Dialogic Corporation

CPI Library Developer's Reference Manual

Function reference

cpi_check_bs
Determines whether the TX board specified by handle is in the boot state.
Prototype
#include txcpi.h
S16 cpi_check_bs ( TX_HANDLE handle, CPIBS *bsp)
Argument

Description

handle

TX handle number of the board to check.

bsp

Pointer to the location where the boot state is to be returned:

typedef struct _CPIBS
{
U16 state;
U8
reg[5];
} CPIBS;
Refer to the Details section for valid boot states.

Return values
Return value

Description

CPI_SUCCESS

Boot state determined.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

Details
The bsp.state is loaded with the boot state (low byte) and the CSR (high byte). The
boot state can be one of the following values:
State

Description

BS_BOOT

Waiting to begin PREBOOT.

BS_READY

KERNEL loaded, initialized, and ready

BS_INIT

KERNEL is initializing.

BS_DOWN

KERNEL not responding.

BS_BERR

Bus error indicated by KERNEL.

BS_LOADING

Loading block of KERNEL.

BS_PREBOOTING

PREBOOT running, not ready for KERNEL.

BS_WAIT_KERNEL

PREBOOT complete, waiting for KERNEL.

The reg element in the structure is unused.

See also
cpi_force_bs

Dialogic Corporation

23

Function reference

CPI Library Developer's Reference Manual

cpi_close
Closes the channel associated with the specified handle.
Prototype
#include txcpi.h
S16 cpi_close ( TX_HANDLE handle)
Argument

Description

handle

TX handle associated with the channel, returned from cpi_open or cpia_open.

Return values
Return value

Description

CPI_SUCCESS

Channel successfully closed.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

Details
Applications that open CPI channels must close all channels before the application
terminates. Failing to close a channel can leave resources in an indeterminate state.

24

Dialogic Corporation

CPI Library Developer's Reference Manual

Function reference

cpi_cptoh_l
Converts the src value from the TX board native format to the host format.
Prototype
#include txcpi.h
U32 cpi_cptoh_l ( U32 src)
Argument

Description

src

Value in TX native format to be converted.

Details
The value of src is converted to the host format and placed in the return value.
Note: This function performs no operation on a host system that uses the same
native format as the TX board (TX boards use the Motorola native format). However,
for code portability, NMS recommends that you always use the conversion functions,
even with host systems that are already in Motorola format.

Dialogic Corporation

25

Function reference

CPI Library Developer's Reference Manual

cpi_cptoh_s
Converts the src value from the TX board native format to the host format.
Prototype
#include txcpi.h
U16 cpi_cptoh_s ( U16 src)
Argument

Description

src

Value in TX native format to be converted.

Details
The value of src is converted to the host format and placed in the return value.
Note: This function performs no operation on a host system that uses the same
native format as the TX board (TX boards use the Motorola native format). However,
for code portability, NMS recommends that you always use the conversion functions,
even with host systems that are already in Motorola format.

26

Dialogic Corporation

CPI Library Developer's Reference Manual

Function reference

cpi_force_bs
Boots the TX device indicated by the specified handle. The board performs a
complete reset, including loading the operating system kernel from on-board flash
memory.
Prototype
#include txcpi.h
S16 cpi_force_bs ( TX_HANDLE handle)
Argument

Description

handle

TX handle number.

Return values
Return value

Description

CPI_SUCCESS

Reset of the TX board successfully started.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

Details
cpi_force_bs triggers the board to reboot from the TX operating system that is
stored in on-board flash memory. All current processing on the board is aborted.
When the board reset completes, cpi_check_bs returns a state of BS_READY.

Dialogic Corporation

27

Function reference

CPI Library Developer's Reference Manual

cpi_get_board
Returns the board number and channel number associated with the specified
handle.
Prototype
#include txcpi.h
S16 cpi_get_board ( TX_HANDLE handle, U8 *board, U8 *chan)
Argument

Description

handle

TX handle number.

board

Pointer to a location to return the TX board number.

chan

Pointer to a location to return the channel number.

Return values
Return value

Description

CPI_SUCCESS

Board and channel numbers returned (as board and chan).

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

28

Dialogic Corporation

CPI Library Developer's Reference Manual

Function reference

cpi_get_data
Recovers received packets from the channel associated with the specified handle.
Prototype
#include txcpi.h
S16 cpi_get_data ( TX_HANDLE handle, CPIPKT *buffer, S16 *len)
Argument

Description

handle

TX handle associated with the channel.

buffer

Pointer to a location to store the received packet.

len

Pointer to the length of the buffer on input and the length of the received packet on
output.

Return values
Return value

Description

CPI_SUCCESS

Packet successfully received.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

CPI_TRUNCATED

Received length is longer than the specified buffer length.

Details
Specify the length of the buffer in the len parameter in the call to cpi_get_data. If
there is no packet to receive, cpi_get_data returns CPI_SUCCESS and len is set to
zero. If there is a packet, cpi_get_data returns CPI_SUCCESS, the length is placed
in len, and the packet is copied into the specified buffer.

Dialogic Corporation

29

Function reference

CPI Library Developer's Reference Manual

cpi_get_dev_info
Retrieves device information for available TX boards.
Prototype
#include txcpi.h
CPI_ERR_TYPE cpi_get_dev_info ( CPI_DEV_INFO *devinfo, U16 *numdevs)
Argument

Description

devinfo

Pointer to an array of device information structures.

numdevs

Pointer to the number of entries in the devinfo array on input and the number of entries
populated on output (number of detected TX devices).

Return values
Return value

Description

CPI_SUCCESS

Information about the set of detected TX devices provided in devinfo.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

Details
Use cpi_get_dev_info to determine the PCI bus and slot for each installed TX board
when assigning CP numbers to the detected boards.
See also
cpi_set_cpid

30

Dialogic Corporation

CPI Library Developer's Reference Manual

Function reference

cpi_get_error_str
Returns an ASCII string associated with the errnum passed to the function.
Prototype
#include txcpi.h
S8 *cpi_get_error_str ( CPI_ERR_TYPE errnum)
Argument

Description

errnum

CPI library error number.

Return values
Return value

Description

Unknown error nnn

No match for the errnum parameter.

NULL

NULL terminated string containing a description of the errnum passed.

Details
When a CPI library function returns CPI_ERROR, use cpi_get_last_error to
determine the error code. Then use cpi_get_error_str to convert this errnum into
an ASCII string describing the error.

Dialogic Corporation

31

Function reference

CPI Library Developer's Reference Manual

cpi_get_last_error
Returns the error code for the most recent error that occurred in the library.
Prototype
#include txcpi.h
CPI_ERR_TYPE cpi_get_last_error()
Details
When a CPI library function returns CPI_ERROR, use cpi_get_last_error to
determine the error code. Then use cpi_get_error_str to convert this errnum into
an ASCII string describing the error.

32

Dialogic Corporation

CPI Library Developer's Reference Manual

Function reference

cpi_get_resources
Identifies the available TX boards.
Prototype
#include txcpi.h
S16 cpi_get_resources ( S16 max_cps, S32 *cps[])
Argument

Description

max_cps

Maximum CP number for which to return resource information.

cps

Pointer to an array of entries where CP types are returned.

Return values
Return value

Description

CPI_SUCCESS

Board types identified in cps array.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

Details
If a CP of the corresponding index does not exist, each element of the array cps is
filled with 0. If a CP for that index does exist, the array is filled with the TX board
types. The parameter max_cps indicates the number of CPs to check. The cps array
should have max_cps + 1 elements since the array is filled according to board
number. There is no board number 0 and this element is not used by this routine.

Dialogic Corporation

33

Function reference

CPI Library Developer's Reference Manual

cpi_htocp_l
Converts the src value from the host format to the TX board native format.
Prototype
#include txcpi.h
U32 cpi_htocp_l ( U32 src)
Argument

Description

src

Value in host native format to be converted.

Details
The value of src is converted to the TX board format and placed in the return value.
Note: This function performs no operation on a host system that uses the same
native format as the TX board (TX boards use the Motorola native format). However,
for code portability, NMS recommends that you always use the conversion functions,
even with host systems that are already in Motorola format.

34

Dialogic Corporation

CPI Library Developer's Reference Manual

Function reference

cpi_htocp_s
Converts the src value from the host format to the TX board native format.
Prototype
#include txcpi.h
U16 cpi_htocp_s ( U16 src)
Argument

Description

src

Value in host native format to be converted.

Details
The value of src is converted to the TX board format and placed in the return value.
Note: This function performs no operation on a host system that uses the same
native format as the TX board (TX boards use the Motorola native format). However,
for code portability, NMS recommends that you always use the conversion functions,
even with host systems that are already in Motorola format.

Dialogic Corporation

35

Function reference

CPI Library Developer's Reference Manual

cpi_init
Initializes the CPI library.
Prototype
#include txcpi.h
S16 cpi_init ( S16 dummy, S8 *idstring)
Argument

Description

dummy

Unused and retained for compatibility.

idstring

Unused and retained for compatibility.

Return values
Return value

Description

CPI_SUCCESS

CPI library successfully initialized.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

Details
Call cpi_init once per application.

36

Dialogic Corporation

CPI Library Developer's Reference Manual

Function reference

cpi_nmi
Controls the non-maskable interrupt (NMI) state on the TX board.
Prototype
#include txcpi.h
S16 cpi_nmi ( TX_HANDLE handle, U32 state)
Argument

Description

handle

TX handle number.

state

Desired state of the NMI signal. Valid values:

CPI_NMI_ASSERT
Assert NMI signal.
CPI_NMI_DEASSERT
Deassert NMI signal.

Return values
Return value

Description

CPI_SUCCESS

NMI signal state set as requested.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

Details
Use the NMI to halt all standard processing on the TX board and to place the board
into a state where diagnostic information can be read from the board. An application
should assert NMI first, and then deassert NMI to cause the TX board to begin
executing in this diagnostic state.

Dialogic Corporation

37

Function reference

CPI Library Developer's Reference Manual

cpi_open
Opens a channel for synchronous I/O on the host.
Note: NMS recommends that you use cpia_open to open all channels to TX boards.
Prototype
#include txcpi.h
TX_HANDLE cpi_open ( U16 port, S16 mode, S16 *rcvr (S16 handle, S16 len))
Argument

Description

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
Return value

Description

CPI_INVALID_HANDLE

Unable to open the channel.

Details
TX_HANDLE is operating-system specific. Since this return value is passed back only
to other CPI calls, the type is not important to the application. When the handle is
required for a wait call (WaitForSingleObject in Windows, poll in UNIX), use
cpi_wait_obj (handle) to access the proper element for each operating system, as
follows:
WaitForSingleObject (cpi_wait_obj (handle), 0);

For multiple-threaded applications, the thread that opens a channel should be the
same thread that processes all I/O for that channel. Otherwise, unpredictable
behavior can result.
See also
cpi_get_data, cpi_wait_msg

38

Dialogic Corporation

CPI Library Developer's Reference Manual

Function reference

cpi_read_control
Reads a set of control registers from a TX board.
Prototype
#include txcpi.h
S16 cpi_read_control ( TX_HANDLE handle, U16 basereg, U16 numreg, U32
*regarray, U16 *actcnt)
Argument

Description

handle

TX handle number.

basereg

Number of the base register to read (0 through max-1).

numreg

Count of registers to read.

regarray

Pointer to an array to hold register values.

actcnt

Pointer to the location where the actual number of registers read are stored.

Return values
Return value

Description

CPI_SUCCESS

Requested set of registers successfully read from TX board.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

Details
In addition to the dual-ported RAM shared between the host processor and the TX
board, a set of registers is used for communication control. Certain low-level
diagnostics on the TX board use the control registers to pass status information to
the host.
All control register access should be restricted to diagnostic applications. Do not use
this function for normal data transfer situations.
See also
cpi_write_control

Dialogic Corporation

39

Function reference

CPI Library Developer's Reference Manual

cpi_read_dpr
Reads from the dual-ported RAM of the TX board specified by handle.
Prototype
#include txcpi.h
S16 cpi_read_dpr ( TX_HANDLE handle, S8 *buffer, U32 off, S16 len)
Argument

Description

handle

TX handle number.

buffer

Pointer to a location to which the data is read.

off

Offset into the dual-ported RAM from which data is to be read.

len

Number of bytes to be read.

Return values
Return value

Description

CPI_SUCCESS

DPR successfully read into the buffer.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

Details
The read starts at off in the DPR and reads len number of bytes.
All dual-ported RAM is used for messaging and therefore should not be read directly.
Do not use this function for normal data transfer situations.

40

Dialogic Corporation

CPI Library Developer's Reference Manual

Function reference

cpi_send
Synchronously sends a packet of data over the channel indicated by the specified
handle.
Prototype
#include txcpi.h
S16 cpi_send ( TX_HANDLE handle, CPIPKT *buffer)
Argument

Description

handle

TX handle associated with the channel.

buffer

Pointer to a CPIPKT structure containing data to send.

Return values
Return value

Description

CPI_SUCCESS

Packet successfully sent to the TX board.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

Details
buffer should point to a properly formatted CP packet. The application sets the
destination board and channel number in the header portion of the buffer. The
function does not return until the board acknowledges the sent packet.

Dialogic Corporation

41

Function reference

CPI Library Developer's Reference Manual

cpi_set_cpid
Assigns a CP number to the TX board at the given PCI bus and slot number.
Prototype
#include txcpi.h
S16 cpi_set_cpid ( S16 type, U32 param1, U32 param2, U32 cpId)
Argument

Description

type

Type of board. The only supported type is CPI_PCI_BUS = PCI board.

param1

Bus number.

param2

Slot number.

cpId

TX board number to associate with the board at the given bus and slot.

Return values
Return value

Description

CPI_SUCCESS

CP number successfully assigned to the given PCI bus and slot number.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

Details
cpi_set_cpid assigns a board number (CP number) to the TX board at the indicated
PCI bus and slot number. After a TX board is assigned a CP number, the board can
be accessed by other CPI functions.

42

Dialogic Corporation

CPI Library Developer's Reference Manual

Function reference

cpi_show_stats
Displays common statistics to stdout using a series of printf calls.
Prototype
#include txcpi.h
S16 cpi_show_stats ( TX_STATS_COMMON *stats)
Argument

Description

stats

Pointer to a location where common statistics information is written.

Return values
Return value

Description

CPI_SUCCESS

Statistics successfully displayed to stdout.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

Details
cpi_show_stats enables an application to display all common statistics in a
standardized format. All statistics definitions can be found in the txstats.h include
file.
See also
cpi_stats

Dialogic Corporation

43

Function reference

CPI Library Developer's Reference Manual

cpi_stats
Obtains per-channel statistics synchronously.
Prototype
#include txcpi.h
CPI_ERR_TYPE cpi_stats ( TX_HANDLE handle, U32 options,
TX_STATS_COMMON *stats)
Argument

Description

handle

TX_HANDLE associated with the channel.

options

Statistics collection operation. Refer to the Details section for valid values.

stats

Pointer to a location where statistics information is written.

Return values
Return value

Description

CPI_SUCCESS

Statistics request successfully completed.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

Details
cpi_stats enables an application to collect the per-channel statistics maintained by
the CPI library. All statistics definitions can be found in the txstats.h include file.
The CPI layer maintains a set of common statistics and optionally a set of layerspecific statistics. The common statistics are defined by the TX_STATS_COMMON
structure. Use the TX_STATS_NAME operation to get ASCII names of the common
statistics.
Use the options parameter to describe the type of statistics to return. The following
table lists the valid values for the options parameter:
#include txstats.h
Use this value...

To return...

TX_STATS_GET

Current statistics.

TX_STATS_ZERO

Current statistics, then zero the statistics.

TX_STATS_NAME

Names of common statistics.

TX_STATS_NAME_LAYER

Names of layer-specific statistics.

TX_STATS_DESC

A description of common statistics.

TX_STATS_DESC_LAYER

A description of layer-specific statistics.

See also
cpi_show_stats

44

Dialogic Corporation

CPI Library Developer's Reference Manual

Function reference

cpi_wait_msg
Waits a specified amount of time (in milliseconds) and returns a packet if one is
received.
Prototype
#include txcpi.h
S16 cpi_wait_msg ( TX_HANDLE handle, CPIPKT *buffer, S16*len, S32
millisecs)
Argument

Description

handle

TX handle associated with the channel.

buffer

Pointer to the address to which to copy the received buffer.

len

Pointer to the length of the buffer on input and the length of the received packet on
output.

millisecs

Amount of time to wait before returning the packet.

Return values
Return value

Description

CPI_SUCCESS

Packet successfully received in buffer.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

CPI_TIMEOUT

No packet to receive.

CPI_TRUNCATED

Received length is longer than the specified buffer length.

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

Dialogic Corporation

45

Function reference

CPI Library Developer's Reference Manual

cpi_wait_obj
Returns the wait object for the channel associated with the specified handle.
Prototype
#include txcpi.h
CPI_WAIT_TYPE cpi_wait_obj ( TX_HANDLE handle)
Argument

Description

handle

TX handle associated with the channel.

Return values
Return value

Description

CPI_INVALID_WAIT_HANDLE

Invalid TX handle.

Details
Use the wait object when calling the host operating system's native wait routine,
such as WaitForSingleObject in Windows or poll for UNIX.

46

Dialogic Corporation

CPI Library Developer's Reference Manual

Function reference

cpi_write_control
Writes a set of control registers to a TX board.
Prototype
#include txcpi.h
S16 cpi_write_control ( TX_HANDLE handle, U16 basereg, U16 numreg, U32
*regarray, U16 *actcnt)
Argument

Description

handle

TX handle number.

basereg

Number of the base register to write (0 through max-1).

numreg

Count of registers to write.

regarray

Pointer to an array holding the register values to be written.

actcnt

Pointer to the location to store the number of registers written.

Return values
Return value

Description

CPI_SUCCESS

Provided set of registers successfully written to the TX board.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

Details
In addition to the dual-ported RAM shared between the host processor and the TX
board, a set of registers is used for communication control. Certain low-level
diagnostics on the TX board use the control registers to control low-level, on-board
diagnostics.
All control register access should be restricted to diagnostic applications. Do not use
this function for normal data transfer situations.
See also
cpi_read_control

Dialogic Corporation

47

Function reference

CPI Library Developer's Reference Manual

cpi_write_dpr
Writes to the dual-ported RAM of the CP indicated by the specified handle.
Prototype
#include txcpi.h
S16 cpi_write_dpr ( TX_HANDLE handle, S8 *buffer, U32 off, S16 len)
Argument

Description

handle

TX handle number.

buffer

Pointer to a location to which the data is written.

off

Offset into the dual-ported RAM where data is written.

len

Number of bytes to be written.

Return values
Return value

Description

CPI_SUCCESS

Provided buffer successfully written to DPR.

CPI_ERROR

Call cpi_get_last_error to obtain the error code.

Details
cpi_write_dpr writes from buffer for len number of bytes starting at off in the
DPR.
All dual-ported RAM is used for messaging and should not be written directly. Do not
use this function for normal data transfer situations.

48

Dialogic Corporation

Index
A

cpi_set_cpid 42

asynchronous functions 13

cpi_show_stats 43

asynchronous transmit 18, 22

cpi_stats 44

cpi_wait_msg 45

board information 28, 30, 42

cpi_wait_obj 46

board number 28, 42

cpi_write_control 47

boot state 23, 27

cpi_write_dpr 48

cpia_chkey 16

channel usage 10

cpia_get_data 17

close channel 24

cpia_intr 18

close system call 11

cpia_open 19

control registers 39, 47

cpia_rxnotify 20

conversion 25, 26, 34, 35

cpia_send 21

CP number 28, 42

cpia_txnotify 22

CPI library definition 10

CPIPKT structure 21, 22, 29, 41, 45

cpi_check_bs 23

cpi_close 24

de-multiplexing 10

cpi_cptoh_l 25

development environment 9

cpi_cptoh_s 26

device information 30

cpi_force_bs 27

DPR 40, 48

cpi_get_board 28

dpriface.h 10

cpi_get_data 29

dual-ported RAM 40, 48

cpi_get_dev_info 30

cpi_get_error_str 31

errors 31, 32

cpi_get_last_error 32

cpi_get_resources 33

flow control 11

cpi_htocp_l 34

function summary 13

cpi_htocp_s 35

cpi_init 36

getmsg system call 11

cpi_nmi 37

cpi_open 38

initialize CPI library 36

cpi_read_control 39

ioctl system call 11

cpi_read_dpr 40

cpi_send 41

logical port 10

Dialogic Corporation

49

Index

CPI Library Developer's Reference Manual

multiplexing 10

select system call 11

send data 21, 41

NMI state 37

statistics 43, 44

non-maskable interrupt state 37

synchronous functions 13

open channel 19, 38

TX_STATS_COMMON structure 44

open system call 11

TX_STATS_NAME structure 44

operating systems 11, 11

txcpi.h 10

txstats.h 44

poll system call 11, 18, 46

port usage 10

UNIX 11

putmsg system call 11

wait object 46

receive data 17, 29

WaitForMultipleObjects 11, 18

resources 33

WaitForSingleObject 11, 46
Windows 11

50

Dialogic Corporation