5 Convergence Module Interface

The ATM convergence module interface enables all kernel-level protocol convergence modules (convergence modules, for short) to interface kernel networking protocol stacks to the ATM subsystem. The ATM convergence module interface is a registration-based interface that provides a set of ATM primitives that convergence modules can use to manage virtual circuits (VCs) and transfer data.

The ATM convergence module interface enables convergence modules to:

Register and unregister the convergence module

Receive connection, data, and exception notification from the CMM

Connect to the ATM Module Management Interface (MMI)

Request interface parameters, endpoint connection state information, and VC statistics

Add an endpoint to and drop an endpoint from a connection

Transmit data on an established VC

Modify VC parameters

Request a connection to a remote system and a connection teardown

Bind to and unbind from a PPA

Accept and reject an incoming call

Add and delete ATM addresses

This chapter describes each task, the function calls involved, and the relevant data structures that convergence module writers can use. Appendix A contains a reference page for each convergence module interface routine.

5.1 Registering a Convergence Module

Before a protocol convergence module can interact with the ATM subsystem, it must use the atm_cmm_register_cvg function call to register itself with the Connection Management Module (CMM). The CMM then passes interface configuration information (for example, currently configured PPAs) to the convergence module, using the module's xxx_except routine, before the registration call returns.

Once a convergence module is registered, the CMM knows where to deliver connection notifications and various exception notifications (for example, changes in system configuration). Convergence modules can register at any time.

5.2 Receiving Data

When the CMM receives data on a VC that the convergence module owns, the CMM calls the xxx_receive routine to pass incoming data to the convergence module. This routine is declared within the convergence module.

If the convergence module uses point-to-multipoint VCs, the module can declare either a xxx_receive or xxx_endpt_receive routine. If a xxx_receive routine is declared, the CMM calls it once for each unit of data received on the VC. The convergence module must duplicate the data, if needed, for each endpoint. If a xxx_endpt_receive routine is declared, for each unit of data received the CMM calls it once for each endpoint. An atm_addr_t parameter to the routine identifies the endpoint. The CMM provides a duplicate mbuf chain for each endpoint; the data might or might not be physically duplicated.

When designing receive functions, you should remember that all data is delivered to the convergence module in an interrupt context with the processor running at the splimp level. The convergence module must implement a queuing policy appropriate for the convergence module's protocol. In general, convergence modules for protocols that can tolerate unspecified latency should queue the incoming data and return immediately to the CMM. Convergence modules for protocols that require bounded latencies (such as video or voice protocols) might want to perform some processing before queuing the data and returning to the CMM. In either case, the receive function must not block.

5.2.1 Receiving Exception Notifications

When an exception condition occurs on a VC, the CMM notifies the convergence module through its exception interface, xxx_except. This function is declared within the convergence module and is used to report exceptions, errors, and system configuration changes to the convergence modules.

Exception notifications have the following characteristics:

Convergence modules can expect them at any time.

They are delivered in an interrupt context.

Exception processing must not block. If a convergence module needs to defer processing an exception notification, it must arrange for a kernel thread to be run at a later time and return immediately to the CMM.

5.2.2 Connecting to the ATM Module Management Interface

When the CMM connects a convergence module to the ATM Module Management Interface (MMI), the CMM uses the xxx_mmi interface. This function is declared within the convergence module. System management programs use the CMM's management interface to pass management and configuration requests directly to convergence modules, without requiring a new /dev entry or other kernel modifications normally associated with creating new management and configuration interfaces. If a module does not require any external management or configuration capabilities, it does not have to register a management function with the CMM.

The MMI follows the standard ioctl call with the following exceptions:

The device major and minor number argument is replaced by the handle argument.

No user credential information is passed. Only users with root access can use the management interface.

5.3 Unregistering a Convergence Module

If a convergence module is finished receiving or making connections, it can use the atm_cmm_unregister_cvg function call to unregister itself from the CMM. This might be necessary in environments where protocol stacks are dynamically configured and deconfigured from the system.

Before unregistering, a convergence module must close all existing connections and unbind from all PPAs. If all connections are not closed or if PPA bindings still exist, the CMM unregisters only the convergence module's xxx_connect routine. The CMM will continue to call the convergence module with incoming data and exception notifications. Once the convergence module is unregistered, the CMM will not call any of its routines.

5.4 Requesting Interface Parameters

When a convergence module must access current information about an interface's physical capabilities (such as its bit rates) and the amount of specific resources left available on an interface (the remaining nonreserved sustainable bit rate), it uses the atm_cmm_ppa_info and atm_cmm_bind_info function calls to query the CMM. The CMM and device drivers keep track of this information.

Since convergence modules normally deal with either PPAs or AESA bindings, the CMM allows convergence modules to query the information from the underlying interface by specifying either the PPA or bind directly. Thus, the convergence module requires no specific knowledge of any device driver or device driver-related structures.

5.5 Reserving Resources for CBR Circuits

If a convergence module needs to reserve resources (such as bandwidth) either prior to making an outgoing connection for a constant bit rate (CBR) circuit or prior to receiving a CBR connection, it uses the atm_cmm_reserve_resources function call to notify the CMM. The convergence module must apply these reserved resources within the system-specified amount of time either to an outgoing CBR connection by using the atm_cmm_connect function call or to an incoming CBR call by using the atm_cmm_accept function call.

Note

Reserved resources can be applied to point-to-point connections only.

If the resources are not applied in time, the CMM revokes the reservation and sends an ATM_CME_RESV_EXPIRE exception notification to the convergence module. The convergence module should remove knowledge of the reserved resources atm_vc_services structure that is being revoked, but should not free the atm_vc_services structure; the CMM frees the structure and releases the underlying resources upon return from the exception notification. In addition, the convergence module cannot apply the resources to a connection as part of handling the exception notification.

Once a reserved resource is successfully applied to a connection, the CMM transparently frees the underlying resources when the connection is torn down. No special action by the convergence module is required.

5.6 Releasing Reserved Resources

When a convergence module no longer needs to apply reserved resources to a VC and wants to release resources that it previously reserved, it uses the atm_cmm_free_services function call with a pointer to the atm_vc_services structure. This frees the atm_vc_services memory and releases its underlying resources.

5.7 Requesting a Connection to a Remote System

When a convergence module needs a connection to a remote system, it uses the atm_cmm_connect function call to make a connection request to the CMM. This initiates the exchanges between the network and the remote host to create a new connection. The convergence module must specify all connection parameters to the CMM; these parameters are required to create the new connection.

By requesting a connection to a remote host, the convergence module owns the VC; the VC's ownership cannot be changed. The convergence module is notified of all incoming data and exceptions on the VC. Also, the convergence module is the only module that can transmit data on the VC.

5.8 Adding an Endpoint to a Connection

When a convergence module must create a point-to-multipoint connection, it first uses the atm_cmm_connect function call to establish a call to the first party of the multipoint connection. This creates a VC and establishes the connection to the first endpoint. Then you can use the atm_cmm_add function call at any time to add new endpoints to the connection. You can add endpoints only to connections that were created with the ATM_CT_PTM flag set.

See Chapter 6 for more information on connections.

5.9 Requesting a Connection Be Torn Down

When a convergence module no longer requires a connection to a remote host, it uses the atm_cmm_release function call to request that the CMM tear down the connection. This initiates the release negotiation with the remote host, and will eventually lead to the connection being torn down and all resources released.

A convergence module can either request that a specific endpoint be disconnected (referenced by an atm_addr structure) or that a VC be disconnected. These operations are equivalent on point-to-point connections; disconnecting only the endpoint results in the VC being torn down. If a convergence module requests that a point-to-multipoint VC be disconnected, the CMM first disconnects all endpoints associated with the VC. This function simplifies the task of disconnecting multipoint VCs and permanent virtual circuits (PVCs).

5.10 Dropping an Endpoint from a Connection

When a convergence module must drop a connection to an endpoint, the module calls the atm_cmm_drop function. The endpoint can be associated with either a point-to-point connection or a point-to-multipoint connection. When the last endpoint associated with a VC is dropped, the VC is torn down. You use this function to manage multipoint VCs, but you can also use it to initiate the teardown of point-to-point VCs.

5.11 Transmitting Data on an Established VC

When a convergence module must transmit data on an established VC, the module calls the atm_cmm_send function call. The CMM then passes the data to the appropriate device driver. Although the CMM does not queue outgoing data, the device driver might. Therefore, the successful return from this function call does not imply that the data was actually transmitted. In fact, the data could be discarded in the driver or on the network. The convergence module is not notified if the data is dropped locally.

5.12 Modifying VC Parameters

After VCs are created, convergence modules can use the atm_cmm_vc_control function call to modify some VC parameters to make the transfer of data more efficient or to control VC aging. You cannot modify the quality of service (QOS) and circuit bandwidth parameters.

5.13 Requesting Endpoint Connection State Information

When a convergence module needs the connection state information for an endpoint updated, the module calls the atm_cmm_enquery function call. This initiates a connection enquiry to the endpoint that results in the ATM address structure for the endpoint being updated with the latest status information. This function may be called any time a connection is active.

5.14 Binding to a PPA

When a convergence module must make outgoing calls or receive incoming calls being made to one of the configured local ATM addresses, the module calls the atm_cmm_ppa_bind function. This call informs the CMM that it will function as a network services user for a specific address and selector value.

Convergence modules are notified when a PPA is configured on the system (when an address is registered with a switch and is made known to the ATM network). Convergence modules can then bind to the PPA to create a network service user endpoint, which uniquely identifies the convergence module on the network. Once bound, there is a unique ATM End System Address (AESA) associated with the bound convergence module. The AESA and the bind point identify the service on the network and local system. Convergence modules will be informed only of incoming calls on PPAs to which they have bound and can place calls only through a bind point. The CMM handles calls only to AESAs. If the AESA specified by the called party address of an incoming call does not exist, the CMM rejects the call. See Section 2.5 for more information on PPAs and AESAs.

By binding to a PPA, a convergence module is creating an AESA and uniquely identifying its service on the network. Once this is done, incoming calls can be routed to the convergence module, and the convergence module can make outgoing calls. All call activity is directed at a bind point and thus to a specific convergence module.

When binding to a PPA, a convergence module can either specify a selector value to use in creating the AESA address, or it may allow the CMM to assign it a selector value. In both cases, the selector value must specify a unique endpoint on the PPA.

Note that a convergence module can bind up to 256 times to a PPA (as long as all its selector values are unique), and may bind to as many PPAs as is necessary to provide its service.

5.15 Receiving a Connection Notification

When a connection request arrives on the system, a signaling protocol module notifies the CMM. The CMM uses the xxx_connect interface to call the convergence module that is bound to the selector specified in the called party address. Only one convergence module can accept a connection. The called convergence module then examines all the connection data (the information in the atm_addr structure as well as any information elements (IEs) or other signaling information passed in) to determine if it is willing to accept the call.

If the convergence module accepts the call, the CMM and signaling module proceed with call setup. The VC is not active at this point. The connection and VC is owned by the accepting convergence module until the connection is destroyed; you cannot change the VC's ownership. The convergence module VC is notified of all incoming data and exceptions on the VC. Also, the convergence module is the only module that can transmit data on the VC.

Connections are not shared between convergence modules at the bind point. If convergence modules must share connections, one module must own the connection and coordinate access to the connection with another module. Alternatively, you can layer modules on top of a multiplexor that assumes ownership of the connection.

If the convergence module rejects the call, the CMM and signaling module release the VC and notify the calling party that the call was rejected. The CMM never accepts a call without the explicit consent of a convergence module.

5.16 Unbinding from a PPA

If a convergence module must not accept an incoming connection (while awaiting a call from a specific caller) or make outgoing calls, it uses the atm_cmm_ppa_unbind function call to unbind its service from the PPA. Typically, convergence modules should unbind a PPA if their service is no longer available, and must unbind before unregistering with the CMM.

5.17 Accepting an Incoming Call

When a convergence module defers action on an incoming call (by returning ATM_CAUSE_DEFER from its xxx_connect routine), the module notifies the CMM as soon as it determines the disposition of the call. Typically, this is done within a set period of time, as defined by the signaling protocol, before the calling party times out on the call request.

If the convergence module determines that the call should be accepted, the module uses the atm_cmm_accept function call to inform the CMM that the call should be accepted and set the circuit resource parameters.

5.18 Rejecting an Incoming Call

When a convergence module defers action on an incoming call (by returning ATM_CAUSE_DEFER from its xxx_connect routine), the module notifies the CMM as soon as it determines the disposition of the call. Typically, this is done within a set period of time, as defined by the signaling protocol, before the calling party times out on the call request.

If the convergence module determines that the call should be rejected, the module uses the atm_cmm_reject function call to inform the CMM.

5.19 Adding a New ATM Address

When a convergence module must register a new address with the network, the module uses the atm_cmm_new_esi function call to supply the ESI (or other signaling protocol equivalent) portion of the address and a driver reference to the CMM. The CMM then performs all the necessary functions needed to register the address with the network and to activate it.

When a convergence module supplies a new ESI, the signaling modules apply the ESI in a signaling protocol-specific way. Depending on the signaling protocol, the addition of a single ESI to the system could create many PPAs. All convergence modules are notified of every new PPA that is created as the result of configuring a new ESI.

Once a convergence module creates an address, only the creating convergence module, the CMM (through the system atmconfig program), or the network can delete the address. Other convergence modules cannot delete the address. The creating convergence module must issue the atm_cmm_ppa_bind call once it receives notification that the PPA(s) have been configured. If the convergence module unregisters with the CMM, all its created addresses are destroyed.

5.20 Deleting an ATM Address

When a convergence module is finished using a new address it has created, it can use the atm_cmm_del_esi function call to delete it. Deleting a PPA causes all VCs associated with that PPA to be closed by the CMM (both ends of the connection receive proper notification). Thus, convergence modules should delete addresses only when there are no active VCs associated with the address' PPAs.

5.21 Requesting VC Statistics

When a convergence module must retrieve current VC information from the CMM, it calls the atm_cmm_vc_stats function. The CMM returns the information in the atm_vc_stats structure.

The CMM keeps track of VC usage on a per-VC basis. This is done as part of the CMM's VC management and cannot be disabled.

5.22 Using ATM Convergence Module Interface Structures

The ATM device driver interface uses the following structures exclusively:

atm_vc_stats -- The virtual circuit statistics structure

atm_cmi_addr -- The called party address union

atm_cvg_params -- The convergence parameters structure

5.22.1 The atm_vc_stats Structure

The atm_vc_stats structure contains information on successful return from the atm_cmm_vc_stats function. Table 5-1 lists those members of the atm_vc_stats structure, with their associated data types, that convergence modules might reference.

Table 5-1: The atm_vc_stats Structure Members

Member Name	Data Type
`bytes_in`	`unsigned long`
`bytes_out`	`unsigned long`
`packets_in`	`unsigned int`
`packets_out`	`unsigned int`
`opened`	`struct timeval`
`last_out`	`struct timeval`
`last_in`	`struct timeval`

The bytes_in member contains a count of the number of bytes received on the VC. This includes any ATM Adaptation Layer (AAL) protocol headers/trailers passed back by the driver.

The bytes_out member contains a count of the number of bytes transmitted on the VC. This does not include the AAL header/trailer bytes unless these are supplied by the convergence module.

The packets_in and packets_out members contain counts of the number of packets (or cells for raw cell VCs) received and sent, respectively.

The opened member contains the time-stamp of the time the VC was established. If you subtract this from the current time, the result is the time the VC has been in service.

The last_out and last_in members contain the time-stamps of the time the last data was received and sent, respectively. If you subtract either of these times from the current time, the result is the amount of time the VC has been idle in either direction.

5.22.2 The atm_cmi_addr Union

Convergence modules use the atm_cmi_addr union to pass a called party (destination) address to the CMM as part of the atm_cmm_connect function call. The format of this union is as follows:

union atm_cmi_addr {
     atm_addr_p     addr;
     struct {
          unsigned int     vci;
          unsigned int     vpi;
     } vcn
};

5.22.2.1 The addr Member

The addr member contains a pointer to an atm_addr structure, which is allocated by the convergence module (atm_cmm_alloc_addr), for creating a new switched virtual circuit (SVC).

5.22.2.2 The vcn Member

The vcn member is a structure that specifies the virtual channel identifier (VCI) and virtual path identifier (VPI) for creating a new PVC. See Appendix A for a description of the atm_cmm_connect function call.

5.22.3 The atm_cvg_params Structure

The CMM needs to know the capabilities and entry points of each convergence module. Convergence modules use the atm_cvg_params structure to pass this information to the CMM as part of the atm_cmm_register_cvg function call. To allow for future expansion of the atm_cvg_params structure, the convergence module should call the bzero command to insert nulls into the entire structure before filling in the known fields.

Example 5-1 shows the atm_cvg_params structure definition.

Example 5-1: The atm_cvg_params Structure Definition

struct atm_cvg_params {
        void (*receive)(atm_vc_p vc,
                        struct mbuf *mbp,
                        int length,
                        struct mbuf *trailer,
                        char      pti,
                        char gfc);
        atm_error_t (*exception)(void *cvg_handle,
                        int command,
                        void *arg);
        int (*mmi_manage)(void *cvg_handle,
                        int cmd,
                        void *arg,
                        int *retval,
                        struct ucred *cred);
        void (*endpt_receive)(atm_vc_p vc,
                        struct mbuf *mbp,
                        int length,
                        struct mbuf *trailer,
                        char      pti,
                        char gfc,
                        atm_addr_p addr);
        void *reserved1;
        void *reserved2;
        void *reserved3;
};

5.22.3.1 The receive Member

The receive member specifies a pointer to a routine that the CMM calls to to notify the convergence module of incoming data. The receive routine receives one copy of VC data, independent of how many local endpoints are added to the VC.

A convergence module must supply either a xxx_receive routine or an xxx_endpt_receive routine.

5.22.3.2 The exception Member

The exception member specifies a pointer to a routine that CMM uses to notify the convergence module of new connections and exception conditions. A convergence module must supply an exception routine.

5.22.3.3 The mmi_manage Member

The mmi_manage member specifies a pointer to a routine that CMM uses to manage the convergence module through the ATM Module Management Interface (MMI). A convergence module must supply an xxx_mmi routine if it is to be managed through the MMI.

5.22.3.4 The endpt_receive Member

The endpt_receive member specifies a pointer to a routine that CMM uses to notify the cnvergence module of incoming data. For a given unit of incoming data, the CMM calls the xxx_endpt_receive routine once for each local endpoint. The CMM provides a unique mbuf chain on each call, which references the received data.

A convergence module must supply either a xxx_receive routine or an xxx_endpt_receive routine.

5.22.3.5 The reserved1, reserved2, and reserved3 Members

The reserved1, reserved2, and reserved3members are reserved for future use, and should be specified as NULL.