2.1 Introduction

2.1.1 Point-to-Point Switching Terminology

2.1.2 Properties of Connections and Listeners

2.2 Point-to-Point Switching Connection Object

2.2.1 Creating a Connection

2.2.2 Setting the Talker for a Connection

2.2.3 Adding Listeners to a Connection

2.2.4 Removing Listeners from a Connection

2.2.5 Setting the Silence Pattern for a Connection

2.2.6 Opening a Connection

2.2.7 Closing a Connection

2.2.8 Destroying a Named Connection

2.3 Making One-Talker, One-Listener Connections

2.3.1 Making a Simplex Connection

2.3.2 Making a Duplex Connection

2.3.3 Making a Quad Connection

2.3.4 Disconnecting a Talker and a Listener

2.4 Restoring Initial Connections

2.5 Connection Transactions

2.5.1 Cancelling a Begin/Submit Transaction

2.6 Terminating a Point-to-Point Switching Client

2.7 Error Processing

2.8 PPX Hot Swap Support

2.8.1 Configuration for Unpopulated CompactPCI Slots

2.8.2 Client Connections

2.8.3 Switch Disabled Error

2.8.4 Switching Service Log Support

2.1 Introduction

This chapter provides a detailed explanation of the programming model for the Point-to-Point Switching service, and describes how to use it in a Natural Access application. It also presents a brief overview of basic Point-to-Point Switching service concepts and terms.

An application can use the Point-to-Point Switching service to:

• Work with connection objects

• Make one-talker, one-listener switch connections

• Perform atomic actions on groups of connections in a single transaction

2.1.1 Point-to-Point Switching Terminology

The following terms define the basic elements of the Point-to-Point Switching service:

Term	Definition
connection object	An internal data structure maintained by the PPX server, that is created when a switch connection is successfully opened. It records the state of the connection. In the Point-to-Point Switching service, a connection object can be considered to be an empty container until talkers and listeners are assigned to it.
connection handle	An identifier for a specific connection object.
connection	A logical path between two terminus entities. Within the Point-to-Point Switching service, a connection may have only one talker but can support multiple listeners.
terminus	A single access point to a switch block input or switch block output. A terminus contains a bus, a stream, a switch number, and a timeslot.
talker	The terminus that drives the output on the connection.
listener	The terminus that receives input from the connection.

2.1.2 Properties of Connections and Listeners

Point-to-Point Switching connections and Point-to-Point Switching listeners have unique properties:

• Switch connections established through the Point-to-Point Switching service have an ownership property.
  When a Point-to-Point Switching client creates a connection between two points, only the client that established the connection (who owns it) is allowed to break the connection (which disables output).

• Ownership can be overridden by assigning the connection a name, that allows different contexts bound to different clients to operate on the same connection points.

• Point-to-Point Switching listener points have an associated state value which is either BUSY or NOT_BUSY.
  Listener points that are connected to a talker are in the BUSY state. A listener point can be connected to a talker only when that point is in the NOT_BUSY state. Therefore, if talker point A is connected to listener point B, listener point B must be disconnected from talker A before it can be assigned to a new talker point C.

2.2 Point-to-Point Switching Connection Object

The fundamental element in the Point-to-Point Switching service is a connection object. A connection is basically a telephone call. Each connection can have one talker. The talker in the connection is driving the output for that connection. Each connection can have one or more listeners. The listeners are receiving the input from the connection.

Use the Point-to-Point Switching service to perform the following operations:

• Create a connection

• Set the talker for a connection

• Add listeners to a connection

• Remove listeners from a connection

• Set the silence pattern for a connection

• Open a connection

• Close a connection

• Destroy a named connection

2.2.1 Creating a Connection

A connection is created by calling ppxCreateConnection with a context. A handle (ppxhd) to the connection is returned. The connection handle is used to specify the connection when setting a talker or adding listeners to the connection. When a connection is initially created, there are no telephony bus timeslots associated with it.

A default idle bit pattern (a fixed 8-bit pattern) can be specified in the call to ppxCreateConnection. If there is no talker attached, any listeners added to the connection receive the default pattern sent on the stream attached to the listener.

In the following sections, an example application is used to demonstrate the Point-to-Point Switching functions. The example application runs a system in which incoming callers are placed on hold while waiting for an available operator. All callers that are on hold listen to the same voice message.

Figure 5 shows the creation of the connection, hold_message_block. A default pattern is set and a pointer to the connection is returned.

Figure 5. Creating a Connection Object

When creating a connection, you may assign a name to the connection. A named connection can be accessed by other applications or contexts, as discussed in Section 2.2.6, Opening a Connection. This also allows the ownership property to be over-ridden.

2.2.2 Setting the Talker for a Connection

ppxSetTalker sets a talker for a connection. The address of the talker is specified by the switch identification number, bus type (CTBUS or LOCAL), stream, and timeslot.

If there are listeners already attached to the connection, the Point-to-Point Switching service connects the listeners to the talker using underlying switch connections. The switch connections may involve the allocation of bus timeslots if the talkers and the listeners are on different boards. If there was a talker already attached to the connection, the original talker is automatically disconnected before the new talker is connected.

In the example shown in Figure 6, the talker is added to the hold_message_block. The talker is a DSP resource playing the on-hold message.

Figure 6. Setting the Talker to a Connection

2.2.3 Adding Listeners to a Connection

ppxAddListeners adds listeners to a connection. The listeners are specified by an array containing the switch identification number, bus type (CTBUS or LOCAL), stream, and timeslot for each listener.

If the connection already has a talker attached, the listeners are connected to the talker using switch connections. The switch connections may involve the allocation of bus timeslots if the talker and the listener are on different boards. If there is no talker attached to the connection, the listeners have the default pattern of the connection sent to them.

In Figure 7, as incoming calls are received, they are connected to the hold_message_block to receive the on-hold message while waiting for an available operator.

Figure 7. Adding Listeners to a Connection

2.2.4 Removing Listeners from a Connection

ppxRemoveListeners removes listeners from a connection. The listeners are specified by an array containing the switch identification number, bus type (CTBUS or LOCAL), stream, and timeslot for each listener.

If the listeners are connected to a talker, the switch connections are broken. The listeners are put into their default disabled hardware state. For telephony bus output streams, the default hardware state is a high impedance state. Local bus output streams are put into the vendor-specified default state.

As shown in Figure 8, as an operator becomes available, listeners are removed from the hold_message_block so they can be connected to an operator.

Figure 8. Removing Listeners from a Connection

2.2.5 Setting the Silence Pattern for a Connection

ppxSetDefaultPattern sets the default pattern for a connection. If there is no talker attached to a connection, the listeners receive the default pattern. If listeners are connected to a talker and the talker is removed, the listeners receive the default pattern for the connection.

This function overrides the default pattern set when the connection is created by calling ppxCreateConnection. The default silence pattern used by the server is 0x7f (mu-law). This default value may be modified by setting a switch fabric attribute within the PPX configuration file, as described in Chapter 3.

2.2.6 Opening a Connection

ppxOpenConnection returns a handle to a named connection.

Typically, in Natural Access, each application runs as a separate thread or process. If a connection is assigned a name when it is created, each application may open a handle to that connection and add a talker or add/remove listeners. Any action taken in one application is reflected in the connection which will be apparent in every application which accesses that connection.

Note: The Point-to-Point Switching service considers a PPX client to be equivalent to a Natural Access context.

Figure 9. Opening a Connection Handle

In Figure 9, the hold_message_block was created with the name hold_msg. In the system, one application is managing incoming calls and transferring them to operators when they are available. Another application is used to manage the operator stations. If an operator needs to place the caller back on-hold, the application can open the connection named hold_msg. The connection handle hold_message_block is returned and the application can then add the caller as a listener to that connection.

2.2.7 Closing a Connection

ppxCloseConnection closes a previously created connection.

If the connection is unnamed (see Section 2.2.1, Creating a Connection for information about naming connections), the resources associated with the connection are freed and all connection outputs become disabled. A named connection is closed by ppxDestroyNamedConnection.

2.2.8 Destroying a Named Connection

ppxDestroyNamedConnection frees all resources and disables outputs to all points on a named connection. Even if all applications close a named connection (using ppxCloseConnection), the connection remains in the Point-to-Point Switching connection database until it is explicitly destroyed (using ppxDestroyNamedConnection).

Once destroyed, any open handles to the named connection become invalid in all applications.

2.3 Making One-Talker, One-Listener Connections

The Point-to-Point Switching service provides convenience functions, ppxConnect and ppxDisconnect, to make connections between one talker and one listener.

Connections made with ppxConnect use internal connection handles that cannot be accessed by the application. Additional listeners cannot be added to connections made with the convenience functions, nor can these connections be accessed across applications.

When a connection is made using ppxConnect, the connection is owned by the context that created it. The connection can only be disconnected (by calling ppxDisconnect) by the owner context.

These convenience functions include a mode argument, that directs the Point-to-Point Switching service to calculate endpoints for any additional connections based upon the single talker and listener that have been passed. The mode argument can have any of the following values:

Value	Description
PPX_SIMPLEX	Establishes a connection in one direction; this mode is typically used to broadcast or to monitor half a conversation.
PPX_DUPLEX	Establishes connections in two directions; this mode is typically used to connect a phone conversation.
PPX_QUAD	Establishes two duplex connections, one for voice and one for signaling; this mode is typically used to connect a network interface to its voice and signaling DSPs.

2.3.1 Making a Simplex Connection

A simplex connection is made by calling ppxConnect and passing it the addresses of the talker and the listener, and the mode PPX_SIMPLEX. The Point-to-Point Switching service connects the talker to the listener by making the necessary switch connection. The connection may involve the allocation of telephony bus timeslots if the talker and the listener are on different boards.

For example, Figure 10 shows a simplex connection between local resources on a telephony board. The switch connection connects a network interface voice input on local stream 0 to the DSP voice output on local stream 5.

Figure 10. Simplex Connection

2.3.2 Making a Duplex Connection

A duplex connection is made by calling ppxConnect and passing it the addresses of the talker and the listener, and the mode PPX_DUPLEX. For duplex connections, the Point-to-Point Switching service makes two end-to-end connections. The connections will involve the allocation of telephony bus timeslots if the talker and the listener are on different boards.

A duplex connection is a bidirectional voice or a bidirectional signaling connection. Telephony bus streams are typically defined in pairs; an even-numbered stream n has a corresponding stream n+1. The even-numbered stream is in one direction and the odd-numbered stream is in the other direction. For example, if stream 0 is an input stream, stream 1 is an output stream.

For a duplex Point-to-Point Switching connection, the first connection is specified by the talker and listener that are passed as arguments to the function. The second connection is determined by connecting the stream pair.

For example, Figure 11 shows a duplex connection between local resources on a telephony board. ppxConnect is called with the address of the talker (LOCAL:0:3) and the address of the listener (LOCAL:5:3). The first connection makes the connection between the talker and the listener. The Point-to-Point Switching service automatically makes the second connection which is LOCAL:4:3 (stream 4 is the pair of stream 5) to LOCAL:1:3 (stream 1 is the pair of stream 0).

Figure 11. Duplex Connection

The Point-to-Point Switching service uses the following algorithm to determine the streams that are used in a duplex connection. The application specifies one talker and one listener in the command:

  ppxConnect( ctahd, &talker, &listener, PPX_DUPLEX)

The Point-to-Point Switching service makes the following connections:

• The first connection is:

     talker -> listener
  
  

• The second connection depends on whether the specified bus is local. Since inputs from local resources are always on even-numbered streams and outputs to local resources are always on odd-numbered streams, local stream endpoints are always as follows:

      listener_2.stream = talker.stream + 1
      talker_2.stream = listener.stream - 1
  
  

  • Then connect:

        talker_2 -> listener_2
    
    

• When the bus is not local, the second connection is determined as follows:

• If the talker is on an even-numbered stream:

      listener_2.stream = talker.stream + 1
  
  

  otherwise:

      listener_2.stream = talker.stream - 1
  
  

• If the listener is on an even-numbered stream:

      talker_2.stream = listener.stream + 1
  
  

  otherwise:

      talker_2.stream = listener.stream - 1
  
  

• Then connect:

      talker_2 -> listener_2
  
  

2.3.3 Making a Quad Connection

A quad connection is made by calling ppxConnect and passing it the addresses of the talker and the listener, and the mode PPX_QUAD. A quad connection is the same as making two duplex connections. The Point-to-Point Switching service makes four end-to-end connections. The connections may involve the allocation of telephony bus timeslots if the talker and the listener are on different boards.

In a quad connection, the application specifies one connection which connects a talker to a listener.

The Point-to-Point Switching service does the following:

• Makes the duplex connection for the talker and the listener.

• Increments the streams by two, and connects a talker and listener.

• Makes the duplex connection for the new talker and listener.

Figure 12 shows a quad connection between local resources on a telephony board. ppxConnect is called with the address of the talker (LOCAL:0:3) and the address of the listener (LOCAL:5:3). The first connection makes the connection between the talker and the listener. The second connection connects LOCAL:4:3 (stream 4 is the pair of stream 5) to LOCAL:1:3 (stream 1 is the pair of stream 0). The third connection makes the connection between the LOCAL:2:3 (stream 2 is stream 0 + 2) to LOCAL:7:3 (stream 7 is stream 5 + 2). The second connection connects LOCAL:6:3 (stream 6 is the pair of stream 7) to LOCAL:3:3 (stream 3 is the pair of stream 2).

.

Figure 12. Quad Connection

The Point-to-Point Switching service makes the required switch connections by calling ppxConnect with two endpoints.

For example, connecting a network interface to the on-board DSP resources for one port of an AG 2000 consists of one Point-to-Point Switching call. The Point-to-Point Switching service makes four switch connections:

Application

Switch Connections Made by Point-to-Point Switching Service

talker.switch_number =0; talker.bus = MVIP95_LOCAL_BUS; talker.stream = 0; talker.timeslot = 4; listener.switch_number = 0; listener.bus = MVIP95_LOCAL_BUS; listener.stream = 5; listener.timeslot = 4; ppxConnect(ctahd, &talker, &listener, PPX_QUAD)

talker.bus = MVIP95_LOCAL_BUS; talker.stream = 0; talker.timeslot = 4; listener.bus = MVIP95_LOCAL_BUS; listener.stream = 5; listener.timeslot = 4; swiMakeConnection(swihd, talker,listener,1) talker.bus = MVIP95_LOCAL_BUS; talker.stream = 4; talker.timeslot = 4; listener.bus = MVIP95_LOCAL_BUS; listener.stream = 1; listener.timeslot = 4; swiMakeConnection(swihd, talker,listener,1) talker.bus = MVIP95_LOCAL_BUS; talker.stream = 2; talker.timeslot = 4; listener.bus = MVIP95_LOCAL_BUS; listener.stream = 7; listener.timeslot = 4; swiMakeConnection(swihd, talker,listener,1) talker.bus = MVIP95_LOCAL_BUS; talker.stream = 6; talker.timeslot = 4; listener.bus = MVIP95_LOCAL_BUS; listener.stream = 1; listener.timeslot = 4; swiMakeConnection(swihd, talker,listener,1)

Connecting the same port on the AG 2000 to DSP resources on an AG 4000 board consists of only one Point-to-Point Switching call, but requires eight switch connections.

2.3.4 Disconnecting a Talker and a Listener

ppxDisconnect is used to disconnect a previously connected simplex, duplex, or quad switch connection. Any intervening timeslots are freed. ppxDisconnect can only breakdown connections that are owned by the context (the context bound to the connection when it was created with ppxConnect).

2.4 Restoring Initial Connections

Switch connections can be specified in the Point-to-Point Switching configuration file. These connections can be disconnected using ppxDisconnect if the connections were not specified with the NAILED keyword.

See Section 3.7, Specifying Switch Connections for details about connections made in the Point-to-Point Switching configuration file.

ppxRestoreConnections is used to set the Point-to-Point Switching service to restore the Point-to-Point Switching configuration file switch connections when the application exits.

If this function is not called, the switch connections are left in the state as modified by the application.

2.5 Connection Transactions

Use the Point-to-Point Switching service to group switch commands into a single logical transaction. This functionality creates a batch of connections that are related to each other. All operations within the transaction must be completed successfully or the transaction fails.

A group of switch operations starts with a ppxBegin command. Each Point-to-Point Switching function called after ppxBegin returns immediately, and the switch connections are not made until ppxSubmit is called.

ppxSubmit is an asynchronous function, but it returns immediately. The final result of the transaction will be delivered in an event.

When ppxSubmit is called, the Point-to-Point Switching service determines if each operation is valid and that there are valid paths for all connections.

After verifying the commands and paths, the Point-to-Point Switching service calls the functions to perform the operations. If an error occurs when making the connections, any pending operations are aborted. The Point-to-Point Switching service restores any of the connections made up to that point and the system is returned to its state before ppxBegin was called.

When all connections have been made, the event PPXEVN_SUBMIT_COMPLETE is returned.

All Point-to-Point Switching functions except ppxOpenConnection and ppxCreateConnection functions can be included in a ppxBegin/ppxSubmit block. Only one ppxBegin/ppxSubmit block can be active on a given context.

2.5.1 Cancelling a Begin/Submit Transaction

ppxBeginCancel cancels a group of commands preceded by a ppxBegin statement.

2.6 Terminating a Point-to-Point Switching Client

The IPC mechanism, which the Point-to-Point Switching service uses to communicate between the Point-to-Point Switching client and the Point-to-Point Switching server, notifies the Point-to-Point Switching server when a client is no longer running. When a client stops running, all connections that the client established during its lifetime are disconnected and all associated resources are freed. A Point-to-Point Switching client does not need to perform explicit disconnections when it exits unless it is bound to a named connection.

Named connections are not automatically disconnected. If a named connection was established or opened by the exiting client, the named connection remains unchanged at the client's exit; nothing is disconnected and no resources are freed. This connection persists until explicitly destroyed at a later time by a different Point-to-Point Switching client with ppxDestroyNamedConnection.

2.7 Error Processing

If the PPX server encounters an error while processing a Point-to-Point Switching function call for a client, the Point-to-Point Switching connection database returns to its initial state at the time the function was initiated. The Point-to-Point Switching connection database returns to its initial state when either Point-to-Point Switching errors or Switching service errors occur during function processing (some Point-to-Point Switching functions call Switching service functions as part of normal execution).

For example, if a new talker is set for a connection, the previous talker is disconnected from the listeners on the connection, and the new talker is connected to these listeners. If the connection fails while the new talker is being connected to any one of the listening points, the previous talker is reestablished on the connection. Any new connections established up to the point of the failure will be broken, and any previously existing connections (to the previous talker) will be restored.

2.8 PPX Hot Swap Support

PPX can establish a set of connections based upon the presence of a connect definition within its configuration file. Because of these connections, it is necessary that PPX is Hot Swap-aware. PPX must release resources for those initial connections that are using a switch associated with a Hot Swap service HSIEVN_REMOVAL_REQUESTED event. See the NMS OAM System User's Manual for more information.

The PPX server has a thread for receiving Hot Swap events. Upon receiving a removal event for a board that is used in one of these initial connections, PPX tears down the connection that is using the switch and marks the switch disabled within the fabric.

If the input on the connection (listener) is on an enabled switch, the default idle pattern is sent to the listening point. This same action is taken when a NULL talker is assigned to a connection object to which listeners have already been assigned.

When an HSIEVN_BOARD_READY event is received, PPX determines whether the board's switch was being used by one of the initial connections. If it was, the connection will be re-established. PPX will also set the state of the switch to ENABLED.

2.8.1 Configuration for Unpopulated CompactPCI Slots

In the configuration file, users define boards for unpopulated CompactPCI slots. Similarly, the following PPX configuration is needed within the switch definition of boards that are planned to be inserted into currently unpopulated CompactPCI slots:

   SwitchState [ENABLED | DISABLED]

When the field is set to DISABLED, the switch is added to the switching fabric but its state is set to DISABLED. Clients will receive an error if they attempt to use the switch. If this field is missing from the definition of the switch, its value is assumed ENABLED.

2.8.2 Client Connections

Client applications are responsible for terminating connections that are effected by an HSIEVN_REMOVAL_REQUESTED event. PPX will not close the switch handle until all clients have disconnected from the switch. Until the switch is closed, clients may continue to make connections using the switch.

2.8.3 Switch Disabled Error

After a disabled switch is closed, users cannot make connections that reference that switch. The PPX error value, PPXERR_DISABLED, is returned from the following API functions when a disabled switch is specified:

• ppxAddListeners

• ppxConnect

• ppxSetTalker

For more information on errors and events, see Appendix A.

2.8.4 Switching Service Log Support

If PPX's SWI command logging is configured, switch enable and disable information will appear in the log file.

The following example shows the subsequent SWI log information that appears if each of the two boards (shown in the ppx.cfg excerpt) are removed and then reinserted.

ppx.cfg

[ppx]
Fabric
        
       # 
       Switch 1
            SwitchType = HMIC
            DeviceName = "agsw"
            DeviceNumber = 1

       #  etc...
       Switch 4
            SwitchType = HMIC
            DeviceName = "agsw"
            DeviceNumber = 4
       #  etc  
       
       # Initial Connections established by ppx server
       Connect
            1:local:0:0 to 1:local:17:0 QUAD
            4:local:0:2 to 4:local:17:2 QUAD 
       End Connect
End Fabric
ppxswi.log
Setup of initial connections.

[Tue Jan 12 15:29:11 1999] Switch 1: Handle Opened 0x1
[Tue Jan 12 15:29:11 1999]   swiMakeConnect: hd 0x1 LOCAL:0:0 TO LOCAL:17:0
[Tue Jan 12 15:29:11 1999]   swiMakeConnect: hd 0x1 LOCAL:16:0 TO LOCAL:1:0
[Tue Jan 12 15:29:11 1999]   swiMakeConnect: hd 0x1 LOCAL:2:0 TO LOCAL:19:0
[Tue Jan 12 15:29:11 1999]   swiMakeConnect: hd 0x1 LOCAL:18:0 TO LOCAL:3:0
[Tue Jan 12 15:29:12 1999] Switch 4: Handle Opened 0x10002
[Tue Jan 12 15:29:12 1999]   swiMakeConnect: hd 0x10002 LOCAL:0:2 TO
                             LOCAL:17:2
[Tue Jan 12 15:29:12 1999]   swiMakeConnect: hd 0x10002 LOCAL:16:2 TO 
                             LOCAL:1:2
[Tue Jan 12 15:29:12 1999]   swiMakeConnect: hd 0x10002 LOCAL:2:2 TO 
                             LOCAL:19:2
[Tue Jan 12 15:29:12 1999]   swiMakeConnect: hd 0x10002 LOCAL:18:2 TO 
                             LOCAL:3:2

Board removal 

[Tue Jan 12 15:30:39 1999] Switch 4 Device 4 DISABLED
[Tue Jan 12 15:30:39 1999] Switch 4 Handle 0x10002 Closed
[Tue Jan 12 15:30:43 1999] Switch 1 Device 1 DISABLED
[Tue Jan 12 15:30:43 1999] Switch 1 Handle 0x1 Closed

Reinsert with auto reconnect

reinsert:
[Tue Jan 12 15:30:52 1999] Switch 1 Device 1 ENABLED
[Tue Jan 12 15:30:52 1999] Switch 1: Handle Opened 0x20001

reconnect:
[Tue Jan 12 15:30:52 1999]   swiMakeConnect: hd 0x20001 LOCAL:0:0 TO 
                             LOCAL:17:0
[Tue Jan 12 15:30:52 1999]   swiMakeConnect: hd 0x20001 LOCAL:16:0 TO 
                             LOCAL:1:0
[Tue Jan 12 15:30:52 1999]   swiMakeConnect: hd 0x20001 LOCAL:2:0 TO 
                             LOCAL:19:0
[Tue Jan 12 15:30:52 1999]   swiMakeConnect: hd 0x20001 LOCAL:18:0 TO 
                             LOCAL:3:0

reinsert:
[Tue Jan 12 15:30:57 1999] Switch 4 Device 4 ENABLED
[Tue Jan 12 15:30:57 1999] Switch 4: Handle Opened 0x30002

reconnect:
[Tue Jan 12 15:30:57 1999]   swiMakeConnect: hd 0x30002 LOCAL:0:2 TO 
                             LOCAL:17:2
[Tue Jan 12 15:30:57 1999]   swiMakeConnect: hd 0x30002 LOCAL:16:2 TO 
                             LOCAL:1:2
[Tue Jan 12 15:30:57 1999]   swiMakeConnect: hd 0x30002 LOCAL:2:2 TO 
                             LOCAL:19:2
[Tue Jan 12 15:30:57 1999]   swiMakeConnect: hd 0x30002 LOCAL:18:2 TO 
                             LOCAL:3:2