![[Contents]](TOC.GIF){kind=small}
![[Prev. Chapter]](REW.GIF){kind=small}
![[Next Section]](NEXT.GIF){kind=small}
![[Next Chapter]](FF.GIF){kind=small}
![[Index]](INDEX.GIF){kind=small}
![[Help]](HELP.GIF){kind=small}
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:
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.
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.
![[Prev. Section]](PREV.GIF){kind=small}
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:
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.
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:
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.
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 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.
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.
Note
The DIGITAL UNIX ATM subsystem does not support the creation of outgoing point-to-multipoint calls and cannot accept more than one endpoint on incoming point-to-multipoint calls. However, the subsystem can accept one endpoint on an incoming point-to-multipoint call that originates from another vendor's UNIX system.
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 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).
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 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 3.6 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.
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:
atm_vc_stats
-- The virtual circuit
statistics structure
atm_cmi_addr
-- The called party address
union
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 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).
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.