The ATM convergence module interface enables all kernel-level protocol convergence modules (convergence modules, for short) to interface kernel networking protocol stacks to the Tru64 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 B 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.
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 a
xxx_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.
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 Tru64 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) 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.
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 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 B
for a description of the
atm_cmm_connect
function call.