7.3 Opening Ports

(Page 4 of 11 in this chapter)

7.3.1 Introduction

Ports are the primary resource on which AG Access operates and are used to execute telephony functions. A port contains physical and logical resources on the AG board and within the application process context.
This section describes how to open AG Access ports and start execution of a network protocol. A protocol must be executing in order to access DSP functions.
The following functions are discussed in this section:

Function

Description

adiOpenPort

Allocates an AG Access port.

adiClosePort

Halts and deallocates a port.

adiStartProtocol

Loads a Trunk Control Program (TCP) and starts the DSP.

adiStopProtocol

Halts the port's DSP and unloads the TCP.

adiGetPortInfo

Retrieves port status and configuration.

Function	Description
adiOpenPort	Allocates an AG Access port.
adiClosePort	Halts and deallocates a port.
adiStartProtocol	Loads a Trunk Control Program (TCP) and starts the DSP.
adiStopProtocol	Halts the port's DSP and unloads the TCP.
adiGetPortInfo	Retrieves port status and configuration.

7.3.2 Opening a Port

Initializing a port is a three-step process:

Invoke adiOpenDriver to obtain a driver handle.

Invoke adiOpenPort to open a port and obtain a port handle.

Invoke adiStartProtocol to start a protocol (also referred to as a Trunk Control Program or TCP).
After the AG driver is open, the application opens a port via adiOpenPort. This function allocates physical and logical resources to the application process. When opening ports, you must specify:

A driver handle returned from adiOpenDriver

A specific AG board

An MVIP timeslot and mode.
These three pieces of data uniquely address all resources required to open a port.
The adiOpenPort prototype is defined as:

#include <adi.h> RETCODE adiOpenPort ( unsigned drvid ; unsigned ag_board ; unsigned mvip_stream ; unsigned mvip_timeslot ; unsigned mvip_mode ; DWORD userid ; PORTHD *port_handle ) ;
The caller provides the drvid that was returned from adiOpenDriver. The drvid is used to communicate with the given ag_board. All commands to the port will be sent via the drvid driver instance. All events for the port will be received via the same driver instance.
The ag_board identifies the target board housing DSP resources that execute telephony functions. The ag_board passed to adiOpenPort corresponds to a board specified in the agmon configuration file. The agmon configuration file contains a Board directive identifying each board in the system.
The mvip_stream, mvip_timeslot, and mvip_mode are discussed in Section 7.3.3, MVIP Addressing.
The userid is designed to facilitate asynchronous programming. The caller supplies this value when opening the port; it is never interpreted by AG Access. The userid is echoed to the application in the event structure when events are delivered and can be used to correlate the port with an application context.
AG Access returns a port handle in the porthd variable. The porthd maps to an AG Access internal context that is referenced whenever a command is issued or an event is received on the port.
The adiOpenPort is an asynchronous function. It returns SUCCESS if the internal context is allocated and the open command is sent to the AG board. An ADIEVN_OPENPORT_DONE event is given to the application when the function completes execution.
The open port completion status is stored in the event value field and is successful if the value is ADI_REASON_FINISHED; otherwise, the value field contains an error code. If the port fails to open, the resources are still allocated to the calling process. The application must invoke adiClosePort to release these resources.

7.3.3 MVIP Addressing

Whenever a port is opened, the application must indicate which MVIP timeslots the port will use. MVIP timeslots perform the following functions: Transmit audio from the DSP to the line interface Receive audio from the line interface to the DSP Transmit signaling bits from the DSP to the line interface Receive signaling bits from the line interface to the DSP
The application specifies an mvip_stream, mvip_timeslot, and an mvip_mode when opening a port. AG Access uses these to calculate which streams and timeslots are allocated to the port. The mvip_stream and mvip_timeslot specify the base timeslot for the port's set, while the mvip_mode dictates how many timeslots are allocated.
The two most common modes are ADI_VOICE_DUPLEX and ADI_FULL_DUPLEX. The ADI_VOICE_DUPLEX mode is typically used with the NOCC protocol and allows media reception and transmission.
The ADI_FULL_DUPLEX mode is typically used when running a network protocol on the port. This mode allows both voice (inband) and network signaling transmission and reception.
The mvip_mode can be one of the following values: Value Description ADI_VOICE_INPUT The port receives inband data only. The data is received by the DSP on the given mvip_stream and mvip_timeslot. ADI_VOICE_OUTPUT The port transmits inband data only. The data is transmitted by the DSP on the given mvip_stream and mvip_timeslot. ADI_VOICE_DUPLEX The port receives and transmits inband data. The same mvip_stream and mvip_timeslot address is used by the DSP for transmitting and receiving. ADI_SIGNAL_INPUT The port receives out-of-band signaling only. The data is received by the DSP on the given mvip_stream and mvip_timeslot. ADI_SIGNAL_OUTPUT The port transmits out-of-band signaling only. The data is transmitted by the DSP on the given mvip_stream and mvip_timeslot. ADI_SIGNAL_DUPLEX The port receives and transmits network out-of-band signals. The same mvip_stream and mvip_timeslot address is used by the DSP for transmitting and receiving. ADI_FULL_DUPLEX This is both ADI_SIGNAL_DUPLEX and ADI_VOICE_DUPLEX. The port receives and transmits both inband media and out-of-band signaling.
If ADI_FULL_DUPLEX is specified, four timeslots are associated with the port. The first two timeslots reside on the given mvip_stream and are used for inband media transmission and reception. The second timeslot pair is for network signaling transmission and reception. The network signal timeslots reside on the given mvip_stream plus 1.
For example, if the mvip_stream and mvip_timeslot are 18:0, and the mvip_mode is ADI_FULL_DUPLEX, the following mapping takes place:
18:0 - Inband media input and output 19:0 - Network signaling input and output
Whenever an mvip_mode is specified that contains both a voice component and a signaling component, the signaling stream is always one greater than the audio stream. For example, if the mvip_stream is 18:1, and the mvip_mode is ADI_VOICE_INPUT + ADI_SIGNAL_INPUT, the audio is received on timeslot 18:1 and the signaling input is received on timeslot 19:1.
More detailed MVIP addressing examples are provided in Section 7.3.5, Example Port Configurations.
If multiple MVIP boards reside in the host computer, all switching commands for the port's timeslot should typically be performed before the port is opened.
For AG boards with no switch (AG-24/24+/30/48/60), the MVIP stream and slot specified, as well as the implied signaling stream, must be configured by MVIPSLOTS statements in the agmon configuration.
For AG boards that do have a switch (AG-8, AG-T1, AG-E1), specify local streams; stream 18 for voice and stream 19 for signaling. agmon will "nail up" these streams to the line interfaces if you configure ENABLEMVIP=NO in the agmon configuration. In this case, access the first line interface as stream 18, slot 0, mode ADI_FULL_DUPLEX. The second line is

Value	Description
`ADI_VOICE_INPUT`	The port receives inband data only. The data is received by the DSP on the given `mvip_stream` and `mvip_timeslot`.
`ADI_VOICE_OUTPUT`	The port transmits inband data only. The data is transmitted by the DSP on the given `mvip_stream` and `mvip_timeslot`.
`ADI_VOICE_DUPLEX`	The port receives and transmits inband data. The same `mvip_stream` and `mvip_timeslot` address is used by the DSP for transmitting and receiving.
`ADI_SIGNAL_INPUT`	The port receives out-of-band signaling only. The data is received by the DSP on the given `mvip_stream` and `mvip_timeslot`.
`ADI_SIGNAL_OUTPUT`	The port transmits out-of-band signaling only. The data is transmitted by the DSP on the given `mvip_stream` and `mvip_timeslot`.
`ADI_SIGNAL_DUPLEX`	The port receives and transmits network out-of-band signals. The same `mvip_stream` and `mvip_timeslot` address is used by the DSP for transmitting and receiving.
`ADI_FULL_DUPLEX`	This is both `ADI_SIGNAL_DUPLEX` and `ADI_VOICE_DUPLEX`. The port receives and transmits both inband media and out-of-band signaling.

7.3.4 Starting a Protocol

The final step to initialize a port is starting a protocol. The function adiStartProtocol initiates a network protocol for the port. This is a required step before using any call control or DSP functions. Once the protocol has started, the application can use the call control functions to place and answer calls.
Each network protocol is coded in a Trunk Control Program (TCP). The protocol selected must have been downloaded at system initialization time. The agmon program downloads all TCPs specified in the AG configuration file.
If the application is not using the protocol-independent call control model, then NOCC must be specified.
The adiStartProtocol function accepts an ADISTART parameter structure. This is a compound structure containing the following parameter structures:
ADICALLCTL ADIDIAL ADIDTMFDETECT ADICLEARDOWN ADIECHOCANCEL
These structures specify network tone parameters and audio detection parameters and are used by call control.
adiStartProtocol is an asynchronous function. The function returns SUCCESS if the command is sent to the AG board. AG Access generates an ADIEVN_STARTPROTOCOL_DONE event with the status in the event value field.

7.3.5 Example Port Configurations

The following two examples are common configurations and illustrate the relationship between MVIP addressing and protocol selection.

Example 1: AG-8 with DID trunks.

As discussed in the AG Access Installation Guide, you specify an AG-8 DID TCP (Trunk Control Protocol) in the agmon configuration file. The agmon utility downloads the TCP to the AG-8.
When opening the port for line 0 on the AG-8, the following MVIP stream, timeslot, and mode are specified:
mvip_stream = 18 mvip_timeslot = 0 mvip_mode = ADI_FULL_DUPLEX
This associates timeslot 18:0 for media input and output and timeslot 19:0 for network signaling input and output.
After the port is opened and a port handle is obtained, you must invoke adiStartProtocol and specify the TCP that was downloaded by agmon. For example, did0 is the DID protocol for both AG-8 and AG-T1 boards.

Example 2: ISDN network interface with AG-24+ for media processing

In this example, you do not want to run a protocol on the AG Access ports. The NOCC TCP must be included in the agmon configuration file. Furthermore, you must perform the switching commands necessary to route the inband data between the ISDN board and the AG-24+. If, for example, the inband data for line 0 is routed on stream 2 timeslot 0, the following MVIP stream, timeslot and mode are specified when opening the port:
mvip_stream = 2 mvip_timeslot = 0 mvip_mode = ADI_VOICE_DUPLEX
This associates timeslot 2:0 for media input and output. No timeslots are consumed for network signaling.
After the port is opened and a port handle has been obtained, you must invoke adiStartProtocol and specify the null protocol, NOCC.

7.3.6 Port Life-Cycle

Figure 30 is a timing diagram describing the sequence of functions and events for opening and starting a port.

: Open Port and Start Protocol Sequence

It is not necessary to invoke adiStopProtocol when closing the port. The adiStopProtocol is used if the application needs to change protocol parameters. The protocol must first be stopped and then started with the new parameters.
Figure 31 is a state transition diagram depicting the complete life-cycle for a single port.

: Port State Diagram

The port states depicted in Figure 31 are described below.
Idle: This is the initial port state. In this state, the application invokes adiOpenPort which allocates host resources and sends an open port command to the AG board.
Opening: The adiOpenPort is an asynchronous function. The port is in the opening state until an ADIEVN_OPENPORT_DONE event is received.
Openfailed: Resources on the host computer are allocated when adiOpenPort is invoked. If the AG board returns an ADIEVN_OPENPORT_DONE event with a failure code, AG Access does not release the local resources. In this case, the application must close the port. Closing the port ensures the port handle is invalidated by both the application programmer and AG Access.
Opened: When the application receives an ADIEVN_OPENPORT_DONE event and the reason is ADI_REASON_FINISHED (successful open), the port is opened.
Starting: The DSP is unavailable until the application starts a protocol. A protocol is started by invoking adiStartProtocol from the Opened state. adiStartProtocol is an asynchronous function that produces an ADIEVN_STARTPROTOCOL_DONE event. The application remains in the Starting state until the event arrives.
Started: If the protocol starts successfully, the port enters the started state and DSP resources are available. In general, the port remains in the Started state until the application is shut down.
Stopping: The application can stop an active protocol by invoking adiStopProtocol. This function halts DSP activity for the given port. AG Access generates an ADIEVN_STOPPROTOCOL_DONE event when the function completes.
Closing: The function adiClosePort stops all activity on the port's DSP and all port resources are deallocated. AG Access generates an ADIEVN_CLOSEPORT_DONE event when the function completes.

(Page 4 of 11 in this chapter)