![[Return to Library]](BOOKSHELF.GIF)
![[Contents]](TOC.GIF)
![[Previous Chapter]](REW.GIF)
![[Next Section]](NEXT.GIF)
![[Next Chapter]](FF.GIF)
![[Index]](INDEX.GIF)
![[Help]](HELP.GIF)
The ATM convergence module interface enables all kernel-level protocol convergence modules (convergence modules, for short) to interface kernel networking protocol stacks to the Digital UNIX 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:
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.
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.
![[Previous Section]](PREV.GIF)
When the CMM receives data on a VC that the convergence module owns, the CMM calls the xxx_receive function to pass incoming data to the convergence module. This function is declared within the convergence module.
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.
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:
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 Digital UNIX ioctl call with the following exceptions:
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.
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 NSAP 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.
If a convergence module needs to reserve resources (such as bandwidth) either prior to making an outgoing connection for a Constant Bit Rate (CBR) or pacing 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 or pacing 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.
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.
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.
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 7 for more information on connections.
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 teardown 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).
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.
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.
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.
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.
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 network services access point (NSAP) associated with the bound convergence module. The NSAP 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 NSAPs. If the NSAP specified by the called party address of an incoming call does not exist, the CMM rejects the call. See Section 3.6 for more information on PPAs and NSAPs.
By binding to a PPA, a convergence module is creating an NSAP 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 NSAP 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.
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.
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.
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.
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.
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.
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.
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.
The ATM device driver interface uses the following structures exclusively:
The atm_vc_stats structure contains information on successful return from the atm_cmm_vc_stats function. Table 6-1 lists those members of the atm_vc_stats structure, with their associated data types, that convergence modules might reference.
| 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.
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
};
The addr member contains an atm_addr structure, which is allocated by the convergence module, for creating a new switched virtual circuit (SVC).
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.