7    Connections

This chapter describes the following connection tasks and the procedures for accomplishing these tasks:

• Making outgoing connections

• Accepting connections

• Controlling the aging of connections

• Releasing connections

• Creating permanent virtual circuits

• Creating signaling virtual circuits

These procedures illustrate the use of the ATM interfaces described in previous chapters.

7.1    Making Outgoing Connections

Making outgoing connections consists of the following tasks:

• Making the call (for both point-to-point and point-to-multipoint connections)

• Adding parties to an existing connection (point-to-multipoint connections only)

7.1.1    Making the Call

Making the call for point-to-point and point-to-multipoint connections is identical except for one argument. When writing convergence modules, make sure the module performs the following tasks when making a call:

1. Chooses a bind point for the outgoing call.

2. Calls the atm_cmm_alloc_addr function to allocate an atm_addr structure that identifies the called party.

3. Sets all the address information associated with the called endpoint in the atm_addr structure

4. Calls atm_cmm_alloc_ie to allocate the atm_uni_call_ie structure that the module uses to make the call. If you use another signaling protocol, allocate the structure needed by that protocol instead.

5. Sets all the needed information in the atm_uni_call_ie structure or other signaling protocol call parameters structure.

6. Allocates an atm_vc_services_t structure by calling atm_cmm_alloc_services.

7. Sets all the structure members in the atm_vc_services_t structure. For Constant Bit Rate (CBR) circuits, set the ATM_SERVICES_CBR flag. For pacing circuits, set the ATM_SERVICES_PACING flag. For both CBR and pacing circuits, you must set the peak bit rates.

8. If you want to reserve resources for CBR or pacing circuits, call the atm_cmm_reserve_resources routine, passing it a pointer to the atm_vc_services_t structure.

   Note

   You can apply reserved resources to point-to-point connections only.

9. If the reserve resources call returns ATM_CAUSE_DEFER, the atm_vc_services structure is considered a reserved resource reservation. The convergence module must wait for an ATM_CME_RESV_AVAIL exception notification before proceeding; this exception indicates the atm_vc_services structure is backed by resources. If the convergence module does not wait for the reservation to become available, it terminates the resource reservation request (and frees the atm_vc_services_t memory) by calling atm_cmm_free_services.

   If the reserve resources call returns ATM_CAUSE_GOOD, the atm_vc_services_t structure is considered to be backed by resources, which can be applied to a call.

   If the reserve resources call returns any other error code, the convergence module should examine the lerrstat structure member of the atm_vc_services_t structure for additional error information. If the convergence module does not continue, it must free the memory allocated in the previous steps.

10. Calls atm_cmm_connect with the appropriate arguments. For point-to-point connections, uses the ATM_CT_PTP argument. For point-to-multipoint connections, uses the ATM_CT_PTM argument.

    Note

    If the module has reserved resources and they are not applied in time, they are revoked by an ATM_CME_RESV_EXPIRE exception notification.

11. If the connect call returns an error code, the convergence module frees the memory allocated in the previous steps. An error might be caused by the Connection Management Module (CMM) or other modules being unable to initiate a call request.

    For CBR and pacing connections that do not use resource reservation, there might be a failure to allocate the necessary resources. If the failure is due to an incorrectly set atm_vc_services_t structure, the lerrstat structure member contains local error information.

12. If the connect call returns ATM_CAUSE_GOOD, the call is proceeding and the convergence module can make a reference to the new atm_vc structure for the connection. From this point, all events on the VC come through the exception interface.

Section B.1 contains a sample routine that shows how to make a call for point-to-point connections and how to make the first call for point-to-multipoint connections.

Once the connect call returns, all subsequent activity on the VC is reported through the exception interface (xxx_except).

After the call is initiated, the convergence module can receive the following notifications:

ATM_CME_CALL_FAILED

An error occurred in processing the call or the called party rejected the call.

The convergence module should extract the cause information from the endpoint's atm_addr structure and decide how to handle the error based on this information. The module should then delete all references to the atm_addr structure and the VC, but should not deallocate the structure memory. The CMM does this after removing all its references to the call. Once the convergence module returns from the exception notification routine, it can no longer access any nonprivate structures associated with the call.

ATM_CME_EP_ACTIVE.

The call is successful; the circuit to the endpoint is complete and it could receive incoming data at any time (incoming data could arrive ahead of the connection activation notification because of race conditions). The convergence module should not send any data until it receives the connection activation notification.

When a connection is activated, the convergence module may check the atm_vc_services structure referenced in the atm_vc structure to determine if any of its connection service parameters were changed by the called party through negotiation.

7.1.2    Adding Parties to an Existing Connection

For point-to-multipoint connections, after the call to the first party is successful, you can add parties to the VC associated with the first call and drop parties at any time. Note that since call placement is multithreaded, you can initiate calls to multiple endpoints sequentially. Convergence modules receive individual notifications for each endpoint that is connected. Thus, multiple connections can be in progress at any given time without the convergence module needing to handle synchronization issues.

The convergence module can receive exception notifications for exceptions affecting all parties on the VC or for single endpoints (an exception with a single party in the multipoint call). When writing a convergence module, you must ensure that the module can handle these exceptions properly so that it does not associate an endpoint exception affecting a specific party with all parties on a VC.

Section B.2 contains a code fragment that shows one method of adding parties to a point-to-multipoint connection.

7.2    Accepting Connections

When a remote host places a call to the local host, the following events occur on the local host:

1. The signaling protocol module on the local host receives a call request (a UNI 3.0 SETUP message or its equivalent).

2. The signaling protocol module uses the information in the signaling protocol message to construct an atm_addr structure and an atm_vc_services structure. These structures contain information about the calling endpoint and the services requested by the endpoint, respectively.

3. The signaling module uses the atm_cmm_new_call function call to pass the structures, the handle of the device driver on which the new VC will be attached, and a unique call reference value to the CMM.

4. The CMM examines the atm_vc_services structure parameters to determine if the available system resources can meet the level of service requested by the calling party. If so, the resources are reserved. If not, only available resources are reserved. The CMM calls the convergence module (using the xxx_connect routine) that has bound to the called party's network services access point (NSAP).

5. When called, the convergence module should inspect the ATM address information and the signaling protocol information (referenced by the setup member of the atm_addr structure) to determine if the call is for the convergence module's protocol. If the call does not belong to the convergence module, it should return an error indication to the CMM. If the call belongs to the convergence module, it continues with step 6.

6. The convergence module should check the service parameters arguments to determine if the service parameters are acceptable. If the service parameters are insufficient for the type of service the module is providing, it can reject the call with the appropriate cause. The convergence module cannot modify the service parameters.

   If the CMM has allocated the resources needed to meet the requested level of service, the convergence module should return ATM_CAUSE_GOOD to the CMM to accept the call. If the CMM indicates that it cannot allocate the bandwidth and the convergence module does not apply a reserved resource to the incoming call, the convergence module should return an error indication to the CMM to reject the call.

   If the convergence module supplies a reserved resource that cannot be applied to the call, the new VC is torn down, the supplied atm_vc_services structure and its underlying resources freed, and the convergence module sent an ATM_CME_EP_DEAD exception notification. The VC's cause log contains the reason why the connection was torn down.

   Section B.3 contains a sample code fragment that shows how a convergence module processes an incoming call.

7. If a convergence module accepts a call, the following should occur:

   • The convergence module should use the convergence module private fields in the atm_addr and atm_vc structures to create its internal references to the new VC and endpoint.

   • Once the connection notification call (xxx_connect) returns with ATM_CAUSE_GOOD, the convergence module owns the call and owns and controls the VC. From this point, all notifications associated with the VC go to the accepting convergence module.

   • The convergence module should consider the VC valid but not active. However, data can start arriving at any time since the path the activation notification takes could be longer than the data path.

   • The convergence module should not attempt to transmit data until it receives a notification that the VC is active.

   • The CMM returns ATM_CAUSE_GOOD to the signaling module, indicating that the signaling module should reply to the calling party in whatever way is appropriate to accept the call.

   • The signaling module must not deallocate any memory used for structures passed to the CMM.

8. If the call is not accepted, the signaling module replies to the caller in an appropriate way to reject the call. In this case, the signaling module must deallocate all memory use for structures passed to the CMM.

7.3    Controlling the Aging of Connections

This section applies to switched virtual circuits (SVCs) only; permanent virtual circuits (PVCs) do not age. The Digital UNIX ATM subsystem provides for automatic detection and elimination of unused VCs when available resources are low. This prevents a hung protocol from continuing to hold resources and ensures that system resources are allocated fairly.

When a circuit is created, convergence modules specify an initial aging algorithm in an argument to the atm_cmm_connect routine. The CMM then performs all connection aging based on usage statistics it collects during the lifetime of a connection. If necessary, convergence modules can use the atm_cmm_vc_control routine to change the aging algorithm applied by the CMM at any time. When a connection has aged, the CMM uses the convergence module's xxx_except routine to notify the convergence module that a connection has aged and is about to be removed from the system. This gives the convergence module a chance to prevent the connection's removal.

If the convergence module does not prevent the connection's removal, the CMM uses the normal connection release mechanism to remove the connection; the signaling module sees the release request as coming from the convergence module and the convergence module sees the request as coming from the remote endpoint. See Section 7.4 for information on releasing a connection.

Table 7-1 contains values you can use for the aging parameters in the atm_cmm_connect and atm_cmm_vc_control routines.

Table 7-1: Aging Parameter Values

These circuit-aging algorithms provide sufficient flexibility so that individual convergence modules should not have to perform their own circuit aging. Also, centralizing circuit aging in the CMM allows aging algorithms to take affect only when the CMM detects that an interface is low on free VCs.

7.4    Releasing a Connection

Either convergence modules or the network or an endpoint can release connections. The following sections describe what happens in either case.

7.4.1    Release by a Convergence Module

When a convergence module no longer requires a connection to an endpoint, it should release the connection to free system resources. To release a connection, a convergence module calls either the atm_cmm_release or atm_cmm_drop function. The former releases a VC and all associated endpoints; the latter disconnects only a single endpoint, releasing the VC only if all endpoints have been dropped.

When a convergence module calls atm_cmm_release, the CMM initiates a disconnect of all endpoints associated with the VC.

For point-to-point VCs, this initiates a release operation on the VC. The convergence module receives an ATM_CME_EP_DEAD notification. This informs the convergence module that the release operation is in progress on the network and that no more data will be sent on the VC.

For multipoint VCs, this initiates the dropping of all endpoints and the release of the VC. As each endpoint is dropped, the convergence module receives an ATM_CME_EP_DEAD notification. The convergence module must delete all its references to the endpoint. Once all endpoints associated with a VC have been dropped, the VC is released. The CMM handles conditions where endpoints are in various stages of set or release when it receives this request.

When the ATM_CME_EP_DEAD notification is received for the last endpoint on the VC, convergence modules should delete all references to the VC. To accomplish this, Digital recommends that the module maintain a use count for any VC references it maintains.

When a VC is released, the CMM notifies the device driver to which the VC is attached so that the device driver can free any resources it has allocated to the VC.

7.4.2    Release by Network or Endpoint

When the network or an endpoint initiates a connection release, the signaling protocol module receives either a release or a drop message. At that point, the signaling module calls either the atm_cmm_con_release or atm_cmm_ep_dropped function.

When a signaling module calls the atm_cmm_con_release function, the CMM does the following:

1. Initiates connection releases to all endpoints associated with the VC, if the VC being released is a multipoint VC.

2. Calls the device driver to which the VC is attached and passes an ATM_DRVMGMT_DELVC notification. The driver should delete all its references to the VC and release all resources associated with the VC.

3. Calls the convergence module that owns the VC and passes an ATM_CME_EP_DEAD notification for each endpoint associated with the VC.

4. Frees all structures associated with the VC and returns to the signaling module.

When the signaling module calls the atm_cmm_ep_dropped function, the CMM calls the convergence module that owns the endpoint's VC and passes an ATM_CME_EP_DEAD notification. If this is the last endpoint associated with the VC, it initiates a release of the VC.

7.5    Creating Permanent Virtual Circuits

Although the ATM subsystem is designed primarily to use SVCs, you can also use PVCs. Before you create PVCs locally, the PVCs must already be set up on the network. You can use either of the following methods for setting up PVCs:

• The atmconfig program (see atmconfig(8) for more information)

• Allow convergence modules to directly create PVCs just as they create SVCs

Either method creates a local reference to the PVC and allocates the resources necessary for the VC to function on the system. In either case, the convergence module's connection routine for the bind point to which the PVC is attached is called.

Note

You can create PVCs only on the PVC PPA. You cannot create a PVC on an SVC PPA.

When a convergence module sets up a PVC, the following events occur:

• A local reference to the VC is set up in the CMM.

• The ownership of the PVC is given to the convergence module.

• The VC is created and enabled in the device driver.

Once set up, the PVC remains in existence until explicitly torn down by the convergence module.

The ATM subsystem treats a PVC like an SVC, except that there is no signaling protocol associated with the PVC, and PVCs do not age. When a convergence module requests a PVC, it must specify all the VC service parameters as it does for an SVC. If the PVC is created successfully, this does not necessarily mean that the PVC exists. Even though a local reference for the PVC has been created, modules cannot check (due to the nature of PVCs) to determine if the PVC exists on the network.

Note

If you create a PVC before it is configured on the network, no invalid VCI errors are reported to the convergence module.

To release PVCs, use the atm_cmm_release function call. However, since PVCs require no signaling protocol exchange with the network, PVC release is synchronous. The return value from the release function call indicates success or failure of the teardown. The convergence module receives no other notifications.

7.6    Creating Signaling Virtual Circuits

Signaling VCs are well-known PVCs that signaling protocols use to communicate with the switches on the network. The switches and the end systems on an ATM network automatically set up signaling VCs. The ATM subsystem treats signaling VCs as ordinary PVCs and does not provide any special mechanisms for them. The signaling protocol module is responsible for managing the signaling VCs.

When signaling modules initialize, they register with the CMM as both a signaling module and as a convergence module. The signaling modules use the signaling module interface to field connection management requests from the CMM; they use the convergence module interface to send and receive signaling protocol packets on the network. Once registered as a convergence module, signaling modules must create all VCs required by their signaling protocol.

Once the signaling VCs are created, the CMM treats them like any other PVC. Like other convergence modules, the signaling module receives no notification whether a PVC exists on the network. Signaling modules receive notification of interfaces being brought up and interfaces going down. When an interface goes down, all signaling VCs on that interface are destroyed.