![[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}
This appendix contains a description of each of the routines described in this guide, in reference-page format. The routines are in alphabetical order.
atm_cmm_accept
atm_cmm_accept
- Accepts a previously deferred call and informs the CMM that the
call should be accepted
atm_error_t atm_cmm_accept(
atm_addr_p addr,
atm_vc_services_t give
);
Specifies a pointer to the
atm_addr
structure
for the call being accepted.
This is the same pointer passed into the convergence
module's
xxx_connect
routine when the call first came in.
This argument is not currently used.
The
atm_cmm_accept
routine is a convergence module
interface that accepts a previously deferred incoming call, notifies the CMM,
and sets the circuit resource parameters.
The incoming call was deferred
when a convergence module returned
ATM_CAUSE_DEFER
from
its
xxx_connect
routine.
Typically, the determination is done within a set period of time, as defined by the signaling protocol, before the calling party times out on the call request.
The connection is not established and ready for use until the convergence module receives the appropriate exception notifications.
If connection setup is proceeding,
atm_cmm_accept
returns
ATM_CAUSE_GOOD; otherwise, it returns an ATM error
number that indicates the reason the call failed.
If the call fails, the
convergence module should remove any reference to the call.
xxx_connect
Section 7.2 for information on accepting connections
![[Prev. Section]](PREV.GIF){kind=small}
atm_cmm_activate_con
atm_cmm_activate_con
atm_error_t atm_cmm_activate_con(
atm_sig_handle_t sm,
atm_addr_t *addr
);
Specifies the signaling module handle that the CMM returned in the registration call.
Specifies a pointer to an
atm_addr
structure
that contains all the parameters of the call.
This pointer must point to
the same
atm_addr
structure that was passed in either the
atm_cmm_new_call
function call or in the
xxx_setup
and
xxx_add
function calls since this pointer is the handle
that refers to the specific connection.
The
atm_cmm_activate_con
routine is a signaling
module interface.
Signaling modules call this routine when they receive an
indication from the network that the circuit is connected.
The routine notifies
the CMM that the connection is ready to carry data.
The CMM enables the VC
locally, and passes the notification to the device driver and protocol convergence
modules.
Note
Do not make this call before circuit connection.
If the indicated connection is found on the system no matter what the
result of the operation,
atm_cmm_activate_con
returns
ATM_CAUSE_GOOD.
If the indicated connection is not found, an error
value is returned indicating that the signaling module should release the
connection since the CMM has no reference to it.
atm_cmm_con_release,
xxx_setup,
xxx_add
Section 7.4 for information on releasing connections
atm_cmm_add
atm_cmm_add
atm_err_t atm_cmm_add(
atm_cvg_handle_t cm,
atm_addr_t *addr,
atm_uni_call_ie_p ei,
atm_vc_t *vc
);
Specifies a value returned to the convergence module by the registration function call. This uniquely identifies the convergence module making the request.
Specifies a pointer to a properly set
atm_addr
structure that specifies the address of the endpoint to be added to the connection.
Specifies a pointer to an array of
atm_uni_call_ie
structures that has been initialized with information to be used
in placing the additional call.
This argument must be NULL if no optional
IEs are specified.
Specifies a pointer to the
atm_vc
structure
of the VC to which the endpoint is to be added.
The VC must have been created
with the
ATM_CT_PTM
flag set.
The
atm_cmm_add
routine is a convergence module interface
that adds endpoints to an existing point-to-multipoint connection.
You can
add endpoints at any time only to connections that were created with the
ATM_CT_PTM
flag set.
See
Example B-2
for a code example of the
atm_cmm_add
routine.
If the endpoint add is proceeding,
atm_cmm_add
returns
ATM_CAUSE_GOOD.
The convergence module receives the
ATM_CME_CALL_FAILED
or the
ATM_CME_EP_ACTIVE
exception indications
to report the progress of the call.
ATM_CME_EP_ACTIVE
indicates
that the call completed and the connection to the endpoint is active and can
transport data.
These indications do not reflect the state of any other endpoint
associated with the VC.
If the endpoint add cannot proceed, an ATM error
number is returned.
atm_cmm_drop
Chapter 7 for information on connections
atm_cmm_adi_set_cause
atm_cmm_adi_set_cause
atm_err_t atm_cmm_adi_set_cause(
atm_drv_handle_t driver,
atm_vc_p vp,
atm_addr_p addr,
char *reason,
atm_error_t cause,
atm_location_t location,
unsigned char diag_length,
unsigned char *diag
);
Specifies the interface on which the condition occurred. This is the driver handle that the CMM assigned at driver registration time.
Specifies a pointer to the VC on which the condition occurred. If the error applies to one endpoint, set the value to NULL and set the addr value to non-NULL.
Specifies a pointer to the
atm_addr
structure
for the endpoint on which the error occurred.
If the error applies to all
endpoints on the VC (global), set the value to NULL and set the
vp
value to non-NULL.
Specifies a NULL-terminated character string that contains descriptive text for the error.
Specifies the
atm_error_t
value that describes
the condition.
Specifies an
atm_location_t
value that
indicates the location in the network where the error occurred.
Specifies the length (in bytes) of the data in the diag argument.
Specifies a string of bytes that contains diagnostic information
about the error.
This data might be passed to the network in the
diag
field of a Cause IE.
The
atm_cmm_adi_set_cause
routine is a device driver
interface that records an error or normal condition associated with a VC or
endpoint.
The condition is stored as an
atm_cause_info
structure together with the VC.
Convergence and signaling modules can retrieve
this information by using the
atm_cmm_next_cause
routine.
Users can display this information by using the
atmconfig
utility.
Errors or events stored with the
atm_cmm_adi_set_cause
routine are visible to the network and to the other end of the connection.
When a signaling module releases a connection or drops an endpoint, the module
extracts the most recent cause from a VC or endpoint and creates a Cause IE.
If the cause is recorded successfully,
atm_cmm_adi_set_cause
returns
ATM_CAUSE_GOOD.
If the driver handle,
vp
argument, or
addr
argument is
invalid,
atm_cmm_adi_set_cause
returns
ATM_CAUSE_BARG.
atm_cmm_adi_set_log,
atm_cmm_next_cause,
atm_cmm_set_cause,
atm_cmm_smi_set_cause
Section 3.10.7 for information on cause information
atm_cmm_adi_set_log
atm_cmm_adi_set_log
atm_err_t atm_cmm_adi_set_log(
atm_drv_handle_t driver,
atm_vc_p vp,
atm_addr_p addr,
char *reason,
atm_error_t cause,
atm_location_t location,
unsigned char diag_length,
unsigned char *diag
);
Specifies the interface on which the condition occurred. This is the driver handle that the CMM assigned at driver registration time.
Specifies a pointer to the VC on which the condition occurred. If the error applies to one endpoint, set the value to NULL and set the addr value to non-NULL.
Specifies a pointer to the
atm_addr
structure
for the endpoint on which the error occurred.
If the error applies to all
endpoints on the VC (global), set the value to NULL and set the
vp
value to non-NULL.
Specifies a NULL-terminated character string that contains descriptive text for the error.
Specifies the
atm_error_t
value that describes
the condition.
Specifies the location in the network where the error occurred.
Specifies the length (in bytes) of the data in the diag argument.
Specifies a string of bytes that contains diagnostic information
about the error.
This data might be passed to the network in the
diag
field of a Cause IE.
The
atm_cmm_adi_set_log
routine is a device driver
interface that records an error or normal condition associated with a VC or
endpoint.
The condition is stored as an
atm_cause_info
structure together with the VC.
Users can display this information by using
the
atmconfig
utility.
Errors or events stored with the
atm_cmm_adi_set_log
routine are logged on the local system only, and are not available when a
signaling module generates a Cause IE.
Logging provides information about
VC or endpoint activity for a system or network administrator to view on the
local system.
If the cause is recorded successfully,
atm_cmm_adi_set_log
returns
ATM_CAUSE_GOOD.
If the driver handle,
vp
argument, or
addr
argument is
invalid, the routine returns
ATM_CAUSE_BARG.
atm_cmm_adi_set_cause,
atm_cmm_next_cause,
atm_cmm_set_log,
atm_cmm_smi_set_log
Section 3.10.7 for information on cause information
atm_cmm_alloc_addr
atm_cmm_alloc_addratm_addr
structure
atm_addr_p atm_cmm_alloc_addr(
void/
);
The
atm_cmm_alloc_addr
routine is a signaling and
convergence module interface that allocates memory for the
atm_addr
structure and initializes the structure members.
One
atm_addr
structure is allocated by a convergence module for each
endpoint it calls and by a signaling module for each endpoint that calls the
local host.
Usually, the CMM frees all ATM address structures associated with a
VC when the VC is destroyed.
However, under some error conditions (such as
when a convergence module is allocating a series of structures and one allocation
fails), it may be necessary for the allocating module to free memory it has
allocated.
In these cases, modules can call the
atm_cmm_free_addr
routine with the value returned from
atm_cmm_alloc_addr
to free memory.
See
Section B.1
for a code example of the
atm_cmm_alloc_addr
routine.
If storage cannot be allocated, a NULL is returned; otherwise, a pointer to the allocated memory is returned.
atm_cmm_free_addr
Section B.1 for information on connections
atm_cmm_alloc_ie
atm_cmm_alloc_ieatm_uni_call_ie
structure
atm_uni_call_ie_p atm_cmm_alloc_ie(
int num_ie
);
Specifies the number of IE structures to allocate.
The
atm_cmm_alloc_ie
routine is a convergence module
interface that allocates memory for the
atm_uni_call_ie
structure and initializes the structure members.
Typically, the convergence protocol module frees all UNI signaling structures
associated with a VC when the VC is destroyed.
However, under some error
conditions (such as when a convergence module is allocating a series of structures
and one allocation fails) the allocating module (either the convergence or
signaling module) might have to free memory it has allocated.
Convergence
modules should not free memory for this structure if the
atm_cmm_connect
or related call succeeds because the CMM will free the memory.
See
Section B.1,
Section B.2,
and
Section B.3
for code examples of the
atm_cmm_alloc_ie
routine.
If storage cannot be allocated, a NULL is returned; otherwise, a pointer to the allocated memory is returned.
atm_cmm_free_ie
Chapter 7 for information on connections
atm_cmm_alloc_services
atm_cmm_alloc_servicesatm_vc_services
structure
atm_vc_services_p atm_cmm_alloc_services(
void/
);
The
atm_cmm_alloc_services
routine is a signaling
and convergence module interface that allocates memory for the
atm_vc_services
structure and initializes the structure members to default values
for best-effort available bit rate (ABR) service.
Once allocated, other ATM
modules can change the
atm_vc_services
structure as needed.
Typically, the CMM frees the
atm_vc_services
structure
associated with a VC when the VC is destroyed.
However, under some error
conditions (such as when a convergence module is allocating a series of structures
and one allocation fails), the allocating module might need to free memory
it has allocated.
In these cases, modules call the
atm_cmm_free_services
routine with the value returned from
atm_cmm_alloc_services
to free memory.
See
Section B.1
for a code example of the
atm_cmm_alloc_services
routine.
If storage cannot be allocated, a NULL is returned; otherwise, a pointer to the allocated memory is returned.
atm_cmm_free_services
Chapter 7 for information on connections
atm_cmm_bind_info
atm_cmm_bind_info
unsigned long atm_cmm_bind_info(
atm_bind_handle_t handle,
atm_bind_info_t it
);
Specifies a pointer to a CMM bind handle of a currently active AESA binding. Information is retrieved from the PPA associated with the bind point.
Specifies the type of information that is being queried. The value returned depends on the object type of the queried information. The following values may be used to query the indicated information:
| Value | Meaning |
ATM_BIND_INFO_HANDLE |
Returns the convergence module's bind handle, which the convergence module supplied at the time it created the AESA bind point. |
ATM_BIND_INFO_ID |
Returns a unique global value for referencing
the bind point.
Each bind point gets assigned a unique ID (which is different
from the bind handle).
An application program can use this value when specifying
a bind point (atmconfig
uses these values to reference
bind points).
The returned value is 32-bits wide. |
ATM_BIND_INFO_PPA |
Returns a pointer to the PPA associated with the AESA bind point. |
ATM_BIND_INFO_SELECTOR |
Returns the selector value assigned to the bind point. Primarily, a convergence module uses this to request that the CMM assign an unused selector value to a bind point. The value returned is between 0 and 255 for SVC bindings, and is 31-bits wide for PVC bindings. |
ATM_PPA_ALLOCGRANE |
Returns a type of
atm_bw_granularity_p, which reflects the underlying interface's units of bandwidth allocation,
or its allocation granularity. |
ATM_PPA_ALLOCLIMIT |
Returns a type of
atm_bw_granularity_p, which reflects the underlying interface's per-VC bit rate limits,
expressed in allocation granularity units. |
ATM_PPA_AVAILRES |
Returns a type of
atm_services_granes_p, which reflects the amount of bandwidth (in granularity units)
currently available for new CBR and pacing circuits over the underlying interface. |
ATM_PPA_BRESVLIM |
Returns the user-configurable limit, expressed as a percentage of backward bandwidth, on CBR circuits. |
ATM_PPA_ESI |
Returns the ESI that the signaling module supplied when the PPA was created. |
ATM_PPA_ESIID |
Returns the unique ESI identifier associated with the PPA's ESI. |
ATM_PPA_ESILEN |
Returns the length of the ESI that the signaling module supplied when the PPA was created. |
ATM_PPA_ESIPID |
Returns the ESI identifier of the PPA's parent ESI. |
ATM_PPA_FRESVLIM |
Returns the user-configurable limit, expressed as a percentage of forward bandwidth, on CBR and pacing circuits. |
ATM_PPA_INFO_BURST_AVAIL |
Returns the available burst cell rate in cells-per-second. This is the amount of burst cell rate that is available to be reserved by a convergence module. |
ATM_PPA_INFO_BURST_MAX |
Returns the maximum burst cell rate supported by the interface in cells-per-second. |
ATM_PPA_INFO_CAPABILITIES |
Returns the driver's capabilities for that interface. |
ATM_PPA_INFO_DID |
Returns a unique global value that can be used to reference the driver for the underlying interface. |
ATM_PPA_INFO_DNAME |
Returns the name of the driver for the underlying interface. |
ATM_PPA_INFO_DUNIT |
Returns the driver's unit number for the underlying interface. |
ATM_PPA_INFO_FC |
Returns a nonzero value if hardware flow control is currently enabled on the interface. |
ATM_PPA_INFO_HARD_MTU |
Returns the largest PDU (in bytes) that the interface supports. This is valid only for interfaces that support AAL5 or AAL3/4 SAR functions in hardware. |
ATM_PPA_INFO_HI_VCI |
Returns the highest value that may be used for a VCI on the interface. |
ATM_PPA_INFO_HI_VPI |
Returns the highest value that may be used for a VPI on the interface. |
ATM_PPA_INFO_ID |
Returns a unique global value for referencing
the PPA.
Each PPA gets assigned a unique ID when it is created.
An application
program can use this value to specify a bind point (atmconfig
uses these values to reference bind points).
The returned value is 32-bits
wide. |
ATM_PPA_INFO_MAX_VCI |
Returns the maximum number of VCIs that the interface supports. |
ATM_PPA_INFO_MAX_VPI |
Returns the maximum number of VPIs that the interface supports. |
ATM_PPA_INFO_MEDIA |
Returns a value that indicates the type of
physical media to which the interface is connected.
The return value is of
the type
atm_media_type_t. |
ATM_PPA_INFO_PEAK_AVAIL |
Returns the available peak cell rate (in cells-per-second). This is the amount of peak cell rate that is available to be reserved by a convergence module. |
ATM_PPA_INFO_PEAK_MAX |
Returns the maximum peak cell rate (in cells-per-second) that the interface supports. |
ATM_PPA_INFO_QUEUES |
Returns the number of scheduling queues that the driver has made visible to the CMM. |
ATM_PPA_INFO_SNAME |
Returns the name of the signaling module that created the PPA. |
ATM_PPA_INFO_SUST_AVAIL |
Returns the available sustainable cell rate (in cells-per-second). This is the amount of sustainable cell rate that is available for a convergence module to reserve. |
ATM_PPA_INFO_SUST_MAX |
Returns the maximum sustainable cell rate (in cells-per-second) that the interface supports. |
ATM_PPA_INFO_TOTAL_VC |
Returns the maximum number of VCs that can be opened on the interface at any given time. |
ATM_PPA_INFO_TYPE |
Returns a value that indicates the underlying
interface type.
The returned value is of the type
atm_interface_t. |
ATM_PPA_INFO_UNI |
Returns the UNI type associated with the
PPA, which the signaling module supplied at the time the PPA was created.
The return value is of the type
atm_uni_type_t. |
ATM_PPA_INFO_VC_LEFT |
Returns the number of unopened VCs on the
interface at the time of the call.
This is the total number of VCs (the value
returned by
ATM_PPA_INFO_TOTAL_VC) minus the number of
VCs currently opened. |
ATM_PPA_MAX_VC_BBW |
Returns the user-configurable maximum per-VC backward (incoming) bit rate (in allocation granularity units) permitted over the underlying interface. |
ATM_PPA_MAX_VC_FBW |
Returns the user-configurable maximum per-VC forward (outgoing) bit rate (in allocation granularity units) permitted over the underlying interface. |
ATM_PPA_MAXRES |
Returns a type of
atm_services_granes_p, which reflects the maximum bandwidths available for CBR and pacing
circuits over the underlying interface.
These bandwidths (expressed in granularity
units) are a function of the interface limits and the user-configurable limits
on the percentage of bandwidth available to CBR and pacing circuits. |
ATM_PPA_NUM_VCI |
Returns the current number of VCIs configured on the underlying interface. |
ATM_PPA_NUM_VPI |
Returns the current number of VPIs configured on the underlying interface. |
ATM_PPA_PEAK_CELLRATE |
Returns the peak PDU bit rate (in cells-per-second) for the underlying interface. |
ATM_PPA_UNUSEDRES_BACK |
Returns the amount of backward (incoming) bandwidth (in cells-per-second) currently reserved for, but not yet applied to, CBR circuits. |
ATM_PPA_UNUSEDRES_FWD |
Returns the amount of forward (outgoing) bandwidth (in cells-per-second) currently reserved for, but not yet applied to, CBR and pacing circuits. |
The
atm_cmm_bind_info
interface is a convergence
module interface that queries the CMM for 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).
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 the bind directly. Thus, the convergence module requires no specific knowledge of any device driver or device driver-related structures.
If an invalid query is made,
atm_cmm_bind_info
returns
a value of 0.
atm_cmm_del_ppa,
atm_cmm_new_ppa,
atm_cmm_ppa_bind,
atm_cmm_ppa_info
Section 4.4.1.15 for information on driver capabilities
atm_cmm_con_deleted
atm_cmm_con_deleted
atm_err_t atm_cmm_con_deleted(
atm_sig_handle_t sm,
atm_addr_p addr
);
Specifies the signaling module handle that the CMM returned in the registration call.
Specifies a pointer to an
atm_addr
structure
that contains all the parameters of the call.
This pointer must point to
the same
atm_addr
structure that was passed in either the
atm_cmm_new_call
function call or in the
xxx_setup
and
xxx_add
function calls since this pointer is the handle
that refers to the specific connection.
The
atm_cmm_con_deleted
interface is a signaling
module interface.
A signaling module calls this routine when the module receives
confirmation of a connection's release from the switch.
The routine notifies
the CMM that the connection no longer exists.
The CMM holds the resources associated with the connection for a brief period of time, then releases them, giving all incoming queues time to clear. The CMM also notifies convergence modules that the connection has been released.
This routine notifies the CMM of both the deletion of point-to-point connections and of the deletion of parties in point-to-multipoint connections.
If the endpoint referenced is invalid, the
atm_cmm_con_deleted
routine returns
ATM_CAUSE_EIR
to indicate that
it has no previous entry for the connection; otherwise, it returns
ATM_CAUSE_GOOD.
atm_cmm_activate_con,
atm_cmm_con_release,
xxx_add,
xxx_setup
Section 7.4.2 for information on releasing connections
atm_cmm_con_failed
atm_cmm_con_failed
atm_error_t atm_cmm_con_failed(
atm_sig_handle_t sm,
atm_addr_t *addr
);
Specifies the signaling module handle that the CMM returned in the registration call.
Specifies a pointer to an
atm_addr
structure
that contains all the parameters of the call.
This pointer must point to
the same
atm_addr
structure that was passed in either the
atm_cmm_new_call
function call or in the
xxx_setup
and
xxx_add
function calls since this pointer is the handle
that refers to the specific connection.
The
atm_cmm_con_failed
routine is a signaling module
interface.
When the CMM makes a connection request to a signaling module,
the call to the remote system might fail for some reason.
Since call creation
is an asynchronous operation, the signaling module might encounter errors
during call processing after the
xxx_setup
call has returned.
In these cases, the signaling module notifies the CMM of failures both of
point-to-point connections and of additional endpoints in point-to-multipoint
connections.
In the case of the failure of endpoints in a point-to-multipoint
connection, the
addr
pointer points to the
atm_addr
structure of the added endpoint.
If the endpoint referenced is invalid, the
atm_cmm_con_failed
routine returns
ATM_CAUSE_EIR
to indicate that
it has no previous entry for the connection; otherwise, it returns
ATM_CAUSE_GOOD.
Section 7.1 for information on setting up connections
atm_cmm_con_release
atm_cmm_con_release
atm_error_t atm_cmm_con_release(
atm_sig_handle_t sm,
unsigned long reference,
atm_ppa_p ppa
);
Specifies the signaling module handle that the CMM returned in the registration call.
Specifies the unique call reference value that identifies the connection to be released.
Specifies a pointer to the PPA to which the VC being released belongs.
The
atm_cmm_con_release
routine is a signaling module
interface.
The signaling module calls this routine when the module receives
a request to tear down a connection from the network or endpoint.
This notifies
the CMM to release a connection or virtual circuit, and not to drop a single
endpoint from a connection.
When this routine is called, the CMM makes the
connection unavailable for transmission, initiates the teardown of the referenced
connection and all associated endpoints, and awaits notification that the
VC has been torn down.
If the endpoint referenced is invalid, the
atm_cmm_con_release
routine returns
ATM_CAUSE_EIR
to indicate that
it has no previous entry for the connection; otherwise, it returns
ATM_CAUSE_GOOD.
atm_cmm_activate_con,
atm_cmm_con_deleted
Section 7.4 for information on releasing connections
atm_cmm_connect
atm_cmm_connect
atm_error_t atm_cmm_connect(
atm_cvg_handle_t cm,
enum atm_ctype type,
atm_bind_handle_t calling,
union atm_cmi_addr called,
atm_uni_call_ie_p ei,
int aging,
atm_vc_service_p params
);
Specifies a value returned to the convergence module by the registration function call. This uniquely identifies the convergence module making the request.
Specifies the type of connection being requested. The following types are defined:
| Connection | Meaning |
ATM_CT_PTM |
Specifies that the connection is the first connection in a point-to-multipoint connection. |
ATM_CT_PTP |
Specifies that the connection is a point-to-point connection only. |
ATM_CT_PVC |
Specifies that the connection is a permanent virtual circuit. |
Specifies the calling party address information to be used when placing the call. This is the identifier returned from the bind operation when the convergence module is bound to a PPA. This specifies the fully qualified AESA that will be used as the calling party address, and is used to direct the call to the proper signaling module and device driver.
Specifies the called party (destination) address for the connection.
When requesting the creation of a new SVC, the
atm_cmi_addr
union contains a pointer to an
atm_addr
structure that
the convergence module allocates (using the proper CMM routine) with all necessary
structure members set to specify the intended destination of the call.
The
convergence module must not free the storage for this structure; the CMM performs
the deallocation when the connection closes (the caller is responsible for
deallocating this structure if this routine returns an error indication).
When requesting the creation of a new PVC, this argument contains the VCI
and VPI for the new VC.
Interpretation of the information in this argument
is based on the value of the
type
argument.
See
Section 6.22.2
for information on the
atm_cmi_addr
union.
Specifies a pointer to an array of
atm_uni_call_ie
structures that has been initialized with information to be used
in placing the call.
This argument must be NULL if no optional IEs are specified.
Specifies how the CMM is to age the connection.
The CMM provides
connection aging services to detect connections that are unused and to delete
the resources associated with the connections.
The CMM provides several aging
algorithms.
The convergence modules must specify an initial aging algorithm
at the time the circuit is created, but can modify this setting at any time
through the
atm_cmm_vc_control
routine.
Specifies an
atm_vc_services_p
pointing
to a properly set
atm_vc_services
structure that defines
the circuit parameters.
For CBR or pacing circuits, the
params
argument can be a resource reservation, that is, a services
structure that is backed by reserved resources.
The
atm_cmm_connect
routine is a convergence module
interface that requests the CMM to create a connection to a remote system.
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.
To
create a PVC, set the
type
argument to
ATM_CT_PVC, set the
calling
argument
to the bind handle returned by the CMM for a binding on the PVC PPA, set the
params
argument to the circuit parameters for the new PVC, and
set the
called
argument to an
atm_cmi_addr
union that contains valid
vci
and
vpi
data; the
aging
arguments are ignored.
If the system cannot provide the level of service specified in the
params
argument, the appropriate error is returned.
No parameter
negotiation is done for PVCs.
See
Section B.1
for a code example of the
atm_cmm_connect
routine.
If the call is proceeding, the
atm_cmm_connect
routine
returns
ATM_CAUSE_GOOD; otherwise, it returns an ATM error
number that indicates the reason the call cannot proceed.
If the call proceeds, the
atm_vc_p
information in
the
atm_addr
structure is valid on return.
However, this
does not mean the VC is ready to carry data.
It means only that the CMM has
allocated an
atm_vc
structure with which it can keep track
of the connection.
The convergence module is notified through the
xxx_except
routine when the call has completed and when the VC can
carry data.
atm_cmm_vc_control
Section 6.22.2
for information on the
atm_cmi_addr
union
Section 7.3 for information on connection aging
Section 7.5 for information on PVC creation
atm_cmm_del_esi
atm_cmm_del_esi
atm_err_t atm_cmm_del_esi(
atm_cvg_handle_t,
atm_esi_handle_t
);
The
atm_cmm_del_esi
routine is a convergence module
interface that deletes an ATM address.
A convergence module uses this routine
when it no longer needs a new address it has created.
Only the convergence
module that registered the address can unregister the address.
Deleting an ESI causes the signaling module to delete all PPAs created from the ESI.
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's PPAs.
atm_cmm_del_ppa
atm_cmm_del_ppa
atm_error_t atm_cmm_del_ppa(
atm_sig_handle_t sm,
atm_ppa_p ppa
);
Specifies the signaling module handle that the CMM returned in the registration call.
Specifies the PPA pointer that was returned when the PPA was added to the system.
The
atm_cmm_del_ppa
routine is a signaling module
interface.
When a signaling protocol, in cooperation with a switch, deletes
an address from the list of recognized addresses on an interface, the signaling
module calls this routine to notify the CMM that the deleted PPA associated
with the address is no longer valid.
The CMM then informs convergence modules
bound to the PPA that the address is no longer valid and initiates a teardown
of all VCs associated with the address.
All PPAs, except for the PVC PPAs, are owned by a signaling module. That is, a signaling module is always responsible for the creation and deletion of a PPA. This is required since the registration of addresses with a switch is handled entirely by signaling protocols. Also, PPAs may be deleted because of actions on the network that are completely unrelated to the local system. Because of this, the CMM does not automatically delete PPAs when an interface is taken down or loses its connection to the switch. The CMM responds to an interface shutdown by deleting the PVC PPA. Signaling modules will delete PPAs when it is appropriate for their protocols to do so (such as when they lose communications with the switch).
Upon successful completion, the
atm_cmm_del_ppa
routine
returns
ATM_CAUSE_GOOD; otherwise, it returns an ATM error
number.
atm_cmm_new_ppa,
atm_cmm_ppa_bind,
atm_cmm_ppa_info
atm_cmm_drop
atm_cmm_drop
atm_err_t atm_cmm_drop(
atm_cvg_handle_t cm,
atm_addr_t *addr
);
Specifies a value that the registration function call returns to the convergence module. This uniquely identifies the convergence module making the request.
Specifies a pointer to the
atm_addr
structure
of the endpoint to be dropped.
The
atm_cmm_drop
routine is a convergence module
interface that drops a connection to an endpoint.
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 routine to manage multipoint VCs; you can also use it to initiate
the teardown of point-to-point VCs.
If the endpoint teardown is proceeding, the
atm_cmm_drop
routine returns
ATM_CAUSE_GOOD; otherwise, it returns an
ATM error number.
After the endpoint is torn down, the convergence module
receives an
ATM_CME_EP_DEAD
exception notification.
When
the last endpoint associated with a VC has been disconnected, the VC is torn
down.
atm_cmm_enquery
atm_cmm_enquery
atm_err_t atm_cmm_enquery(
atm_cvg_handle_t cm,
atm_addr_t *ep
);
Specifies a value that the registration function call returns to the convergence module. This uniquely identifies the convergence module making the request.
Specifies the endpoint to be queried.
The
atm_cmm_enquery
routine is a convergence module
interface that requests that the connection state information for an endpoint
be updated.
This initiates a connection enquiry to the endpoint that results
in the
atm_addr
structure for the endpoint being updated
with the latest status information.
This routine may be called any time a
connection is active.
If the enquiry is initiated, the
atm_cmm_enquery
routine returns
ATM_CAUSE_GOOD; otherwise, it returns an
ATM error number, indicating the reason the enquiry was not initiated.
When
the enquiry reply is received by the system, the convergence module is informed
by an
ATM_CME_ENQUERY_DONE
exception notification.
When
the convergence module gets this notification, it may then examine the updated
endpoint status information in the
atm_addr
structure.
atm_cmm_ep_dropped
atm_cmm_ep_dropped
atm_err_t atm_cmm_ep_dropped(
atm_sig_handle_t sm,
unsigned long reference,
long epreference,
atm_ppa_p ppa
);
Specifies the signaling module handle that the CMM returned in the registration call.
Specifies the unique call reference value that identifies the connection to be released.
Specifies the unique endpoint reference value that identifies the endpoint to be dropped.
Specifies a pointer to the PPA to which the VC being released belongs.
The
atm_cmm_ep_dropped
routine is a signaling module
interface.
A signaling module calls this routine when the module receives
a request to drop an endpoint from a connection.
This notifies the CMM to
drop endpoints in a multipoint connection.
The endpoint must already exist
on the system.
The CMM notifies the convergence module that owns the endpoint's VC that the endpoint has been dropped and deletes the endpoint. If the last endpoint associated with a VC is dropped, the CMM initiates the release of the VC.
If the endpoint referenced is invalid, the
atm_cmm_ep_dropped
routine returns
ATM_CAUSE_EIR
to indicate that
it has no previous entry for the connection; otherwise, it returns
ATM_CAUSE_GOOD.
atm_cmm_error
atm_cmm_error
void atm_cmm_error(
atm_drv_handle_t driver,
int error,
atm_vc_t *vc
);
Specifies the interface on which the error has occurred. This is the handle assigned to the driver when the driver registers with the CMM.
Specifies a numeric value that indicates one of the following error types:
| Error | Meaning |
ATM_DE_DOWN |
The driver detected a fatal medium error. In response, the CMM initiates the destruction of all VCs belonging to the failed interface. Further, the CMM considers the interface unavailable and rejects any requests for new connections on the interface. The driver must inform the CMM when the media is functional again. The vc argument is ignored for this notification. |
ATM_DE_UP |
The driver detected that the medium is up and ready to transfer data. When the CMM receives this indication, it allows the processing of connection requests. The vc argument is ignored for this notification. |
ATM_DE_STARTQ |
A driver output queue whose flow was controlled
is now able to accept additional data for transmission.
The
vc
argument is the number of the queue that is being enabled (0<=
vc
<
atm_drv_params.nqueue). |
ATM_DE_VC_FATAL |
A local, fatal error has occurred to the interface that causes one or more VCs to become inoperative. An example of this type of error might be an adapter memory error that destroys any information about the VC on the adapter. This indication reports errors from which the driver is unable to recover. The vc argument is a pointer to the failed VC. |
Specifies a pointer to the VC on which the error occurred. If the error is not associated with a VC, this is NULL.
The
atm_cmm_error
routine is a device driver interface.
When an ATM device driver detects errors on VCs or other interface failures,
the module calls this routine to report the error to the CMM.
When the CMM receives the error report, it recovers or shuts down the VC with the errors. The driver does not need to perform any other actions. If the VC must be destroyed, the CMM calls the driver through the driver management interface to deactivate or destroy the VC. If the error indicates an interface failure, the CMM tears down VCs on the interface.
Chapter 10 for information on flow control in the ATM subsystem
atm_cmm_findaddr
atm_cmm_findaddr
atm_addr_p atm_cmm_findaddr(
long call_reference,
long endpoint,
atm_ppa_p ppa
);
Specifies the unique call reference value assigned to the VC.
Specifies the endpoint reference value for an endpoint in a point-to-multipoint connection. This argument is set to 0 for the root of point-to-multipoint connections and for point-to-point connections.
Specifies the interface associated with the endpoint to look up. Since call reference values are usually unique only per interface, you must specify this argument to differentiate between VCs with the same reference value but belonging to different interfaces.
The
atm_cmm_findaddr
routine is a signaling module
interface that signaling modules use to request endpoint and VC information
from the CMM.
The CMM maintains all state information about each VC and calls
(endpoints) associated with the VC.
Signaling modules can call this routine at any time to resolve a reference
to a connection endpoint.
Once the reference is resolved, the signaling module
can access and modify structures as necessary as long as you follow locking
conventions.
For example, if the signaling module needs to process a STATUS
ENQUIRY request, all the information necessary to format the STATUS reply
is in the
atm_addr
structure.
This routine returns a reference
to the structure, enabling the signaling module to extract the data needed
to format the reply.
Upon successful completion, the
atm_cmm_findaddr
call returns a pointer to the
atm_addr
structure for the
specified endpoint.
Signaling modules can use this information to find the
atm_vc
structure, if necessary.
If the specified endpoint is not
found, the CMM returns NULL.
atm_cmm_find_driver
atm_cmm_find_driver
atm_drv_handle_t atm_cmm_find_driver(
char *name
);
Specifies a NULL-terminated character string that identifies the driver.
The
atm_cmm_find_driver
routine is a convergence
and signaling module interface that enables the module to determine whether
a specified driver is registered with the CMM.
If a convergence or signaling module provides MMI services, the module can use this routine to determine whether the driver over which it is requested to operate actually exists.
Upon successful completion, the
atm_cmm_find_driver
call returns the handle (atm_drv_handle_p) that identifies
the driver to the CMM.
If the driver is not registered, the call returns NULL.
atm_cmm_free_addr
atm_cmm_free_addratm_addr
structures
void atm_cmm_free_addr(
atm_addr_p addr
);
Specifies a pointer to the
atm_addr
structure
to free.
This is the same pointer passed into the
atm_alloc_addr
routine.
The
atm_cmm_free_addr
routine is a convergence module
interface that convergence modules use to free memory that they have allocated.
Usually, the CMM frees all ATM address structures associated with a
VC when the VC is destroyed.
However, under some error conditions (such as
when a convergence module is allocating a series of structures and one allocation
fails), it may be necessary for the allocating module to free memory it has
allocated.
In these cases, modules can call the
atm_cmm_free_addr
routine with the value returned from
atm_cmm_alloc_addr
to free memory.
atm_cmm_free_ie
atm_cmm_free_ie
void atm_cmm_free_ie(
atm_uni_call_ie_p u
);
Specifies a pointer to the
atm_call_ie
structure to free.
This is the same pointer returned from the
atm_cmm_alloc_ie
routine as a result of a successful storage allocation.
The
atm_cmm_free_ie
routine is a convergence module
interface that convergence modules use to free IE structure memory that they
have allocated.
See
Section B.1
for a code example of the
atm_cmm_free_ie
routine.
atm_cmm_free_services
atm_cmm_free_servicesatm_vc_services
structures and
releases reserved resources
atm_error_t atm_cmm_free_services(
atm_vc_services_p s
);
Specifies a pointer to the
atm_vc_services
structure to free.
This is the same pointer passed into the
atm_alloc_services
routine.
The
atm_cmm_free_services
routine is a convergence
module interface that convergence modules use to free memory that they have
allocated.
Typically, the CMM frees the
atm_vc_services
structure associated with a VC when the VC is destroyed.
However, under some
error conditions (such as when a convergence module is allocating a series
of structures and one allocation fails), the allocating module might need
to free memory it has allocated.
In these cases, modules call the
atm_cmm_free_services
routine with the value returned from
atm_cmm_alloc_services
to free memory.
A convergence module can also use the
atm_cmm_free_services
call to free a resource reservation or to terminate a resource
reservation request.
(See
Section 7.1
for more information.)
The
atm_cmm_free_services
call frees the
atm_vc_services_t
memory and releases its reserved resources, if any.
If the CMM is able to free the memory and any reserved resources, the
atm_cmm_free_services
call returns
ATM_CAUSE_GOOD.
If the services structure is associated with a resource that is in the process
of being released, the call returns
ATM_CAUSE_BUSY.
If
the convergence module inadvertently attempts to free an
atm_vc_services_t
that is attached to an active connection,
ATM_CAUSE_BUSY
is also returned.
atm_cmm_alloc_services,
atm_cmm_reserve_resources,
xxx_except
Section 6.2.1 for information on convergence module exception handling
atm_cmm_mib_response
atm_cmm_mib_response
atm_error_t atm_cmm_mib_response(
void *id,
unsigned int fieldlen,
unsigned char *fieldval
);
Specifies the access ID that the CMM passes into the signaling module's MIB access routine. The signaling module must not modify this value.
Specifies the length (in bytes) of the returned information.
This argument is valid only in response to an
ATM_MIB_GET
operation.
Specifies a pointer to a series of bytes that constitute the
value being retrieved by an
ATM_MIB_GET
operation.
Do
not use this for an
ATM_MIB_GET
operation.
The
atm_cmm_mib_response
routine is a signaling
module interface.
Sometimes a signaling module's MIB access routine can block
because of the need to contact some other network management entity.
When
the signaling module returns from the MIB access call, the module calls this
routine to notify the CMM of the completion of a MIB access and report any
retrieved values.
Upon successful completion, the
atm_cmm_mib_response
call returns
ATM_CAUSE_GOOD; otherwise, it returns an ATM
error number.
atm_cmm_new_call
atm_cmm_new_call
atm_error_t atm_cmm_new_call(
atm_sig_handle_t sm,
atm_addr_t *addr,
atm_uni_call_ie_p ie,
atm_vc_services services,
atm_ppa_p ppap,
int selector,
unsigned int vpi,
unsigned int vci,
long call_reference
);
Specifies the signaling protocol module handle that was returned by the registration function.
Specifies a pointer to an
atm_addr
structure
that contains all the information about the incoming call.
The signaling module
writes the information into the structure.
Specifies a pointer to an array of optional information elements received from the calling party. The signaling module converts data from the call setup message and fills in an array of information element structures.
Specifies a pointer to a properly set
atm_vc_services
structure.
This indicates the type of service the calling party
is requesting.
The signaling protocol module must extract the required information
from its signaling protocol messages.
All members of this structure must
be set.
If a signaling protocol does not provide means by which some of the
needed values can be specified, the signaling protocol module must supply
some reasonable defaults.
The CMM and driver require this information to
determine if there are sufficient local resources to handle the services the
caller is requesting.
The CMM modifies values in this structure to indicate
that the value should be negotiated with the calling party.
(This usually
means that the signaling module simply returns the modified values in the
reply to the calling party.)
Specifies the PPA on which the incoming call arrived.
Specifies the selector value taken from the called party address information sent by the caller. This indicates the service on the PPA that is being called.
Specifies the VPI value for the new VC that the network has created for this call.
Specifies the VCI value for the new VC that the network has created for this call.
Specifies a unique value that the signaling module has assigned to this call. This is the value used to reference this call during the call's entire lifetime on the system. This value is opaque to the CMM and can have special meaning to the signaling protocol module.
The
atm_cmm_new_call
routine is a signaling module
interface that a signaling module calls when it receives a new call.
This
notifies the CMM of the new call.
The CMM determines whether the call should
be accepted.
This CMM routine is nonblocking and returns with an indication
about the disposition of the call.
The CMM evaluates the call parameters and determines if the call should
be accepted.
If the call is accepted, the
atm_cmm_new_call
routine returns
ATM_CAUSE_GOOD.
If the CMM and convergence
module cannot immediately decide on the disposition of the call,
ATM_CAUSE_DEFER
is returned; the signaling module's exception routine
is called when the disposition of the call is determined.
If the call is rejected, this routine returns an ATM error number indicating
the reason.
The convergence module may supply additional information in the
cause
fields in the
atm_addr
structure.
If the
call is rejected (a value other than
ATM_CAUSE_GOOD
or
ATM_CAUSE_DEFER
is returned), the signaling module must deallocate
the storage for the
atm_addr
structure, the information
elements, and the
atm_vc_services
structure.
xxx_except
Section 7.2 for information on receiving connections
atm_cmm_new_esi
atm_cmm_new_esi
atm_esi_handle_t atm_cmm_new_esi(
atm_cvg_handle_t cvg_handle,
unsigned char *esi,
int esilen,
atm_ppa_p driver,
void *arg
);
Specifies the convergence module handle returned to the convergence module when it registered with the CMM.
Specifies a pointer to an array of the 6 bytes of ESI to be registered with the network.
Specifies the size (in bytes) of the ESI being added.
This
must be less than
ATM_MAX_ESI.
For UNI signaling, this
is always 6.
Specifies the driver handle of the interface on which the address is to be registered. This value is obtained from the PVC PPA for the driver on which the ESI is being registered.
Specifies a value that the convergence module creating the ESI uses to identify any PPAs created from the ESI. The CMM does not modify the value of this argument.
The
atm_cmm_new_esi
routine is a convergence module
interface that registers an ATM address with the network.
The module supplies
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.
The calling convergence module is notified of the new PPA(s) when the registration is complete. Note that the addition of a new ESI does not cause the immediate creation of a new PPA in cases where there is no signaling protocol that accepts the ESI, or if the link to the switch is down. In these cases, new PPAs are created when new signaling modules are registered and accept the ESIs, or when links to the switch become functional.
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 addresses; 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, all its created
addresses are destroyed.
If an ESI is deleted, the calling convergence module receives an
ATM_CME_ESI_DEL
exception notification.
If the registration process is proceeding, the
atm_cmm_new_esi
routine returns a handle for the new ESI; otherwise, it returns
a NULL.
If the requested ESI is already registered, the routine also returns
NULL.
atm_cmm_del_esi,
atm_cmm_ppa_bind
atm_cmm_new_ppa
atm_cmm_new_ppa
atm_ppa_p atm_cmm_new_ppa(
atm_sig_handle_t sm,
unsigned char *addr,
unsigned int addrlen,
unsigned char ton,
unsigned char anpi,
atm_drv_handle_t driver,
atm_esi_p esi,
void *ppas_id,
atm_uni_type_t uni,
void *sig_info
);
Specifies the signaling module handle that the registration function call returned.
Specifies a pointer to a series of bytes in memory that is the fully formed new address. The CMM copies this information and the signaling module can free these bytes on return if they are not needed for internal use.
Specifies the exact number of bytes in the address.
This
must be less than
ATM_PPA_MAX_ADDR.
For UNI signaling,
the value of this argument is always 20.
Specifies the endpoint's address type. These bits are the same as the type of number field in the Called Party Number IE (right justified).
Specifies the address or numbering plan identification information for the address. These bits are the same as those in the corresponding field of the Called Party Number IE.
Specifies the device driver handle for the interface on which the new address has been created. This value is taken from the PVC PPA over which the signaling module has created the new address.
Specifies which ESI was used in the creation of this address.
This is the
atm_esi
structure pointer that gets passed
in to the signaling module on the
ATM_SIGE_NEWESI
exception.
Specifies an internal value that the signaling module can
use to keep track of the PPA.
The CMM does not use or modify the value of
this argument, which gets placed in the
atm_ppa
structure
for use by the signaling module.
Identifies the type of UNI (public or private) associated with the PPA.
Identifies a piece of data that the signaling module needs
to associate with the PPA.
For UNI signaling, set this value to the UNI version
that is in use on the PPA.
The version is specified as an
atm_uni_vers_t
constant.
The
atm_cmm_new_ppa
routine is a signaling module
interface.
When a signaling module creates a new address (new PPA), the module
calls this routine.
This notifies the CMM that the new PPA exists.
A convergence
module can use the PPA to make and receive calls.
For example, when a UNI 3.0/3.1 signaling module is informed of a new address prefix, through the Interim Local Management Interface (ILMI), that has been created on the switch, the module combines the new prefix with existing end system identifiers (ESIs) to form a new set of addresses for the new prefix. Then, the signaling module tells the CMM about each of these new addresses.
Upon successful completion, the
atm_cmm_new_ppa
routine
returns a valid PPA pointer for the new PPA; otherwise, it returns NULL.
atm_cmm_del_ppa,
atm_cmm_ppa_bind,
atm_cmm_ppa_info
atm_cmm_new_thread
atm_cmm_new_thread
thread_t atm_cmm_new_thread(
task_t task,
void(*)(void * arg) *first,
void *arg,
int pri,
int maxpri
);
Specifies a pointer to a task structure used to uniquely identify the thread. The contents of this structure are filled in by this routine and should never be modified. This argument must reference a structure that will be valid for the life of the thread (generally a global structure).
Specifies the address of the routine that serves as the thread's entry point. This is the first routine called in the new thread's context. Returning from this routine terminates the thread. This routine is passed a single argument whose use is entirely thread specific.
Specifies the argument that is passed as the only argument to the thread's entry point. The use and interpretation of this argument is entirely up to the module creating and using the thread.
Specifies the priority at which the thread runs when its entry point is called. This is also the priority at which the thread always runs unless you change the priority by using one of the kernel thread management functions.
Specifies the maximum priority at which the thread is allowed to run. You cannot set the thread priority higher than this value. Note that thread priorities range from 1 (the highest) to 63 (the lowest). Set the thread priority as follows: maxpri <= newpri <= 63.
The
atm_cmm_new_thread
routine is a signaling, convergence,
and device driver module interface.
When an ATM module creates a new thread
for use by any ATM module, the module calls this routine.
This routine combines
many of the DIGITAL UNIX thread primitives to provide an easier interface
for ATM modules.
Upon successful completion, the
atm_cmm_new_thread
routine returns a pointer to a thread structure that is used to reference
the thread in all subsequent calls to kernel thread routines.
If a thread
could not be created, it returns NULL.
See Section 3.8.4 for a description of ATM thread creation.
atm_cmm_next_cause
atm_cmm_next_cause
atm_cause_info_p atm_cmm_next_cause(
atm_vc_p vp,
atm_addr_p addr,
atm_cause_info_p cip
);
Specifies a pointer to the VC from which to retrieve cause information. If you want information for only one endpoint, set the value to NULL and set the addr value to non-NULL.
Specifies a pointer to the
atm_addr
structure
for the endpoint from which to retrieve cause information.
If the error applies
to all endpoints on the VC (global), set the value to NULL and set the
vp
value to non-NULL.
Specifies the
atm_cause_info_p
value returned
by the previous call to
atm_cmm_next_cause.
To retrieve
the first cause entry for a VC or endpoint, set the value to NULL.
The
atm_cmm_next_cause
routine is a convergence and
signaling module interface that retrieves error or normal condition information
logged by previous calls to
atm_cmm_set_cause,
atm_cmm_adi_set_cause, or
atm_cmm_smi_set_cause.
To retrieve the first logged cause for a VC or endpoint, set the value
of the
cip
parameter to NULL.
To retrieve subsequent
causes, set the value of the
cip
parameter to the
value returned from the previous call to
atm_cmm_next_cause.
Upon successful completion, the
atm_cmm_next_cause
routine returns a pointer to the next
atm_cmm_next_cause
structure for the specified VC or endpoint.
If both the VC (vp) and endpoint (addr) arguments
are NULL, or if there are no more causes for the specified VC or endpoint,
the routine returns NULL.
atm_cmm_adi_set_cause,
atm_cmm_set_cause,
atm_cmm_smi_set_cause
Section 3.10.7 for information on cause information
atm_cmm_oam_receive
atm_cmm_oam_receive
void atm_cmm_oam_receive(
atm_drv_handle_t driver,
struct mbuf *mbp,
atm_vc_t *vc
);
Specifies the interface on which the operations and maintenance (OAM) cell was received. This is the driver handle that the CMM assigned at driver registration time.
Specifies a pointer to a single mbuf that contains the complete OAM cell (including the cell header). You can pass only one OAM cell to the CMM in a single call.
Specifies a pointer to the VC to which the OAM cell belongs. The CMM creates PVCs for VCs 3 and 4 for the receipt of F4 OAM flows.
The
atm_cmm_oam_receive
routine is a device driver
interface.
When an ATM device driver receives data packets and cells from
the ATM network, the driver calls this routine to pass the data to the CMM.
Device drivers should pass all OAM cells to the CMM.
atm_cmm_receive
Section 3.5.3 for information on how data are carried
atm_cmm_ppa_bind
atm_cmm_ppa_bind
atm_bind_handle_t atm_cmm_ppa_bind(
atm_ppa_p ppa,
atm_cvg_handle_t cvg_handle,
int selector,
void *const bind_handle,
atm_error_t (*const xxx_connect)(void bind_handle,
atm_addr_p addr,
atm_bind_handle_t myaddr,
atm_vc_p vc,
atm_uni_call_ie_p *reply,
atm_vc_services_p requested,
atm_vc_services_p *avail)
);
Specifies a pointer to the
atm_ppa
structure
of the PPA to which the convergence module is binding.
This is the same pointer
passed into the convergence module when it is notified of the existence of
the new PPA.
Specifies the convergence module handle returned to the convergence module when it registered with the CMM. This argument must be valid for the bind to proceed.
Specifies the selector byte that the convergence module will
use as its bind point.
This value must not already be bound to an AESA.
If
this value is
ATM_CMM_BIND_PICK, the CMM assigns the selector
value.
If the caller specifies the selector value to use, it must be in the
range of 0 to 255 (for binding to SVC PPAs) and the high-order bit must be
clear (for binding to PVC PPAs).
Specifies a value that the CMM will pass back to the convergence module when it informs the convergence module of a new call. The convergence module can use this value to identify any internal references to the bound PPA. This value has no meaning to the CMM and is not modified by the CMM.
Specifies a pointer to a routine that the CMM is to call when a new connection is being processed. If a convergence module should not receive a connection through a bind point, the value of this argument must be NULL.
The
atm_cmm_ppa_bind
routine is a convergence module
interface that binds a convergence module to a PPA.
A convergence module
must call this routine if it wants to make outgoing calls or to receive incoming
calls being made to one of the configured local ATM addresses.
The routine
informs the CMM that the convergence module will function as a network service
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 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.
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, a specific convergence module.
When binding to a PPA, a convergence module can either specify a specific selector value it wants 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 to 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.
Upon successful completion, the
atm_cmm_ppa_bind
routine returns a value that the convergence module uses to reference the
bind point; otherwise, it returns a NULL.
Typically, bind failure occurs
for the following reasons: insufficient memory, the PPA is no longer valid,
the selector value specified is in use, or there are no free selectors available.
atm_cmm_bind_info,
atm_cmm_del_ppa,
atm_cmm_new_ppa,
atm_cmm_ppa_info,
atm_cmm_ppa_unbind,
xxx_connect
Section 3.6 for information on PPAs and AESAs
atm_cmm_ppa_info
atm_cmm_ppa_info
unsigned long atm_cmm_ppa_info(
atm_ppa_p ppa,
atm_bind_info_t it
);
Specifies a pointer to the PPA for which information is to be retrieved. This can be any valid PPA currently configured on the system.
Specifies the type of information that is being queried. The value returned depends on the object type of the queried information. You may use the following values to query the indicated information:
| Value | Meaning |
ATM_PPA_ALLOCGRANE |
Returns a type of
atm_bw_granularity_p, which reflects the underlying interface's units of bandwidth allocation
or its allocation granularity. |
ATM_PPA_ALLOCLIMIT |
Returns a type of
atm_bw_granularity_p, which reflects the underlying interface's per-VC bit rate limits,
expressed in allocation granularity units. |
ATM_PPA_AVAILRES |
Returns a type of
atm_services_granes_p, which reflects the amount of bandwidth (in granularity units)
currently available for new CBR and pacing circuits over the underlying interface. |
ATM_PPA_BRESVLIM |
Returns the user-configurable limit, expressed as a percentage of backward bandwidth, on CBR circuits. |
ATM_PPA_ESI |
Returns the ESI that the signaling module supplied when the PPA was created. |
ATM_PPA_ESIID |
Returns the unique ESI identifier associated with the PPA's ESI. |
ATM_PPA_ESILEN |
Returns the length of the ESI that the signaling module supplied when the PPA was created. |
ATM_PPA_ESIPID |
Returns the ESI identifier of the PPA's parent ESI. |
ATM_PPA_FRESVLIM |
Returns the user-configurable limit, expressed as a percentage of forward bandwidth, on CBR and pacing circuits. |
ATM_PPA_INFO_BURST_AVAIL |
Returns the available burst cell rate (in cells-per-second). This is the amount of burst cell rate that is available for a convergence module to reserve. |
ATM_PPA_INFO_BURST_MAX |
Returns the maximum burst cell rate (in cells-per-second) that the interface supports. |
ATM_PPA_INFO_CAPABILITIES |
Returns the driver's capabilities for that interface. |
ATM_PPA_INFO_DID |
Returns a unique global value that can be used to reference the driver for the underlying interface. |
ATM_PPA_INFO_DNAME |
Returns a pointer to a character string that is the name of the driver for the underlying interface. |
ATM_PPA_INFO_DUNIT |
Returns the unit number of the driver for the underlying interface. |
ATM_PPA_INFO_FC |
Returns a nonzero value if hardware flow control is currently enabled on the interface. |
ATM_PPA_INFO_HARD_MTU |
Returns the largest PDU (in bytes) that the interface supports. This is valid only for interfaces that support AAL5 or AAL3/4 SAR functions in hardware. |
ATM_PPA_INFO_HI_VCI |
Returns the highest value that may be used for a VCI on the interface. |
ATM_PPA_INFO_HI_VPI |
Returns the highest value that may be used for a VPI on the interface. |
ATM_PPA_INFO_ID |
Returns a unique global value for referencing
the PPA.
Each PPA is assigned a unique ID when it is created.
An application
program can use this value when specifying a bind point (atmconfig
uses these values to reference bind points).
The returned value
is 32-bits wide. |
ATM_PPA_INFO_MAX_VCI |
Returns the maximum number of VCIs that the interface supports. |
ATM_PPA_INFO_MAX_VPI |
Returns the maximum number of VPIs that the interface supports. |
ATM_PPA_INFO_MEDIA |
Returns a value that indicates the type of
physical media to which the interface is connected.
The return value is of
the type
atm_media_type_t. |
ATM_PPA_INFO_PEAK_AVAIL |
Returns the available peak cell rate (in cells-per-second). This is the amount of peak cell rate that is available for a convergence module to reserve. |
ATM_PPA_INFO_PEAK_MAX |
Returns the maximum peak cell rate (in cells-per-second) that the interface supports. |
ATM_PPA_INFO_QUEUES |
Returns the number of scheduling queues that the driver has made visible to the CMM. |
ATM_PPA_INFO_SNAME |
Returns a pointer to a character string that contains the name of the signaling module that controls all SVCs created on the PPA. If the PPA is a PVC PPA, the returned value is NULL. |
ATM_PPA_INFO_SUST_AVAIL |
Returns the available sustainable cell rate (in cells-per-second). This is the amount of sustainable cell rate that is available for a convergence module to reserve. |
ATM_PPA_INFO_SUST_MAX |
Returns the maximum sustainable cell rate (in cells-per-second) that the interface supports. |
ATM_PPA_INFO_TOTAL_VC |
Returns the maximum number of VCs that can be opened on the interface at any given time. |
ATM_PPA_INFO_TYPE |
Returns a value that indicates the underlying
interface type.
The returned value is of the type
atm_interface_t. |
ATM_PPA_INFO_UNI |
Returns the UNI type associated with the
PPA, which the signaling module supplied at the time the PPA was created.
The return value is of the type
atm_uni_type_t. |
ATM_PPA_INFO_VC_LEFT |
Returns the number of unopened VCs on the
interface at the time of the call.
This is the total number of VCs (the value
returned by
ATM_PPA_INFO_TOTAL_VC) minus the number of
VCs currently opened. |
ATM_PPA_MAX_VC_BBW |
Returns the user-configurable maximum per-VC backward (incoming) bit rate (in allocation granularity units) permitted over the underlying interface. |
ATM_PPA_MAX_VC_FBW |
Returns the user-configurable maximum per-VC forward (outgoing) bit rate (in allocation granularity units) permitted over the underlying interface. |
ATM_PPA_MAXRES |
Returns a type of
atm_services_granes_p, which reflects the maximum bandwidths available for CBR and pacing
circuits over the underlying interface.
These bandwidths (expressed in granularity
units) are a function of the interface limits and the user-configurable limits
on the percentage of bandwidth available to CBR and pacing circuits. |
ATM_PPA_NUM_VCI |
Returns the current number of VCIs configured on the underlying interface. |
ATM_PPA_NUM_VPI |
Returns the current number of VPIs configured on the underlying interface. |
ATM_PPA_PEAK_CELLRATE |
Returns the peak PDU bit rate (in cells-per-second) for the underlying interface. |
ATM_PPA_UNUSEDRES_BACK |
Returns the amount of backward (incoming) bandwidth (in cells-per-second) currently reserved for, but not yet applied to, CBR circuits. |
ATM_PPA_UNUSEDRES_FWD |
Returns the amount of forward (outgoing) bandwidth (in cells-per-second) currently reserved for, but not yet applied to, CBR and pacing circuits. |
The
atm_cmm_ppa_info
routine is a convergence module
interface that queries the CMM for 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).
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 the PPA directly. Thus, the convergence module requires no specific knowledge of any device driver or device driver-related structures.
atm_cmm_bind_info,
atm_cmm_del_ppa,
atm_cmm_new_ppa,
atm_cmm_ppa_bind,
atm_cmm_ppa_unbind
Section 4.4.1.15
for a description of the
capabilities
member of the
atm_drv_params
structure
atm_cmm_ppa_unbind
atm_cmm_ppa_unbind
atm_error_t atm_cmm_ppa_unbind(
atm_bind_handle_t bind_handle
);
Specifies the binding to be removed.
This is the handle that
the
atm_cmm_ppa_bind
routine returns to the convergence
module.
The
atm_cmm_ppa_unbind
routine is a convergence module
interface that unbinds a convergence module's service from a PPA.
A convergence
module uses this routine when it does not want to accept an incoming connection
or to make outgoing calls, for example, a module awaiting a call from a specific
caller.
Typically, convergence modules should unbind a PPA if their service
is no longer available, and must unbind before unregistering with the CMM.
Removing a binding does not affect any currently open VCs.
Upon successful completion, the
atm_cmm_ppa_unbind
routine returns
ATM_CAUSE_GOOD; otherwise, it returns an
ATM error number.
atm_cmm_bind_info,
atm_cmm_del_ppa,
atm_cmm_new_ppa,
atm_cmm_ppa_bind,
atm_cmm_ppa_info
atm_cmm_receive
atm_cmm_receive
void atm_cmm_receive(
atm_drv_handle_t driver,
const struct mbuf *const mbp,
const int length,
const struct mbuf *const trailer,
atm_vc_t *vc,
char pti,
char gfc
);
Specifies the interface on which the data arrived. This is the driver handle that is given to the driver when it registers with the CMM.
Specifies a pointer to a chain of mbufs that contain the data received.
Specifies the total number of bytes received. For cooked data, this is the number of cells received multiplied by 48. For raw cells, this is the total number of data bytes in the mbuf chain, including the ATM cell headers but not including any time-stamps.
Specifies a pointer to the last mbuf in the mbuf chain. This enables the CMM to quickly locate the cooked packet trailer in the incoming packet without having to traverse the mbuf chain (the driver already knows the address of this mbuf because it must fill in the mbuf length after the data is copied by the adapter using DMA). For raw data, this pointer simply references the last mbuf in the chain.
Specifies a pointer to the
atm_vc
structure
of the VC on which the data was received.
Specifies the PTI field of the incoming cells.
This is driver
dependent since it is up to the hardware how it keeps track of the PTI fields
of all the cells in a packet.
The driver indicates its ability to keep track
of these bits to the CMM in the
atm_drv_params
structure
during the driver registration process.
This field is valid only for cooked
connections since complete cells are passed up when raw cells are received.
Specifies flow-control information the driver passes up to the CMM. The use of this field is not currently defined. This argument is provided for future use when GFC bits are standardized.
The
atm_cmm_receive
routine is a device driver interface.
When an ATM device driver receives data packets and cells from the ATM network,
the driver calls this routine to pass the data to the CMM.
When the CMM receives the data, it immediately passes the data to the convergence module that owns the VC. The CMM does not queue the data. That way, the convergence modules receive the data at their input functions in the interrupt context; the driver should do all receive processing in interrupt context for efficiency.
After passing data to the CMM, the driver must not reference any mbufs
in the mbuf chain again.
If the driver must allocate private storage for
data (rather than allocating from the system mbuf pool), the driver must provide
an appropriate free routine and set the
m_ext
structure
in the mbuf appropriately.
The data mbuf chain is deallocated only when the
protocol stack has finished referencing the data.
Device drivers use this call to pass up only data packets and
cells.
Device drivers must use the
atm_cmm_oam_receive
routine to pass operations and maintenance (OAM) cells (nondata cells) to
the CMM.
xxx_xmit
Section 3.5.3 for information on the mbuf chain
Section 4.2 for information on receiving cells
atm_cmm_register_cvg
atm_cmm_register_cvg
atm_cvg_handle_t atm_cmm_register_cvg(
long version,
char *const name,
void *cvg_handle,
void (*const xxx_receive)(atm_vc_p vc,
struct mbuf *mdp,
int length,
struct mbuf *trailer,
char pti,
char gfc),
atm_error_t (*const xxx_except)(void *handle,
unsigned int exception,
void *arg),
int (*const xxx_mmi)(void *handle,
unsigned int command,
void *arg,
int *retval,
struct ucred *cred)
);
Specifies the version of the include files that were used
when the convergence module driver was compiled.
The value of this argument
must match
ATM_REVISION
in the
/usr/include/io/atm/sys/atm.h
file when the convergence module was compiled.
This tells the
CMM which version of the global data structures the convergence module is
using.
Specifies a unique character string by which the convergence module is known to the system. Management programs use this string to display the name of the convergence module. This string must be unique; if the convergence module registers itself multiple times, it must use a different name for each registration.
Specifies a value that the convergence module can use to identify a specific registration to the CMM. This value is passed back to the convergence module for exception and management processing. The CMM does not modify this value, which is always passed back unchanged.
Specifies a pointer to a routine that CMM uses to notify the convergence module of incoming data. A convergence module must supply a receive routine.
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.
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.
The
atm_cmm_register_cvg
routine is a convergence
module routine that registers a convergence module with the CMM.
A protocol
convergence module must register with the CMM before it can interact with
the ATM subsystem.
The CMM passes interface configuration information (for
example, currently configured PPAs) to the convergence module, using the module's
exception 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.
The
atm_cmm_register_cvg
routine returns a unique
value that identifies an instance of the convergence module.
The convergence
module must use this value on all subsequent calls to the CMM.
atm_cmm_unregister_cvg,
xxx_except,
xxx_mmi,
xxx_receive
Chapter 8 for information on the MMI
atm_cmm_register_dd
atm_cmm_register_dd
atm_drv_handle_p atm_cmm_register_dd(
long version,
atm_drv_params_p params,
atm_error_t (*const xxx_xmit)(int unit,
struct mbuf *data,
long length,
atm_vc_p vc,
unsigned char clp,
unsigned char gfc),
atm_error_t (*const xxx_manage)(int unit,
unsigned int command,
void *arg),
int (*const xxx_mmi)(int handle,
unsigned int command,
void *arg,
int *retval,
struct ucred *cred)
);
Specifies the version of the include files that are used when
the device driver is compiled.
The value of this argument must match
ATM_REVISION
in the
/usr/include/io/atm/sys/atm.h
file when the device driver is compiled.
This tells the CMM which version
of the global data structures the driver is using.
Specifies a pointer to an
atm_drv_params
structure, which defines the basic capabilities of the interface.
This structure
must be completely initialized.
For the registration call, this pointer can
reference static memory since the CMM copies the information into its local
memory before returning.
Specifies the address of the routine for the CMM to call when it has data to transmit on the interface.
Specifies the address of a routine that the CMM calls to perform
various driver management functions.
The management function definitions
are in the
atm_adi.h
file in the
/usr/include/io/atm/sys
directory.
Specifies a pointer to a routine that the CMM calls to pass MMI commands from an application program. This routine is optional; you provide it only if the driver implements any MMI services.
The
atm_cmm_register_dd
routine is a device driver
interface that registers the device driver with the CMM.
This is done during
driver initialization, when a device driver's attach routine is called.
The
atm_cmm_register_dd
routine is called before returning from the
attach.
Upon successful completion,
atm_cmm_register_dd
returns
atm_drv_handle_t.
The driver uses this handle in all subsequent
calls to the CMM; otherwise, it returns NULL.
xxx_manage,
xxx_mmi,
xxx_xmit
Section 3.5.3 for information on the mbuf chain
Chapter 4
for more information on the device driver
interface and the
atm_queue_param
structure
Chapter 8 for more information on the MMI
atm_cmm_register_sig
atm_cmm_register_sig
atm_sig_handle_t atm_cmm_register_sig(
long version,
char *const id,
void *sig_handle,
atm_error_t (*const xxx_setup)(atm_addr_p addr,
unsigned long *refptr),
atm_error_t (*const xxx_release)(atm_addr_p addr),
atm_error_t (*const xxx_add)(atm_addr_p addr),
atm_error_t (*const xxx_drop)(atm_addr_p addr),
atm_error_t (*const xxx_enquery)(atm_addr_p addr),
atm_error_t (*const xxx_restart)(void *handle,
unsigned int class,
unsigned int vpi,
unsigned int vci),
atm_error_t (*const xxx_except)(void *handle,
unsigned int exception,
void *arg),
int (*const xxx_mmi)(void *handle,
unsigned int command,
void *arg,
int *retval,
struct ucred *cred),
atm_error_t (*const xxx_mib)(void *sig_handle,
unsigned int command,
atm_oid_p oid,
unsigned int fieldlen,
unsigned char *fieldval,
void *id)
);
Specifies the version of the include files that were used
when the signaling module was compiled.
The value of this argument must match
ATM_REVISION
in the
/usr/include/io/atm/sys/atm.h
file when the signaling module was compiled.
This tells the CMM which version
of the global data structures the signaling module is using.
Specifies a unique character string by which the protocol is known to the system. This string is used both by management programs to display the name of the switching module and by protocol convergence modules needing to use a specific protocol. For example, the UNI 3.0 switching protocol could use an ID of UNI 3.0 to identify itself. Each ID must be unique. The CMM performs signaling module lookup with case-insensitive searches, so the IDs cannot use case to differentiate themselves. Management programs display the ID strings as supplied by the signaling modules. Signaling modules that implement more than one protocol (or more than one version of the same protocol) must use multiple registration calls to register each protocol.
Specifies a value that the signaling module can use to identify a specific registration to the CMM. This value is passed back to the signaling module for exception and management processing. The CMM does not modify this value, which is always passed back unchanged.
Specifies a pointer to a routine that the CMM calls to request the creation of a new connection (make a call).
Specifies a pointer to a routine that the CMM calls to request the deletion of a connection (a hangup).
Specifies a pointer to a routine that the CMM calls to request the addition of an endpoint to a point-to-multipoint connection.
Specifies a pointer to a routine that the CMM calls to request the dropping of an endpoint to a point-to-multipoint connection.
Specifies a pointer to a routine that the CMM calls to request status for an endpoint.
Specifies a pointer to a routine that the CMM calls to request a RESTART message be sent.
Specifies a pointer to a routine that CMM uses to notify the signaling module of errors and exception conditions.
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.
Specifies a pointer to a routine that CMM uses to access fields of MIBs that the signaling modules maintain. You provide this routine only when a signaling module maintains a MIB.
The
atm_cmm_register_sig
routine is a signaling
module interface that registers a signaling module with the CMM.
Registration
must occur when the signaling module is initialized.
Once registered, the
CMM can use the signaling module and make it available to convergence modules.
Signaling modules should register as both signaling and convergence modules. When registering as a convergence module, a signaling module must set up its signaling VCs to send and receive signaling messages. The CMM does not provide special facilities for signaling VCs, but treats them like any other VC.
xxx_add,
xxx_drop,
xxx_enquery,
xxx_except,
xxx_mib,
xxx_mmi,
xxx_release,
xxx_restart,
xxx_setup
Section 7.6 for a description of signaling VC initialization
Chapter 8 for a discussion of the MMI
atm_cmm_reject
atm_cmm_reject
void atm_cmm_reject(
atm_addr_p addr
);
Specifies a pointer to the
atm_addr
structure
for the call being rejected.
This is the same pointer passed into the convergence
module's
xxx_connect
routine when the call first came in.
The
atm_cmm_reject
routine is a convergence module
interface that rejects a previously deferred incoming call and notifies the
CMM.
The incoming call was deferred when a convergence module returned
ATM_CAUSE_DEFER
from its
xxx_connect
routine.
When this call returns, the convergence module must destroy all references to the rejected call.
atm_cmm_accept,
atm_cmm_new_call
atm_cmm_release
atm_cmm_release
atm_err_t atm_cmm_release(
atm_cvg_handle_t cm,
atm_vc_t *vc
);
Specifies the value that the registration routine returns to the convergence module. This uniquely identifies the convergence module making the request.
Specifies a pointer to the VC to be torn down. This can be a point-to-point or a point-to-multipoint VC. In the case of a point-to-multipoint VC, connections to all endpoints in the multipoint connection are torn down.
The
atm_cmm_release
routine is a convergence module
routine that requests the CMM to delete a virtual circuit.
A convergence
module uses this routine when it no longer requires a connection to a remote
host.
After the routine is called, release negotiation with the remote host
is initiated, which will eventually lead to the connection being torn down
and all resources released.
A convergence module can either request that a specific endpoint be
dropped using
atm_cmm_drop
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 task simplifies the task of disconnecting
multipoint VCs and for disconnecting PVCs.
For an SVC, if the connection teardown is proceeding, the
atm_cmm_release
routine returns
ATM_CAUSE_GOOD;
otherwise, it returns an ATM error number.
As each endpoint is torn down,
the convergence module receives an
ATM_CME_EP_DEAD
exception
notification for that endpoint.
When the last endpoint associated with a
VC has been disconnected, the VC is torn down.
For a PVC, if the PVC has been destroyed on the local system, the
atm_cmm_release
routine returns
ATM_CAUSE_GOOD
and the PVC can still exist on the network; otherwise, it returns an ATM error
number.
No notifications are provided on the PVC release.
atm_cmm_reply
atm_cmm_reply
atm_err_t atm_cmm_reply(
atm_sig_handle_t sm,
atm_addr_t *addr,
atm_uni_call_ie_p ies,
unsigned int vpi,
unsigned int vci,
unsigned long call_reference
);
Specifies the signaling module's handle assigned to it when it registered with the CMM.
Specifies a pointer to an
atm_addr
structure
that contains all the parameters of the call.
This pointer must point to
the same
atm_addr
structure that was passed in the
xxx_setup
and
xxx_add
routines since this pointer
is the handle used to refer to the specific connection.
Specifies a pointer to an array of UNI signaling information
elements (or any memory array in the case of non-UNI signaling protocols).
The signaling module stores the contents of the information elements sent
in the connection reply received from the called party in the array.
The
information element array contains only those elements that do not translate
to values in the
atm_vc_services
structure.
Specifies the VPI value for the connection. The network should assign this before the routine is called.
Specifies the VCI value for the connection. The network should assign this before the routine is called.
Specifies the call reference value that the signaling module
will use when referring to this call.
This is placed in the
atm_vc
structure for future use in referencing the call.
The
atm_cmm_reply
routine is a signaling module
interface.
Signaling modules use this routine to notify the CMM when they
receive notification from the switch that an outgoing connection has been
completed.
The CMM receives signaling information elements returned by the
called party in the connection reply.
You use this call to notify the CMM
of both the completion of point-to-point connections and of the addition of
endpoints in point-to-multipoint connections.
If you are adding endpoints to a point-to-multipoint connection, the
addr
pointer will point to the
atm_addr
structure
of the added endpoint.
The call to
atm_cmm_reply
is always followed by a
call to
atm_cmm_activate_con, which notifies the CMM that
the connection is ready to carry data.
Since the
atm_cmm_reply
routine is notifying the
CMM that a previously created connection has completed, it can fail only if
the connection referenced is invalid.
In this case, it returns
ATM_CAUSE_EIR
to indicate it has no previous entry for the connection; otherwise,
it returns
ATM_CAUSE_GOOD.
If the CMM or a convergence
module needs to destroy the connection at this point it must follow the normal
teardown procedure.
If
ATM_CAUSE_EIR
is returned, the
signaling module is expected to tear down the connection.
atm_cmm_reserve_resources
atm_cmm_reserve_resources
atm_err_t atm_cmm_reserve_resources(
atm_ppa_p ppa,
atm_cvg_handle_t cm,
atm_vc_services_p s
);
Specifies the underlying driver or adapter bandwidth pool from which to allocate the resources. The underlying driver or adapter must support CBR or pacing. These resources can be applied only to point-to-point connections set up over bind points associated with the same PPA.
Specifies the value returned to the convergence module by the registration request routine. This uniquely identifies the convergence module reserving the resources.
Specifies an
atm_vc_services_p
pointing
to a properly set
atm_vc_services
structure that defines
the CBR or pacing circuit parameters.
The
atm_cmm_reserve_resources
routine is a convergence
module interface.
Convergence modules use this routine to reserve bandwidth
resources and to notify the CMM before making a call or accepting a connection.
The CMM passes the notification to the device driver and protocol convergence
module.
The
atm_cmm_reserve_resources
routine returns
ATM_CAUSE_GOOD, if the CMM was able to allocate and reserve the
necessary resources.
This routine returns
ATM_CAUSE_DEFER
if the CMM was
not able to allocate and reserve the necessary resources.
In this case, the
convergence module must wait for the
ATM_CME_RESV_AVAIL
notification exception before making a call or accepting a connection.
Until
the convergence module receives an
ATM_CME_RESV_AVAIL
notification
exception, the
atm_vc_services
structure is considered
to be a resource reservation request.
If the resource reservation fails, the
atm_cmm_reserve_resources
routine returns an ATM error number that indicates the reason for
the resource reservation failure.
If the failure is due to an incorrectly
set
atm_vc_services
structure, the
lerrstat
structure member contains local error information.
atm_cmm_restart
atm_cmm_restart
atm_err_t atm_cmm_restart(
atm_sig_handle_t sm,
unsigned int class,
unsigned int vpi,
unsigned int vci
);
Specifies the signaling module's handle returned by the CMM when the signaling module registers.
Specifies the type of restart that is being performed.
The
caller can set the value of this argument to either
ATM_RESTART_VP
(to restart all VCs on a VP) or
ATM_RESTART_VC
(to restart a specific VC).
Specifies the VC(s) to be restarted.
If
class
is set to
ATM_RESTART_VP,
vpi
specifies the VP on which all VCs are to be restarted; the
vci
argument is ignored.
If
class
is set to
ATM_RESTART_VC, the
vpi
and
vci
arguments specify which VC is to be restarted.
Specifies the VC(s) to be restarted.
If
class
is set to
ATM_RESTART_VC, the
vpi
and
vci
arguments specify which
VC is to be restarted.
The
atm_cmm_restart
routine is a signaling module
interface.
When a signaling module receives a RESTART request, the module
calls this routine to pass all of the appropriate information to the CMM.
The CMM then initiates a restart of the indicated VC(s) before returning
to the signaling module.
If the restart is successfully initiated, the
atm_cmm_restart
routine returns
ATM_CAUSE_GOOD; otherwise, it
returns an appropriate ATM error number.
atm_cmm_new_call,
atm_cmm_restart_ack
atm_cmm_restart_ack
atm_cmm_restart_ack
void atm_cmm_restart_ack(
void *handle,
unsigned int class,
unsigned int vpi,
unsigned int vci
);
Specifies the handle that the CMM uses to identify the restart. This value has significance only to the CMM. This is the value that the CMM passed to the restart function call.
Specifies the type of restart that is being performed.
The
caller can set the value of this argument to either
ATM_RESTART_VP
(to restart all VCs on a VP) or
ATM_RESTART_VC
(to restart a specific VC).
Specifies the VC(s) to be restarted.
If
class
is set to
ATM_RESTART_VP,
vpi
specifies the VP on which all VCs are to be restarted; the
vci
argument is ignored.
If
class
is set to
ATM_RESTART_VC, the
vpi
and
vci
arguments specify which VC is to be restarted.
Specifies the VC(s) to be restarted.
If
class
is set to
ATM_RESTART_VC, the
vpi
and
vci
arguments specify which
VC is to be restarted.
The
atm_cmm_restart_ack
routine is a signaling module
interface that signaling modules call to notify the CMM when a restart has
been completed.
Once notified, the CMM returns the indicated VCs to the NULL
state and frees their resources.
atm_cmm_send
atm_cmm_send
atm_err_t atm_cmm_send(
atm_cvg_handle_t cm,
atm_vc_t *vc,
const struct mbuf *const data,
const long length,
unsigned char clp,
unsigned char gfc
);
Specifies the value returned to the convergence module by the registration function call. This uniquely identifies the convergence module making the request.
Specifies a pointer to the
atm_vc
structure
of the VC on which the data is to be sent.
Specifies a pointer to a chain of mbufs that contain the data to be transmitted.
Specifies the total length of the data to be sent. For raw ATM cell transmission, this value must be a multiple of the ATM cell size. For cooked transmission, this value indicates the size of the PDU to be encapsulated and sent.
Specifies the congestion loss priority bits to be used when transmitting cooked data. When transmitting raw data, the convergence module sets these bits in each ATM cell.
Specifies the value of the generic flow-control bits to be used when transmitting the cooked data. When transmitting raw data, the convergence module sets these bits in each ATM cell.
The
atm_cmm_send
routine is a convergence module
interface that transmits data on an established virtual circuit.
The CMM
then hands 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 routine 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.
If the data is successfully passed to the driver and the driver accepts
the data, the
atm_cmm_send
routine returns
ATM_CAUSE_GOOD.
This does not indicate that the data arrived at the destination
or that it has even left the system.
If the driver does not accept the data,
an ATM error number is returned, indicating the reason the data was not accepted.
ATM_CAUSE_QFULL
indicates that the driver cannot
accept the data because its queue is full or it is out of some other resource.
The convergence module can then decide if the data should be discarded or
queued to send later.
xxx_xmit
Section 3.5.3 for more information on the mbuf chain
Chapter 10 for information on flow control in the ATM subsystem
atm_cmm_set_cause
atm_cmm_set_cause
atm_err_t atm_cmm_set_cause(
atm_cvg_handle_t cm,
atm_vc_p vp,
atm_addr_p addr,
char *reason,
atm_error_t cause,
atm_location_t location,
unsigned char diag_length,
unsigned char *diag
);
Specifies the value the registration request function call returned to the convergence module. This uniquely identifies the convergence module making the request.
Specifies a pointer to the VC on which the condition occurred. If the error applies to one endpoint, set the value to NULL and set the addr value to non-NULL.
Specifies a pointer to the
atm_addr
structure
for the endpoint on which the error occurred.
If the error applies to all
endpoints on the VC (global), set the value to NULL and set the
vp
value to non-NULL.
Specifies a NULL-terminated character string that contains descriptive text for the error.
Specifies the
atm_error_t
value that describes
the condition.
Specifies an
atm_location_t
value that
identifies the location in the network where the error occurred.
Specifies the length (in bytes) of the data in the diag argument.
Specifies a string of bytes that contains diagnostic information
about the error.
This data might be passed to the network in the
diag
field of a Cause IE.
The
atm_cmm_set_cause
routine is a convergence module
interface that records an error or normal condition associated with a VC or
endpoint.
The condition is stored as an
atm_cause_info
structure together with the VC.
Convergence and signaling modules can retrieve
this information by using the
atm_cmm_next_cause
routine.
Users can display this information by using the
atmconfig
utility.
Errors or events stored with the
atm_cmm_set_cause
routine are visible to the network and to the other end of the connection.
When a signaling module releases a connection or drops an endpoint, the module
extracts the most recent cause from a VC or endpoint and creates a Cause IE.
If the cause is recorded successfully, the
atm_cmm_set_cause
routine returns
ATM_CAUSE_GOOD.
If the driver
handle,
vp
argument, or
addr
argument is invalid, the routine returns
ATM_CAUSE_BARG.
atm_cmm_adi_set_cause,
atm_cmm_next_cause,
atm_cmm_set_log,
atm_cmm_smi_set_cause
Section 3.10.7 for information on cause information
atm_cmm_set_log
atm_cmm_set_log
atm_err_t atm_cmm_set_log(
atm_cvg_handle_t cm,
atm_vc_p vp,
atm_addr_p addr,
char *reason,
atm_error_t cause,
atm_location_t location,
unsigned char diag_length,
unsigned char *diag
);
Specifies the value the registration request function call returned to the convergence module. This uniquely identifies the convergence module making the request.
Specifies a pointer to the VC on which the condition occurred. If the error applies to one endpoint, set the value to NULL and set the addr value to non-NULL.
Specifies a pointer to the
atm_addr
structure
for the endpoint on which the error occurred.
If the error applies to all
endpoints on the VC (global), set the value to NULL and set the
vp
value to non-NULL.
Specifies a NULL-terminated character string that contains descriptive text for the error.
Specifies the
atm_error_t
value that describes
the condition.
Specifies an
atm_location_t
value that
identifies the location in the network where the error occurred.
Specifies the length (in bytes) of the data in the diag argument.
Specifies a string of bytes that contains diagnostic information
about the error.
This data might be passed to the network in the
diag
field of a Cause IE.
The
atm_cmm_set_log
routine is a convergence module
interface that records an error or normal condition associated with a VC or
endpoint.
The condition is stored as an
atm_cause_info
structure together with the VC.
Users can display this information by using
the
atmconfig
utility.
Errors or events stored with the
atm_cmm_set_log
routine are logged on the local system only, and are not available when a
signaling module generates a Cause IE.
Logging provides information about
VC or endpoint activity for a system or network administrator to view on the
local system.
If the cause is recorded successfully, the
atm_cmm_set_log
routine returns
ATM_CAUSE_GOOD.
If the handle,
vp
argument, or
addr
argument is
invalid, the routine returns
ATM_CAUSE_BARG.
atm_cmm_adi_set_log,
atm_cmm_next_cause,
atm_cmm_set_cause,
atm_cmm_smi_set_log
Section 3.10.7 for information on cause information
atm_cmm_smi_set_cause
atm_cmm_smi_set_cause
atm_err_t atm_cmm_smi_set_cause(
atm_sig_handle_t sm,
atm_vc_p vp,
atm_addr_p addr,
char *reason,
atm_error_t cause,
atm_location_t location,
unsigned char diag_length,
unsigned char *diag
);
Specifies the signaling module handle that the registration function call returned.
Specifies a pointer to the VC on which the condition occurred. If the error applies to one endpoint, set the value to NULL and set the addr value to non-NULL.
Specifies a pointer to the
atm_addr
structure
for the endpoint on which the error occurred.
If the error applies to all
endpoints on the VC (global), set the value to NULL and set the
vp
value to non-NULL.
Specifies a NULL-terminated character string that contains descriptive text for the error.
Specifies the
atm_error_t
value that describes
the condition.
Specifies an
atm_location_t
value that
identifies the location in the network where the error occurred.
Specifies the length (in bytes) of the data in the diag argument.
Specifies a string of bytes that contains diagnostic information
about the error.
This data might be passed to the network in the
diag
field of a Cause IE.
The
atm_cmm_smi_set_cause
routine is a signaling
module interface that records an error or normal condition associated with
a VC or endpoint.
The condition is stored as an
atm_cause_info
structure together with the VC.
Convergence and signaling modules can retrieve
this information by using the
atm_cmm_next_cause
routine.
Users can display this information by using the
atmconfig
utility.
Errors or events stored with the
atm_cmm_smi_set_cause
routine are visible to the network and to the other end of the connection.
When a signaling module releases a connection or drops an endpoint, the module
extracts the most recent cause from a VC or endpoint and creates a Cause IE.
If the cause is recorded successfully, the
atm_cmm_smi_set_cause
routine returns
ATM_CAUSE_GOOD.
If the driver
handle,
vp
argument, or
addr
argument is invalid, the routine returns
ATM_CAUSE_BARG.
atm_cmm_adi_set_cause,
atm_cmm_smi_set_log,
atm_cmm_next_cause,
atm_cmm_set_cause
Section 3.10.7 for information on cause information
atm_cmm_smi_set_log
atm_cmm_smi_set_log
atm_err_t atm_cmm_smi_set_log(
atm_sig_handle_t sm,
atm_vc_p vp,
atm_addr_p addr,
char *reason,
atm_error_t cause,
atm_location_t location,
unsigned char diag_length,
unsigned char *diag
);
Specifies the signaling module handle that the registration function call returned.
Specifies a pointer to the VC on which the condition occurred. If the error applies to one endpoint, set the value to NULL and set the addr value to non-NULL.
Specifies a pointer to the
atm_addr
structure
for the endpoint on which the error occurred.
If the error applies to all
endpoints on the VC (global), set the value to NULL and set the
vp
value to non-NULL.
Specifies a NULL-terminated character string that contains descriptive text for the error.
Specifies the
atm_error_t
value that describes
the condition.
Specifies an
atm_location_t
value that
identifies the location in the network where the error occurred.
Specifies the length (in bytes) of the data in the diag argument.
Specifies a string of bytes that contains diagnostic information
about the error.
This data might be passed to the network in the
diag
field of a Cause IE.
The
atm_cmm_smi_set_log
routine is a signaling module
interface that records an error or normal condition associated with a VC or
endpoint.
The condition is stored as an
atm_cause_info
structure together with the VC.
Users can display this information by using
the
atmconfig
utility.
Errors or events stored with the
atm_cmm_smi_set_log
routine are logged on the local system only, and are not available when a
signaling module generates a Cause IE.
Logging provides information about
VC or endpoint activity for a system or network administrator to view on the
local system.
If the cause is recorded successfully, the
atm_cmm_smi_set_log
routine returns
ATM_CAUSE_GOOD.
If the handle,
vp
argument, or
addr
argument is
invalid, the routine returns
ATM_CAUSE_BARG.
atm_cmm_adi_set_log,
atm_cmm_next_cause,
atm_cmm_set_log,
atm_cmm_smi_set_cause
Section 3.10.7 for information on cause information
atm_cmm_status_done
atm_cmm_status_done
void atm_cmm_status_done(
atm_addr_p addr
);
Specifies a pointer to the
atm_addr
structure,
indicating the endpoint from which the enquiry response was received.
This
should correspond to the endpoint provided to the signaling module's enquiry
function call.
The
atm_cmm_status_done
routine is a signaling module
interface that signaling modules call to notify the CMM when a status enquiry
has completed.
Once notified, the CMM either examines the enquiry data itself
or passes it to the convergence module that requested the enquiry.
atm_cmm_unregister_cvg
atm_cmm_unregister_cvg
atm_error_t atm_cmm_unregister_cvg(
atm_cvg_handle_t cm
);
Specifies a value that identifies the convergence module.
The
atm_cmm_register_cvg
call returns this value.
The
atm_cmm_unregister_cvg
routine is a convergence
module interface that unregisters a convergence module with the CMM.
A convergence
module unregisters with the CMM if it no longer needs to receive or make connections.
This might be necessary in environments when protocol stacks are dynamically
configured and unconfigured 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 connection routine. The CMM will continue to call the convergence module with incoming data and exception notifications. Once the convergence module is unregistered, the CMM does not call any of its routines.
If the convergence module is completely unregistered and the CMM will
make no more calls to its routines, the
atm_cmm_unregister_cvg
routine returns
ATM_CAUSE_GOOD.
If there are still connections
associated with the convergence module, it returns
ATM_CAUSE_BUSY.
This means the module's
xxx_connect
routine
is unregistered, but the CMM will continue to deliver data and exception notifications.
Once the convergence module unregisters, the CMM will not accept any more
connection requests from the module until it reregisters.
The convergence
module must make the unregister call again once all existing connections are
closed.
atm_cmm_vc_control
atm_cmm_vc_control
atm_err_t atm_cmm_vc_control(
atm_cvg_handle_t cm,
atm_vc_t *vc,
int operation,
void *arg
);
Specifies the value returned to the convergence module by the registration function call. This uniquely identifies the convergence module making the request.
Specifies the VC to which the function call applies.
Specifies the type of operation to be performed on the VC.
Specifies further data for the operations. The type and use of this argument depends on the type of operation being performed. The following are valid operations:
| Operation | Meaning |
ATM_VCC_AGING |
Changes the circuit-aging algorithm applied
to the VC.
For this operation,
arg
is an
int
whose value is the new aging parameter (see Table 7-1 for a
list of values). |
ATM_VCC_QPARAM |
Sets the queuing parameters for queuing raw
cells in the driver.
The argument to this operation is an
atm_queue_param_p
that points to a properly set
atm_queue_param
structure.
This structure is referenced only within the context of the function
call and may be a local variable in the calling function. |
The
atm_cmm_vc_control
routine is a convergence
module interface that enables convergence modules to modify virtual circuit
parameters, either to make the transfer of data more efficient or to control
the VC aging.
The QOS and circuit bandwidth parameters cannot be modified.
Upon successful completion, the
atm_cmm_vc_control
routine returns
ATM_CAUSE_GOOD; otherwise, it returns an
ATM error number.
Section 4.4.2
for information on the
atm_queue_param
structure
Section 7.3 for information on connection aging
atm_cmm_vc_get
atm_cmm_vc_get
atm_vc_p atm_cmm_vc_get(
atm_drv_handle_t driver,
unsigned int vpi,
unsigned int vci
);
Specifies the device driver handle for the PPA to which the VC being queried is attached.
Specifies the VPI values for the VC.
Specifies the VCI values for the VC.
The
atm_cmm_vc_get
routine is a signaling module
interface.
When a signaling module needs to access status information about
a VC that is currently in service, based on the VPI and VCI, the module calls
this routine.
If the VC is currently configured on the system, the
atm_cmm_vc_get
routine returns a pointer to that
atm_vc
structure;
otherwise, it returns NULL.
atm_cmm_status_done,
atm_cmm_vc_stats
atm_cmm_vc_stats
atm_cmm_vc_stats
atm_error_t atm_cmm_vc_stats(
atm_vc_p vc,
atm_vc_stats_p stats
);
Specifies a pointer to the VC for which statistics are to be reported.
Specifies a pointer to an
atm_vc_stats
structure allocated by the caller into which the CMM can copy the statistics.
The
atm_cmm_vc_stats
routine is a convergence module
interface that retrieves VC statistics from the CMM.
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.
No entity can reset the VC counters. If a convergence module needs to collect statistics between two events, it must query the statistics at the first event and the second event and subtract the first event's statistics from the second event's statistics.
Upon successful completion, the
atm_cmm_vc_stats
routine returns
ATM_CAUSE_GOOD; otherwise, it returns an
ATM error.
atm_cmm_vc_control,
atm_cmm_vc_get
xxx_add
xxx_add
atm_error_t xxx_add(
atm_addr_p addr
);
Specifies a pointer to the
atm_addr
structure
for the endpoint to be added.
The
xxx_add
routine is a routine declared within
a signaling module that the CMM calls when it needs to add an endpoint to
a point-to-multipoint connection.
The name of the routine (xxx_add) can be any valid C language function name.
You pass the routine
to the CMM by reference only.
The signaling module can obtain the information about the root's VC
by following the
addr->vc
pointer.
This routine is nonblocking.
The CMM is notified when the connection has been added.
The
xxx_add
routine must return
ATM_CAUSE_GOOD
if the signaling module is proceeding with the endpoint addition
or an ATM error number if the call cannot proceed.
xxx_connect
xxx_connect
atm_error_t xxx_connect(
void *bind_handle,
atm_addr_p addr,
atm_bind_handle_t myaddr,
atm_vc_p vc,
atm_uni_call_ie_p *reply,
atm_vc_services_p requested,
atm_vc_services_p *avail
);
Specifies the PPA binding being used. It is the value passed to the CMM when the convergence module requested a PPA bind on which the call is being processed.
Specifies a pointer to the
atm_addr
structure,
indicating the endpoint that is initiating the connection.
Specifies the bind identifier for the bind point on which
the call arrived.
This is the value the CMM returns when the convergence module
calls
atm_cmm_ppa_bind.
Specifies a pointer to the VC of the new connection.
Specifies a pointer to an
atm_uni_call_ie
structure in which the convergence module writes the address of an information
elements array to be used in composing the reply to the calling party.
If
no reply is necessary, the convergence module can ignore this argument.
Specifies a pointer to an
atm_vc_services
structure that contains information to pass to the convergence module about
the network resources required to establish the new connection.
Specifies a pointer to an
atm_vc_services
structure that contains information about the network resources available
to be committed to the new connection.
If the avail argument is NULL, the convergence module cannot negotiate service structure parameters; it can only accept or reject the call. If the avail argument is not NULL, the convergence module must evaluate the structure's contents to obtain more information about the incoming call.
For non-CBR circuits, the
avail
argument
is the same as the
requested
argument.
The convergence
module can change negotiable parameters by modifying the appropriate fields
in the
atm_vc_services
structure referenced by
avail.
In UNI 3.1, no circuit parameters can be modified.
Forward
and backward MTU sizes may be negotiable through the
atm_uni_call_ie
structure.
For CBR circuits, the value of avail depends on whether or not the CMM was able to allocate the bandwidth resources necessary to establish a new CBR connection.
If
avail
is NULL, the CMM was not able to
allocate bandwidth resources.
The convergence module can use the information
provided in the
requested
argument to determine
the resources needed to establish the connection, and can apply reserved resources
to the call.
You do this by setting
avail
to the
address of an
atm_vc_services_t
structure that has been
backed by the appropriate resources.
The supplied reserved resource bit rates
need not match the requested resource bit rates exactly.
The forward (local
system transmit) rate can be less than or equal to the requested rate (so
as not to exceed the contract already established with the network).
The backward
(local system receive) rate can be greater than or equal to the requested
rate (to ensure that the local system can receive at least as much as the
sender contracted to send).
The convergence module can impose exact bit-rate matching, if necessary.
The convergence module can change negotiable parameters by changing
avail, as for non-CBR circuits.
If the supplied reserved resource
cannot be applied to the call, the convergence module receives an
ATM_CME_EP_DEAD
exception notification; the VC cause information
indicates the reason for the failure.
For CBR circuits, if the avail argument is not NULL, the CMM was able to allocate the bandwidth resources necessary to establish a CBR connection. The convergence module can change negotiable parameters, as with non-CBR circuits. The convergence module also has the option of replacing the CMM-allocated resources with reserved resources held by the convergence module by setting avail to the address of the reserved resources services structure. Restrictions on bit-rate matching still apply.
The
xxx_connect
routine is a function declared within
a convergence module that the CMM calls to notify the convergence module of
a connection request.
The CMM calls the convergence module that is bound
to the selector specified in the called party address.
The name of the routine (xxx_connect) can be any
valid C language function name.
The routine is passed to the CMM by reference
only.
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 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; the VC's ownership cannot be changed. The convergence module VC is notified of all incoming data on the VC and exceptions on the VC. Also, the convergence module is the only module that can transmit data on the VC.
You use this routine for both point-to-point and point-to-multipoint connections.
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, modules could be layered 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.
PVCs created by the
atmconfig
utility must have a
convergence module specified since it is not possible for convergence modules
to determine if they should accept a PVC call.
When the
atmconfig
utility creates a new PVC, the
convergence module to which it belongs receives the connection notification.
For PVCs, the
myaddr
argument points to the PVC
PPA, the
vc
argument references the new
atm_vc
structure, and the
requested
argument
references the new PVCs circuit parameters.
The
addr,
reply, and
avail
arguments are NULL.
Convergence modules cannot change or reject PVC circuit parameters; the system
does not create the PVC unless it can provide the requested level of service
as specified by the creator of the PVC.
When a convergence module accepts a connection, it can assume that the
connection exists and that it will receive notifications if the connection
is destroyed.
It is free to use its private structure members in the
atm_vc
structure referenced in the
atm_addr
structure.
When a connection is accepted, it is not yet ready to carry data. The convergence module must not attempt to transmit data until it is notified that the connection is active. However, it should be ready to receive data since data can arrive ahead of the activation notification.
See
Section B.3
for a code example of the
xxx_connect
routine.
In the example,
new_connect
is the name of the routine.
If the convergence module accepts the connection, it should return
ATM_CAUSE_GOOD.
If the convergence module cannot immediately accept
the connection (for example, if negotiation is needed with upper-level protocols
or a user-level process), it must not block; it should return
ATM_CAUSE_DEFER.
Returning
ATM_CAUSE_DEFER
causes no immediate
action to be taken on the connection since the ATM protocols allow some time
for the called party to reply.
When the convergence module makes a determination
about the disposition of the call, it must communicate this to the CMM by
using either the
atm_cmm_accept
or
atm_cmm_reject
calls.
If the convergence module rejects the call, it must return
an ATM error number other than
ATM_CAUSE_GOOD
or
ATM_CAUSE_DEFER.
atm_cmm_accept,
atm_cmm_ppa_bind,
atm_cmm_reject
xxx_drop
xxx_drop
atm_error_t xxx_drop(
atm_addr_p addr
);
Specifies a pointer to the
atm_addr
structure
for the endpoint to be dropped.
The
xxx_drop
routine is a function declared within
a signaling module that the CMM calls when it needs to drop an endpoint on
a point-to-multipoint connection.
The name of the routine (xxx_drop) can be any valid C language function name.
The routine is passed
to the CMM by reference only.
The signaling module can obtain the information about the root's VC
by following the
addr->vc
pointer.
This function call
is nonblocking.
The CMM is notified when the connection has been dropped.
The
xxx_drop
routine must return
ATM_CAUSE_GOOD
if the signaling module is proceeding with the endpoint drop or
an ATM error number if the call cannot proceed.
xxx_enquery
xxx_enquery
atm_error_t xxx_enquery(
atm_addr_p addr
);
Specifies a pointer to the
atm_addr
structure
for the endpoint to be queried.
The
xxx_enquery
routine is a function declared within
a signaling module that the CMM calls when it needs status for an endpoint.
The name of the routine (xxx_enquery) can be any valid
C language function name.
You pass the routine to the CMM by reference only.
This routine is nonblocking. When the query response arrives, the signaling module uses a function call to notify the CMM.
The
xxx_enquery
routine must return
ATM_CAUSE_GOOD
if the signaling module is proceeding with the enquiry or an ATM
error number if the call cannot proceed.
xxx_except
xxx_except
int xxx_except(
void *handle,
unsigned int exception,
void *arg
);
Specifies an identifier that the module passed to the CMM when the module registered. For convergence and signaling modules, this is the internal handle the module registers with the CMM. This value is meaningful only to the called module.
Specifies a value that identifies the type of exception that occurred. The following table contains a list of valid values:
| Exception | Meaning |
ATM_CME_BIND_DEL |
Informs the convergence module that one of
its bindings is being destroyed.
The usual reason for this is that a PPA
is being destroyed either because its address is no longer registered with
the network or because the interface to the network has gone down.
The argument
to this exception is the value returned from the
atm_cmm_ppa_bind
call (atm_bind_handle_t); the convergence module
uses this value to reference the bind point.
The return value from this call
is ignored. |
ATM_CME_CALL_FAILED |
Indicates that a call to an endpoint
has failed.
The argument is an
The convergence module must destroy all references to the endpoint when processing this notification. The convergence module receives one additional notification to destroy all its references to the endpoint's VC if this was the only endpoint associated with a VC. |
ATM_CME_DELPVC |
Informs the convergence module that a PVC
has been deleted from the system.
Convergence modules receive one of these
exceptions for each PVC that is deleted, even PVCs that they delete.
The
argument for this command is an
atm_vc_p
to the PVC being
deleted.
When this notification is received, convergence modules must destroy
all references to the PVC and must not send any more data on it. |
ATM_CME_DVR_DOWN |
Informs the convergence module that a driver
is down, and any unused reserved resource or outstanding reservation request
is revoked.
The convergence module should remove knowledge of the reserved
resource or outstanding reservation request services structure indicated by
the
atm_vc_services_p
argument.
The convergence module
should not free the
atm_vc_services
structure; the CMM
does this upon return from the exception notification.
If the convergence
module attempts to free the structure,
ATM_CAUSE_BUSY
is
returned. |
ATM_CME_ENQUERY_DONE |
Informs the convergence module that a requested
connection state enquiry function on an endpoint has completed.
The argument
is an
atm_addr_p
for the endpoint that was queried.
The
state information in the
atm_addr
structure indicates if
the enquiry succeeded and the current endpoint state. |
ATM_CME_EP_ACTIVE |
Informs the convergence module that an endpoint is now active and available for transferring data. This notification is usually the result of receiving a connection complete from the signaling module. When the convergence module requests a new connection or receives notification of a new connection, the connection is not yet ready to carry data. Only after the connection setup is complete (requiring several message exchanges between connection endpoints) will it be able to carry data. This command tells the convergence module that the connection is complete
and ready to carry data.
Use this notification for both point-to-point and
point-to-multipoint notifications.
The command argument is an
|
ATM_CME_EP_DEAD |
Informs the convergence module that the connection to an endpoint has been destroyed and that all resources allocated for the endpoint should be freed. This is the only notification the convergence module will receive. After receiving this notification, it is illegal for the convergence module to reference the endpoint. The command
argument is an
|
ATM_CME_ESI_DEL |
Informs the convergence module that an ESI
it had created has been removed from the system.
The CMM notifies the convergence
module separately to destroy any PPAs created from the ESI.
The argument is
the value (arg) that the convergence module passed
in to the
atm_cmm_new_esi
call.
When this notification
is received, convergence modules should destroy all references to the deleted
ESI. |
ATM_CME_PPA_ADD |
Informs the convergence module that a new
PPA has been configured and is available for connections.
The argument is
a pointer to the
atm_ppa
structure for the new PPA.
If
the convergence module needs to receive calls on this new PPA it must perform
an
atm_cmm_ppa_bind
function call for the new PPA. |
ATM_CME_PPA_DEL |
Informs the convergence module that a PPA
has been removed from the system.
The CMM notifies the convergence module
separately to destroy all VCs associated with the PPA.
The argument for this
command is a pointer to the
atm_ppa
structure for the PPA
that is being deleted.
When this notification is received, convergence modules
should destroy all references to the deleted PPA. |
ATM_CME_RESV_AVAIL |
Informs the convergence module that an outstanding
request for a reserved resource has been satisfied.
The
atm_vc_services
structure indicated by the
atm_vc_services_p
argument is now a services structure that is backed by resources, or a reserved
resource.
The convergence module must apply this services structure to an
outgoing or incoming call within the system-specified amount of time to avoid
having the resources revoked by an
ATM_CME_RESV_EXPIRE
exception notification. |
ATM_CME_RESV_EXPIRE |
Informs the convergence module that a reserved
resource has not been used in the system-specified amount of time and is revoked.
The convergence module should remove knowledge of the reserved resource services
structure indicated by the
atm_vc_services_p
argument.
The convergence module should not free the
atm_vc_services
structure; the CMM does this upon return from the exception notification.
If the convergence module attempts to free the structure,
ATM_CAUSE_BUSY
is returned. |
ATM_CME_RESVREQ_REL |
Informs the convergence module that an outstanding
request for a reserved resource has been canceled.
This exception is generated
by a change in configuration parameters that causes the contents of the
atm_vc_services
structure (which were valid at the time of the request)
to no longer be valid.
For example, this event could occur if the system
administrator reduced the per-VC bandwidth limit to values below the rates
specified in the reservation request.
The convergence module should remove
knowledge of the reservation request services structure indicated by the
atm_vc_services_p
argument.
The convergence module should not free
the services structure; the CMM does this upon return from the exception notification.
If the convergence module attempts to free the structure,
ATM_CAUSE_BUSY
is returned. |
ATM_CME_START_VC |
Informs the convergence module that a VC
on which flow was previously controlled may now resume transmission of data.
The argument to this command is a pointer to the
atm_vc
structure of the VC that can resume data transmission. |
ATM_CME_VC_OLD |
Informs a convergence module that a VC has aged (been inactive for a long period of time) and that the CMM is about to delete it. In this situation, the convergence module is given the chance to stop the CMM from destroying the VC. When the VC is about to be destroyed because of inactivity, this notification is made to the convergence module. The argument is an
|
ATM_SIGE_ACCEPT |
Specifies that an incoming call whose disposition
was previously deferred has been accepted.
The signaling modules should take
appropriate action to accept the call and activate the connection.
The argument
to this exception is an
atm_addr_p
that references the
call that is being accepted. |
ATM_SIGE_DEL_ESI |
Informs the signaling module of a user- or
convergence module-initiated deletion of an ESI (or similar) part of an address.
The signaling module then performs the deletion of every PPA associated with
the ESI through protocol exchanges with the switch.
As each PPA is deleted,
the signaling module uses the
atm_cmm_del_ppa
function
call to notify the CMM.
The arguments and returns are the same as for the
ATM_SIGE_NEW_ESI
exception. |
ATM_SIGE_DEL_PPA |
Informs the signaling module of a user-initiated
deletion of a PPA.
The signaling module then performs the deletion of the
PPA through protocol exchanges with the switch.
The argument for this exception
is a pointer to the
atm_ppa
structure of the PPA being
deleted.
If the signaling module returns
ATM_CAUSE_GOOD,
the CMM considers the PPA deleted (even though the protocol exchange with
the switch may not be complete).
It then initiates the deletion of all VCs
and bind points associated with the PPA. |
ATM_SIGE_NEW_ESI |
Informs the signaling module that a
user- or convergence module-initiated creation of a new ESI (or similar address
part) has been configured on the system.
The argument for this exception
is a pointer to an
When a signaling module receives this exception, it should initiate creation
of new PPAs based on the new ESI, notifying the CMM of each new PPA created.
This exception should return
When
a new driver is brought on line, the CMM notifies the signaling module of
every ESI that the driver reports from its ROM.
This enables the system to
automatically configure addresses based on adapter ROM values (if any).
Note
that even though signaling modules have access to device driver's ROM ESI
addresses from the driver's
|
ATM_SIGE_REJECT |
Specifies that an incoming call whose disposition
was previously deferred has been rejected.
The signaling modules should take
appropriate action to reject the call.
The argument to this exception is
an
atm_addr_p
that references the call that is being rejected. |
Specifies an additional argument whose interpretation depends on the exception value.
The
xxx_except
routine is a function declared within
a convergence or signaling module that the CMM calls to report exceptions,
errors, and system configuration changes on a VC.
The name of the routine (xxx_except) can be any valid
C language function name.
You pass the routine to the CMM by reference only.
Exception notifications have the following characteristics:
Convergence and signaling modules can expect them at any time.
They are delivered in an interrupt context.
Exception processing must not block. If a convergence or signaling module needs to defer processing an exception notification, it must arrange for a kernel thread to be run at a later time and to return immediately to the CMM.
If a command has no explicit return value specified, it always returns
ATM_CAUSE_GOOD; otherwise, it returns one of the specified values.
atm_cmm_register_cvg,
atm_cmm_register_sig
Section 7.3 for information on connection aging
Chapter 10 for more information on flow control in the ATM subsystem
xxx_manage
xxx_manage
atm_error_t xxx_manage(
int unit,
unsigned int command,
void *arg
);
Specifies the unit number to which the command applies.
Specifies the type of management function to perform. The following management functions are defined:
| Function | Definition |
ATM_DRVMGMT_ADDVC |
Instructs the driver to create a new
VC.
The
arg
argument is a pointer to the
If the driver has insufficient resources to meet the QOS specified
for the VC, it must return a value other than
|
ATM_DRVMGMT_CLEARQ |
Clears the QOS parameters from a driver queue. The CMM issues this command after the last VC has been detached from a queue to indicate to the driver that the queue no longer requires servicing. |
ATM_DRVMGMT_DELVC |
Instructs the driver to reclaim all resources
associated with a VC and to destroy any references to the VC.
This call cannot
block.
The
arg
argument is a pointer to the
atm_vc
structure for the VC to be deleted.
The driver must free
all local resources for the VC and set
vc->drv_pp1
and
vc->drvpp2
to 0 prior to returning.
|
ATM_DRVMGMT_DOWN |
Instructs the interface to shut down and to stop exchanging data with the switch. This call cannot block. This call need only start the driver shutdown procedure. When the shutdown is complete, the driver must notify the CMM by using the CMM driver error interface. The CMM takes care of VC deallocation; the driver can expect to be called to deallocate local resources for each open VC. Do not use the arg argument. |
ATM_DRVMGMT_ENBVC |
Instructs the driver to enable the VC for
sending and receiving data.
This call cannot block.
The
arg
argument is a pointer to the
atm_vc
structure,
which identifies the VPI and VCI values to be activated.
This call is made
only after a VC is set up on the network and becomes active and only after
the
ATM_DRVMGMT_ADDVC
command, never before it. |
ATM_DRVMGMT_FC |
Enables the types of flow control that the
driver uses.
The following values are supported:
ATM_FLOW_NONE
(disables all flow control);
ATM_FLOW_STD
(enables ATM
Forum standard flow control); and
ATM_FLOW_VENDOR
(enables
vendor-specific flow control).
ATM_FLOW_NONE
is the default
state for the driver.
Flow control is enabled or disabled globally rather
than on a per-VC basis.
|
ATM_DRVMGMT_MAXVCI |
Specifies the maximum VCI value for any VC
on the driver.
The
arg
argument is the maximum
VCI value (0<=
VCI
<=
maxvci).
This value must be less than the
max_vci
member of the
atm_drv_params
structure.
The CMM uses this when it detects that
the connect switch supports fewer VCIs than the driver. |
ATM_DRVMGMT_MAXVPI |
Specifies the maximum VPI value for any VC
on the driver.
The
arg
argument is the maximum
VPI value (0<=
VPI
<=
maxvpi).
This value must be less than the
max_vpi
member of the
atm_drv_params
structure.
The CMM uses this when it detects that
the connect switch supports fewer VPIs than the driver. |
ATM_DRVMGMT_QUERY |
Queries the driver for its current available
resources.
This call cannot block.
The
arg
argument
is a pointer to an
atm_drv_params
structure in which to
write the information.
The driver does not write the
num_id
member or the
ids
array.
The values written should be
the maximum allowable values for each resource minus the resources currently
in use.
The CMM uses this call to synchronize its current driver state information
with the driver's internal state.
The driver's internal state is always assumed
to be correct.
|
ATM_DRVMGMT_RAWPARAM |
Controls queuing of raw cells (not used for
cooked connections).
This command sets parameters that the driver uses to
queue incoming raw cells into one mbuf chain rather than passing each cell
up to the CMM.
This reduces the cell-processing overhead when receiving raw
cells.
The argument is a pointer to the
atm_queue_param
structure. |
ATM_DRVMGMT_SETQ |
Specifies QOS parameters of a driver's transmit
queue.
Only drivers that have informed the CMM that they implement multiple
queues can expect this command.
The CMM issues this command before any VCs
are attached to a specific queue.
The argument is a pointer to an
atm_vc_services
structure that holds the queue parameters.
The
CMM can issue this command at any time to change the parameters of a queue.
|
ATM_DRVMGMT_UP |
Instructs the interface to initialize and
come on line.
This call cannot block.
This call need only start a driver
initialization function.
When the initialization is complete and the driver
is ready to create VCs, it must use the
atm_cmm_error
routine
to notify the CMM.
|
Specifies any data needed to perform the function.
The
xxx_manage
routine is a function declared within
a device driver module that the CMM calls when it needs to perform some driver
management task.
The name of the routine (xxx_manage)
can be any valid C language function name.
You pass the routine to the CMM
by reference only.
If the
xxx_manage
routine is completed successfully,
the driver returns
ATM_CAUSE_GOOD; otherwise, the driver
returns an ATM error number indicating the cause of the failure.
atm_cmm_error,
atm_cmm_register_dd
xxx_mib
xxx_mib
atm_error_t xxx_mib(
void *sig_handle,
unsigned int command,
atm_oid_p oid,
unsigned int fieldlen,
unsigned char *fieldval,
void id
);
Specifies the signaling module's internal handle that it provides to the CMM in the registration call.
Specifies the command to get or set a field in the MIB.
Valid
values are
ATM_MIB_GET
and
ATM_MIB_SET,
used to get and set a field in the MIB, respectively.
Specifies an
atm_oid
structure that identifies
the object (and object instance) to retrieve from the MIB.
Specifies the length of the data being provided on an
ATM_MIB_SET
and is ignored on an
ATM_MIB_GET.
Specifies a pointer to the value to be set in the indicated
MIB field on an
ATM_MIB_SET
and is NULL on an
ATM_MIB_GET.
Specifies a value that the CMM uses to identify the specific MIB request. The CMM uses this when querying a MIB value from one signaling module while sending a request to another network management entity.
The
xxx_mib
routine is a function declared within
a signaling module that the CMM calls to access fields of MIBs maintained
by the signaling module.
This routine is provided only when a signaling module
maintains a MIB.
The values of MIB fields are returned through a call to
atm_cmm_mib_response.
The name of the routine (xxx_mib) can be any valid
C language function name.
You pass the routine to the CMM by reference only.
The
xxx_mib
function call cannot block.
If the value is available immediately,
atm_cmm_mib_response
is called from within the signaling module's
xxx_mib
routine and
ATM_CAUSE_GOOD
is returned.
If the MIB value
must be queried,
ATM_CAUSE_DEFER
must be returned and
atm_cmm_mib_response
called when the query is complete and the value
is available.
If a MIB set operation cannot be completed immediately, the
signaling module must return
ATM_CAUSE_DEFER
and call
atm_cmm_mib_response
when the access has been completed.
An error
is indicated by returning the appropriate ATM error number.
atm_cmm_register_sig
Section 5.17
for a description of the
atm_oid
structure
xxx_mmi
xxx_mmi
int xxx_mmi(
void *handle,
unsigned int command,
void *arg,
int *retval,
struct ucred *cred
);
Specifies an identifier that the module passed to the CMM when the module registered. For device drivers, this is a unit number. For convergence and signaling modules, this is the internal handle that the module provides to the CMM. This value is meaningful only to the called module.
Specifies what action the MMI routine is to perform.
The
format of the command is the same as that of ATM
ioctl
commands as defined in the
/usr/include/sys/atm.h
file.
Commands for non-CMM ATM modules are defined using the IOW (I/O write) or
equivalent macros.
All commands have a type of "g" and a value
of between 128 and 255 inclusive.
Specifies a command-specific argument that is interpreted
by the management function based on the value of
cmd.
The
format of the data referenced by this argument can be anything that is valid
for
ioctl
calls.
Specifies a pointer to an integer into which the MMI routine
writes a return value when returning
ESUCCESS
to the CMM.
This argument is optional.
Specifies the credentials or access information passed by
the system to the CMM in the
ioctl
call.
The
xxx_mmi
routine is a function declared within
a convergence, device driver, or signaling module that the CMM calls to pass
management and configuration requests from applications through the CMM and
the MMI interface.
The name of the routine (xxx_mmi) can be any valid
C language function name.
You pass the routine to the CMM by reference only.
The
xxx_mmi
routine is called from within a system
call context with no external locks held.
It has access to the per-process
data structures and user address space of the calling process.
If necessary,
the
xxx_mmi
routine can block as long as it does not hold
simple locks while blocking.
If a module does not require any external management or configuration capabilities, it does not have to register a management function with the CMM.
This interface 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 the operation completes successfully, the
xxx_mmi
routine returns
ESUCCESS; otherwise, it returns a DIGITAL UNIX
error number as defined in
sys/errno.h.
In addition, for
successful completions modules can use the
retval
pointer to pass the return value from the
ioctl
system
call to the calling program.
atm_cmm_register_cvg,
atm_cmm_register_dd,
atm_cmm_register_sig
Chapter 8
for information on MMI and
ioctl
calls
xxx_receive
xxx_receive
void xxx_receive(
atm_vc_t *vc,
struct mbuf *mbp,
int length,
struct mbuf *trailer,
char pti,
char gfc
);
Specifies a pointer to the
atm_vc
structure
on which the data arrived.
The module being called already owns the VC, so
this is used as a handle for the module to identify on which (of many) VCs
the data arrived.
The convergence module may use its two private structure
members in the
atm_vc
structure to place local information
necessary for managing the connection.
Specifies a pointer to a list of mbufs that contain the data received.
Specifies a value that indicates the exact number of bytes received. For cooked packets, this is the size of the received packet or protocol data unit (PDU) plus the padding and AAL trailer. It is always a multiple of 48. For raw data, this value is a multiple of the number of cells received. It is a multiple of 53 bytes (time-stamp bytes are not included in the count).
Specifies a pointer to the mbuf that contains the last byte of the received data. This permits the convergence module to easily and quickly locate the AAL trailer for obtaining the PDU length and other information (such as user-to-user indications). When receiving raw cells, this argument points to the mbuf that contains the last cell in the chain.
Specifies the accumulated PTI information of a received cooked
packet.
The availability of this information is dependent on the driver's
ability to keep track of all the PTI fields in all the cells that compose
a cooked packet.
The convergence module can determine if this argument is
valid by examining the
capabilities
structure member in
the device driver's
atm_drv_params
structure.
This argument
has no meaning for raw data.
Specifies the accumulated GFC information from the cells that
make up a cooked packet.
The availability of this information is dependent
on the driver's ability to keep track of all the GFC fields in all the cells
that compose a cooked packet.
The convergence module can determine if this
argument is valid by examining the
capabilities
structure
member in the device driver's
atm_drv_params
structure.
This argument has no meaning for raw data.
The
xxx_receive
routine is a function declared within
a convergence module that the CMM calls to pass data to a convergence module.
The name of the routine (xxx_receive) can be any valid
C language function name.
You pass the routine to the CMM by reference only.
When designing receive routines, convergence module writers 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 need to do some processing before
queuing the data and returning to the CMM.
In either case, the receive routine
must not block.
atm_cmm_register_cvg
Section 3.5 for a description of ATM data formats
Chapter 4 and Chapter 6 for information on device drivers and convergence modules, respectively
xxx_release
xxx_release
atm_error_t xxx_release(
atm_addr_p addr
);
Specifies the pointer to the
atm_addr
structure.
The
xxx_release
routine is a function declared within
a signaling module that the CMM calls when it needs a connection torn down
(a hangup).
The name of the routine (xxx_release) can
be any valid C language function name.
You pass the routine to the CMM by
reference only.
When the CMM makes the call, the signaling protocol module should initiate a release of the connection to the specified endpoint. This routine is nonblocking, and is used only for releasing a point-to-point connection or the root of a point-to-multipoint connection (when all leaf connections have been released).
The
xxx_release
routine must return
ATM_CAUSE_GOOD
if the circuit deletion is completed or an ATM error number if
the circuit deletion fails.
xxx_restart
xxx_restart
atm_error_t xxx_restart(
void *handle,
unsigned int class,
unsigned int vpi,
unsigned int vci
);
Specifies a unique identifier that the CMM uses to identify the restart request. This has meaning only to the CMM and should not be modified by the signaling module.
Specifies the type of restart that is being performed.
Currently,
only restarting of individual VCs or all VCs in a VP are supported.
The caller
sets the value of this argument to
ATM_RESTART_VP
to restart
all VCs on a VP or
ATM_RESTART_VC
to restart a specific
VC.
These are the only two values permitted for this argument.
Specifies which VC(s) are to be restarted.
If
class
is set to
ATM_RESTART_VP,
vpi
specifies the VP on which all VCs are to be restarted; the
vci
argument is ignored.
Specifies which VC(s) are to be restarted.
If
class
is set to
ATM_RESTART_VC, the
vpi
and
vci
arguments specify which VC is to
be restarted.
The
xxx_restart
routine is a function declared within
a signaling module that the CMM calls to request a RESTART message be sent.
The name of the routine (xxx_restart) can be any valid
C language function name.
You pass the routine to the CMM by reference only.
The
xxx_restart
routine must return
ATM_CAUSE_GOOD
if the signaling module is proceeding with the restart or an ATM
error number if the call cannot proceed.
atm_cmm_register_sig,
atm_cmm_restart_ack
xxx_setup
xxx_setup
atm_error_t xxx_setup(
atm_addr_p addr,
unsigned long *refptr
);
Specifies the pointer to the
atm_addr
structure.
The CMM will have initialized the
atm_addr
structure and
will have set up the
atm_uni_call_ie
structure with parameters
that the protocol convergence modules supplied.
Specifies a unique call reference number for the call. If the signaling module creates a unique call reference number for the call, the module must assign this value.
The
xxx_setup
routine is a function declared within
a signaling module that the CMM calls to request the creation of a new connection
(make a call).
The name of the routine (xxx_setup) can
be any valid C language function name.
You pass the routine to the CMM by
reference only.
When the CMM calls this routine, the signaling protocol module should
initiate a call to the party specified in the
atm_addr
structure.
This routine is nonblocking, and is used only to set up point-to-point
connections or the first connection in a point-to-multipoint connection.
Note
The CMM uses the value returned in refptr to release a connection. The signaling module should set this up as soon as possible, and before a call to
atm_cmm_con_release.
The
xxx_setup
routine returns
ATM_CAUSE_GOOD
if the setup is proceeding or an ATM error number if the call cannot
proceed.
xxx_xmit
xxx_xmit
atm_error_t xxx_xmit(
int unit,
struct mbuf *data,
long length,
atm_vc_p vc,
unsigned char clp,
unsigned char gfc
);
Specifies the unit number on which to send the data.
Specifies the data to be transmitted.
This data is passed
to the driver as a chain of mbufs.
The driver determines the type of data
being sent by examining
vc->vcs->aal.
Specifies to the driver the total number of bytes in the AAL5 PDU or the total number of bytes being sent. The use of this information depends on the driver implementation. The CMM uses this information to gather VC and interface usage statistics so the driver does not have to keep track of the total number of bytes transmitted.
Specifies the VC on which to send the data.
Specifies the CLP value for AAL5 PDUs. When sending raw cells, the convergence module must place this value in each cell header along with the gfc argument.
Specifies the GFC bits for congestion control when sending AAL5 PDUs. When sending raw cells, the convergence module must place this value in each cell header along with the clp argument.
The
xxx_xmit
routine is a function declared within
a device driver module that the CMM calls when it has data to transmit on
the interface.
The name of the routine (xxx_xmit) can
be any valid C language function name.
You pass the routine to the CMM by
reference only.
The
xxx_xmit
routine cannot block.
The driver must
either queue the data or, if the routine queue is full, return an error indication.
If the data is queued, the driver must return
ATM_CAUSE_GOOD.
If the data is not queued, the driver must return an ATM error number
that indicates the reason the data was not queued (ATM_CAUSE_QFULL
indicates a queue full condition).
In addition, the driver must
not discard the data.
The CMM returns the error indication to the convergence
module.
It is up to the convergence module to implement a discard or retry
policy.
atm_cmm_register_dd