atm_cmm_accept
- Accepts a previously deferred call and informs the CMM that the
call should be accepted
Synopsis
atm_error_t atm_cmm_accept(
atm_addr_p addr,
atm_vc_services_t give
);
Arguments
- addr
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.
- give
This argument
is not currently used.
Description
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.
Return Values
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.
Related Information
xxx_connect
Section 6.2
for information on accepting connections
atm_cmm_activate_con
NAME
atm_cmm_activate_conSynopsis
atm_error_t atm_cmm_activate_con(
atm_sig_handle_t sm,
atm_addr_t *addr
);
Arguments
- sm
Specifies the signaling
module handle that the CMM returned in the registration call.
- addr
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.
Description
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.
Return Values
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.
Related Information
atm_cmm_con_release,
xxx_setup,
xxx_add
Section 6.4
for information on releasing connections
atm_cmm_add
NAME
atm_cmm_addSynopsis
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
);
Arguments
- cm
Specifies a value
returned to the convergence module by the registration function call.
This
uniquely identifies the convergence module making the request.
- addr
Specifies a pointer
to a properly set
atm_addr
structure that specifies the
address of the endpoint to be added to the connection.
- ei
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.
- vc
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.
Description
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.
Example
See
Example B-2
for a code example of the
atm_cmm_add
routine.
Return Values
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.
Related Information
atm_cmm_drop
Chapter 6
for information on connections
atm_cmm_adi_set_cause
NAME
atm_cmm_adi_set_causeSynopsis
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
);
Arguments
- driver
Specifies the
interface on which the condition occurred.
This is the driver handle that
the CMM assigned at driver registration time.
- vp
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.
- addr
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.
- reason
Specifies a
NULL-terminated character string that contains descriptive text for the error.
- cause
Specifies the
atm_error_t
value that describes the condition.
- location
Specifies
an
atm_location_t
value that indicates the location in
the network where the error occurred.
- diag_length
Specifies
the length (in bytes) of the data in the
diag
argument.
- diag
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.
Description
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.
Return Values
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.
Related Information
atm_cmm_adi_set_log,
atm_cmm_next_cause,
atm_cmm_set_cause,
atm_cmm_smi_set_cause
Section 2.9.7
for information on cause information
atm_cmm_adi_set_log
NAME
atm_cmm_adi_set_logSynopsis
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
);
Arguments
- driver
Specifies the
interface on which the condition occurred.
This is the driver handle that
the CMM assigned at driver registration time.
- vp
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.
- addr
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.
- reason
Specifies a
NULL-terminated character string that contains descriptive text for the error.
- cause
Specifies the
atm_error_t
value that describes the condition.
- location
Specifies
the location in the network where the error occurred.
- diag_length
Specifies
the length (in bytes) of the data in the
diag
argument.
- diag
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.
Description
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.
Return Values
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.
Related Information
atm_cmm_adi_set_cause,
atm_cmm_next_cause,
atm_cmm_set_log,
atm_cmm_smi_set_log
Section 2.9.7
for information on cause information
atm_cmm_alloc_addr
NAME
atm_cmm_alloc_addratm_addr
structure
Synopsis
atm_addr_p atm_cmm_alloc_addr(void
);
Description
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.
Example
See
Section B.1
for a code example of the
atm_cmm_alloc_addr
routine.
Return Values
If storage cannot be allocated, a NULL is returned; otherwise, a pointer
to the allocated memory is returned.
Related Information
atm_cmm_free_addr
Section B.1
for information on connections
atm_cmm_alloc_ie
NAME
atm_cmm_alloc_ieatm_uni_call_ie
structure
Synopsis
atm_uni_call_ie_p atm_cmm_alloc_ie(
int num_ie
);
Arguments
- num_ie
Specifies the
number of IE structures to allocate.
Description
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.
Example
See
Section B.1,
Section B.2,
and
Section B.3
for code examples of the
atm_cmm_alloc_ie
routine.
Return Values
If storage cannot be allocated, a NULL is returned; otherwise, a pointer
to the allocated memory is returned.
Related Information
atm_cmm_free_ie
Chapter 6
for information on connections
atm_cmm_alloc_services
NAME
atm_cmm_alloc_servicesatm_vc_services
structure
Synopsis
atm_vc_services_p atm_cmm_alloc_services(
void
);
Description
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 unspecified bit rate (UBR) 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.
Example
See
Section B.1
for a code example of the
atm_cmm_alloc_services
routine.
Return Values
If storage cannot be allocated, a NULL is returned; otherwise, a pointer
to the allocated memory is returned.
Related Information
atm_cmm_free_services
Chapter 6
for information on connections
atm_cmm_bind_info
NAME
atm_cmm_bind_infoSynopsis
unsigned long atm_cmm_bind_info(
atm_bind_handle_t handle,
atm_bind_info_t it
);
Arguments
- handle
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.
- it
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 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, for CBR 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 for CBR circuits. |
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 for CBR and pacing circuits. |
ATM_PPA_MAXRES |
Returns a type of
atm_services_granes_p, which reflects the maximum bandwidths available for CBR 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 circuits. |
Description
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.
Return Values
If an invalid query is made for an
ATM_BIND_*
object
type,
atm_cmm_bind_info
returns a value of -1.
If an invalid query is made for any other object type, the function returns
a value of 0.
Related Information
atm_cmm_del_ppa,
atm_cmm_new_ppa,
atm_cmm_ppa_bind,
atm_cmm_ppa_info
Section 3.4.1.15
for information on driver capabilities
atm_cmm_con_deleted
NAME
atm_cmm_con_deletedSynopsis
atm_err_t atm_cmm_con_deleted(
atm_sig_handle_t sm,
atm_addr_p addr
);
Arguments
- sm
Specifies the signaling
module handle that the CMM returned in the registration call.
- addr
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.
Description
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.
Return Values
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.
Related Information
atm_cmm_activate_con,
atm_cmm_con_release,
xxx_add,
xxx_setup
Section 6.4.2
for information on releasing connections
atm_cmm_con_failed
NAME
atm_cmm_con_failedSynopsis
atm_error_t atm_cmm_con_failed(
atm_sig_handle_t sm,
atm_addr_t *addr
);
Arguments
- sm
Specifies the signaling
module handle that the CMM returned in the registration call.
- addr
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.
Description
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.
Return Values
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.
Related Information
Section 6.1
for information on setting up connections
atm_cmm_con_release
NAME
atm_cmm_con_releaseSynopsis
atm_error_t atm_cmm_con_release(
atm_sig_handle_t sm,
unsigned long reference,
atm_ppa_p ppa
);
Arguments
- sm
Specifies the signaling
module handle that the CMM returned in the registration call.
- reference
Specifies
the unique call reference value that identifies the connection to be released.
- ppa
Specifies a pointer
to the PPA to which the VC being released belongs.
Description
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.
Return Values
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.
Related Information
atm_cmm_activate_con,
atm_cmm_con_deleted
Section 6.4
for information on releasing connections
atm_cmm_connect
NAME
atm_cmm_connectSynopsis
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
);
Arguments
- cm
Specifies a value
returned to the convergence module by the registration function call.
This
uniquely identifies the convergence module making the request.
- type
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.
This sets the
ATM_SERVICES_PTM
flag in the
atm_vc_services
structure. |
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. |
- calling
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.
- called
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 5.22.2
for information on the
atm_cmi_addr
union.
- ie
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.
- aging
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.
- params
Specifies an
atm_vc_services_p
pointing to a properly set
atm_vc_services
structure that defines the circuit parameters.
For CBR circuits,
the
params
argument can be a resource reservation;
that is, a services structure that is backed by reserved resources.
Description
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.
Notes
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.
Example
See
Section B.1
for a code example of the
atm_cmm_connect
routine.
Return Values
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.
Related Information
atm_cmm_vc_control
Section 5.22.2
for information on the
atm_cmi_addr
union
Section 6.3
for information on connection aging
Section 6.5
for information on PVC creation
atm_cmm_cr2grain
NAME
atm_cmm_cr2grainSynopsis
unsigned longatm_cmm_cr2grain(
atm_ppa_p ppa,
unsigned long cr,
atm_direction_t direction
);
Arguments
- ppa
Specifies a pointer
to the PPA for which the conversion is to be performed.
This can be any valid
PPA configured in the system.
- cr
Specifies the cell
rate, in cells per second, to be converted.
- direction
Specifies
the direction of the cell rate.
A driver might have different allocation granularities
for the forward and backward directions.
Description
The
atm_cmm_cr2grain
routine is a convergence module
interface that converts a cell rate to an allocation granularity unit.
Some
ATM drivers do not support setting a virtual circuit's (VC) cell rate in 1
cell per second increments.
You can also use the
atmconfig
command to set a driver's allocation granularity.
Therefore, this routine
enables a convergence module to determine the nearest actual cell rate that
can be achived on the VC, allowing for the allocation granularity.
The
atm_cmm_cr2grain
routine converts a cell rate
to the nearest number of allocation granularity units, rounding as necessary.
In the forward direction, the return value is the number of allocation granularity
units that comes closest to, but does not exceed, the cell rate, to avoid
violating the network contract.
In the backward direction, the return value
is the number of allocation granularity units that are needed to handle the
entire incoming cell rate to avoid violating the network contract.
Return Values
Returns the number of granularity units.
Returns zero if the driver
associated with the PPA does not support traffic shaping (for example, CBR
and VBR).
Related Information
atm_cmm_grain2cr,
atm_cmm_ppa_info
atm_cmm_del_esi
NAME
atm_cmm_del_esiSynopsis
atm_err_t atm_cmm_del_esi(
atm_cvg_handle_t cvg_handle,
atm_esi_handle_t esi
);
Arguments
- cvg_handle
Specifies
the value returned to the convergence module by the registration request routine.
This uniquely identifies the convergence module making the request.
- esi
Specifies the value
returned to the convergence module when the ESI was created.
Description
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.
Return Values
None
Related Information
atm_cmm_new_esi
atm_cmm_del_ppa
NAME
atm_cmm_del_ppaSynopsis
atm_error_t atm_cmm_del_ppa(
atm_sig_handle_t sm,
atm_ppa_p ppa
);
Arguments
- sm
Specifies the signaling
module handle that the CMM returned in the registration call.
- ppa
Specifies the PPA
pointer that was returned when the PPA was added to the system.
Description
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).
Return Values
Upon successful completion, the
atm_cmm_del_ppa
routine
returns
ATM_CAUSE_GOOD; otherwise, it returns an ATM error
number.
Related Information
atm_cmm_new_ppa,
atm_cmm_ppa_bind,
atm_cmm_ppa_info
atm_cmm_drop
NAME
atm_cmm_dropSynopsis
atm_err_t atm_cmm_drop(
atm_cvg_handle_t cm,
atm_addr_t *addr
);
Arguments
- cm
Specifies a value
that the registration function call returns to the convergence module.
This
uniquely identifies the convergence module making the request.
- addr
Specifies a pointer
to the
atm_addr
structure of the endpoint to be dropped.
Description
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.
Return Values
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.
Related Information
atm_cmm_add
atm_cmm_enquery
NAME
atm_cmm_enquerySynopsis
atm_err_t atm_cmm_enquery(
atm_cvg_handle_t cm,
atm_addr_t *ep
);
Arguments
- cm
Specifies a value
that the registration function call returns to the convergence module.
This
uniquely identifies the convergence module making the request.
- ep
Specifies the endpoint
to be queried.
Description
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.
Return Values
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.
Related Information
atm_cmm_add
atm_cmm_ep_add
NAME
atm_cmm_ep_addSynopsis
atm_err_t atm_cmm_ep_add(
atm_sig_handle_t sm,
atm_addr_t *addr,
atm_uni_call_ie_p ie,
atm_ppa_p ppap,
unsigned long call_reference,
unsigned long epreference
);
Arguments
- sm
Specifies the signaling
module handle that the CMM returned in the registration call.
- addr
Specifies a pointer
to an
atm_addr
structure that contains all the information
about the incoming endpoint.
The signaling module writes the information into
this structure.
- ie
Specifies a pointer
to an array of optional information elements received from the adding party.
The signaling module converts data from the incoming signaling
messages and fills in an array of information element structures.
- ppap
Specifies the
PPA on which the incoming add request was received.
- call_reference
Specifies
the unique call reference value associated with this call.
The signaling module
should have already delivered a call with this reference when the initial
connection was received.
- epreference
Specifies
the unique endpoint reference value associated with the endpoint.
This value
identifies the endpoint during its entire lifetime on the system.
The value
is unique with respect to
call_reference, but might
be duplicated across different calls.
The value is opaque to the CMM, and
can have special meaning to the signaling module.
Description
The
atm_cmm_ep_add
routine is a signaling module
interface.
A signaling module calls this routine when the module receives
a request to add an endpoint to an existing call.
This notifies the CMM of
the new endpoint.
The CMM determines whether to accept the endpoint.
This routine is nonblocking, and returns an indication about the disposition
of the endpoint.
Return Values
If the CMM and the convergence module that owns the call agree to accept
the endpoint, the
atm_cmm_ep_add
routine returns
ATM_CAUSE_GOOD.
If the call is rejected, the routine returns an ATM error value that
indicates the reason.
The convergence module might supply additional information
in the cause fields in the
atm_addr
structure.
If the endpoint
is rejected, the signaling module must deallocate the storage for the
atm_addr
structure and the information elements.
Related Information
xxx_except,
atm_cmm_new_call
Section 6.1.2
for information on adding endpoints
atm_cmm_ep_dropped
NAME
atm_cmm_ep_droppedSynopsis
atm_err_t atm_cmm_ep_dropped(
atm_sig_handle_t sm,
unsigned long reference,
long epreference,
atm_ppa_p ppa
);
Arguments
- sm
Specifies the signaling
module handle that the CMM returned in the registration call.
- reference
Specifies
the unique call reference value that identifies the connection to be released.
- epreference
Specifies
the unique endpoint reference value that identifies the endpoint to be dropped.
- ppa
Specifies a pointer
to the PPA to which the VC being released belongs.
Description
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.
Return Values
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.
Related Information
atm_cmm_add,
atm_cmm_drop
atm_cmm_error
NAME
atm_cmm_errorSynopsis
void atm_cmm_error(
atm_drv_handle_t driver,
int error,
atm_vc_t *vc
);
Arguments
- driver
Specifies the
interface on which the error has occurred.
This is the handle assigned to
the driver when the driver registers with the CMM.
- error
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. |
- vc
Specifies a pointer
to the VC on which the error occurred.
If the error is not associated with
a VC, this is NULL.
Description
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.
Return Values
None
Related Information
Chapter 9
for information on flow control in the
ATM subsystem
atm_cmm_findaddr
NAME
atm_cmm_findaddrSynopsis
atm_addr_p atm_cmm_findaddr(
long call_reference,
long endpoint,
atm_ppa_p ppa
);
Arguments
- call_reference
Specifies
the unique call reference value assigned to the VC.
- endpoint
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.
- ppa
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.
Description
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.
Return Values
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.
Related Information
atm_cmm_add
atm_cmm_find_driver
NAME
atm_cmm_find_driverSynopsis
atm_drv_handle_t atm_cmm_find_driver(
char *name
);
Arguments
- name
Specifies a NULL-terminated
character string that identifies the driver.
Description
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.
Return Values
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.
Related Information
atm_cmm_register_dd
atm_cmm_free_addr
NAME
atm_cmm_free_addratm_addr
structures
Synopsis
void atm_cmm_free_addr(
atm_addr_p addr
);
Arguments
- addr
Specifies a pointer
to the
atm_addr
structure to free.
This is the same pointer
passed into the
atm_alloc_addr
routine.
Description
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.
Return Values
None
Related Information
atm_cmm_alloc_addr
atm_cmm_free_ie
NAME
atm_cmm_free_ieSynopsis
void atm_cmm_free_ie(
atm_uni_call_ie_p u
);
Arguments
- 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.
Description
The
atm_cmm_free_ie
routine is a convergence module
interface that convergence modules use to free IE structure memory that they
have allocated.
Example
See
Section B.1
for a code example of the
atm_cmm_free_ie
routine.
Return Values
None
Related Information
atm_cmm_alloc_ie
atm_cmm_free_services
NAME
atm_cmm_free_servicesatm_vc_services
structures and
releases reserved resources
Synopsis
atm_error_t atm_cmm_free_services(
atm_vc_services_p s
);
Arguments
- s
Specifies a pointer
to the
atm_vc_services
structure to free.
This is the
same pointer passed into the
atm_alloc_services
routine.
Description
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 6.1
for more information.)
The
atm_cmm_free_services
call frees the
atm_vc_services_t
memory and releases its reserved resources, if any.
Return Values
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.
Related Information
atm_cmm_alloc_services,
atm_cmm_reserve_resources,
xxx_except
Section 5.2.1
for information on convergence module
exception handling
Section 6.1
for information on making outgoing connections
and resource reservations
atm_cmm_grain2cr
NAME
atm_cmm_grain2crSynopsis
unsigned long atm_cmm_grain2cr(
atm_ppa_p ppa,
unsigned long nm,
atm_direction_t direction
);
Arguments
- ppa
Specifies a pointer
to the PPA for which the conversion is to be performed.
This can be any valid
PPA configured in the system.
- hm
Specifies the granularity
units to be converted.
- direction
Specifies
the direction of the cell rate.
A driver might have different allocation granularities
for the forward and backward directions.
Description
The
atm_cmm_grain2cr
routine is a convergence module
interface that converts allocation granularity units to a cell rate.
Some
ATM drivers do not support setting a virtual circuit's (VC) cell rate in increments
of 1 cell per second.
You can also use the
atmconfig
command
to set a driver's allocation granularity.
Therefore, this routine enables
a convergence module to determine the nearest actual cell rate that can be
achived on the VC, allowing for the allocation granularity.
The
atm_cmm_grain2cr
routine converts number of allocation
granularity units, for the given adapter and direction, to a cell rate (in
cells per second).
Return Values
Returns the number of cells per second.
Returns zero if the driver associated
with the PPA does not support traffic shaping (for example, CBR and VBR).
Related Information
atm_cmm_cr2grain,
atm_cmm_ppa_info
atm_cmm_new_call
NAME
atm_cmm_new_callSynopsis
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
);
Arguments
- sm
Specifies the signaling
protocol module handle that was returned by the registration function.
- addr
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.
- ie
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.
- services
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.)
- ppap
Specifies the
PPA on which the incoming call arrived.
- selector
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.
- vpi
Specifies the VPI
value for the new VC that the network has created for this call.
- vci
Specifies the VCI
value for the new VC that the network has created for this call.
- call_reference
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.
Description
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.
Return Values
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.
Related Information
xxx_except
Section 6.2
for information on receiving connections
atm_cmm_new_esi
NAME
atm_cmm_new_esiSynopsis
atm_esi_handle_t atm_cmm_new_esi(
atm_cvg_handle_t cvg_handle,
unsigned char *esi,
int esilen,
atm_drv_handle_t driver,
void *arg
);
Arguments
- cvg_handle
Specifies
the convergence module handle returned to the convergence module when it registered
with the CMM.
- esi
Specifies a pointer
to an array of the 6 bytes of ESI to be registered with the network.
- esilen
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.
- driver
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.
- arg
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.
Description
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.
Return Values
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.
Related Information
atm_cmm_del_esi,
atm_cmm_ppa_bind
atm_cmm_new_ppa
NAME
atm_cmm_new_ppaSynopsis
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
);
Arguments
- sm
Specifies the signaling
module handle that the registration function call returned.
- addr
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.
- addrlen
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.
- ton
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).
- anpi
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.
- driver
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.
- esi
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.
- ppas_id
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.
- uni
Identifies the
type of UNI (public or private) associated with the PPA.
- sig_info
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.
Description
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.
Return Values
Upon successful completion, the
atm_cmm_new_ppa
routine
returns a valid PPA pointer for the new PPA; otherwise, it returns NULL.
Related Information
atm_cmm_del_ppa,
atm_cmm_ppa_bind,
atm_cmm_ppa_info
atm_cmm_new_thread
NAME
atm_cmm_new_threadSynopsis
thread_t atm_cmm_new_thread(
task_t task,
void(*)(void * arg) *first,
void *arg,
int pri,
int maxpri
);
Arguments
- task
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).
- first
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.
- arg
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.
- pri
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.
- maxpri
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
Description
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 operating system's thread primitives to provide an easier interface
for ATM modules.
Return Values
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.
Related Information
Section 2.7.4
for a description of ATM thread creation
atm_cmm_next_cause
NAME
atm_cmm_next_causeSynopsis
atm_cause_info_p atm_cmm_next_cause(
atm_vc_p vp,
atm_addr_p addr,
atm_cause_info_p cip
);
Arguments
- vp
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.
- addr
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.
- cip
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.
Description
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.
Return Values
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.
Related Information
atm_cmm_adi_set_cause,
atm_cmm_set_cause,
atm_cmm_smi_set_cause
Section 2.9.7
for information on cause information
atm_cmm_oam_receive
NAME
atm_cmm_oam_receiveSynopsis
void atm_cmm_oam_receive(
atm_drv_handle_t driver,
struct mbuf *mbp,
atm_vc_t *vc
);
Arguments
- driver
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.
- mbp
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.
- vc
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.
Description
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.
Return Values
None
Related Information
atm_cmm_receive
Section 2.4.3
for information on how data are carried
atm_cmm_ppa_bind
NAME
atm_cmm_ppa_bindSynopsis
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)
);
Arguments
- ppa
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.
- cvg_handle
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.
- selector
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).
- bind_handle
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.
- xxx_connect
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.
Description
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.
Return Values
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.
Related Information
atm_cmm_bind_info,
atm_cmm_del_ppa,
atm_cmm_new_ppa,
atm_cmm_ppa_info,
atm_cmm_ppa_unbind,
xxx_connect
Section 2.5
for information on PPAs and AESAs
atm_cmm_ppa_info
NAME
atm_cmm_ppa_infoSynopsis
unsigned long atm_cmm_ppa_info(
atm_ppa_p ppa,
atm_bind_info_t it
);
Arguments
- ppa
Specifies a pointer
to the PPA for which information is to be retrieved.
This can be any valid
PPA currently configured on the system.
- it
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 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 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 the interface's peak cell rate that
is available to 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 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 for CBR and pacing circuits. |
ATM_PPA_MAXRES |
Returns a type of
atm_services_granes_p, which reflects the maximum bandwidths available for CBR 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 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 circuits. |
Description
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.
Return Values
None
Related Information
atm_cmm_bind_info,
atm_cmm_del_ppa,
atm_cmm_new_ppa,
atm_cmm_ppa_bind,
atm_cmm_ppa_unbind
Section 3.4.1.15
for a description of the
capabilities
member of the
atm_drv_params
structure
atm_cmm_ppa_unbind
NAME
atm_cmm_ppa_unbindSynopsis
atm_error_t atm_cmm_ppa_unbind(
atm_bind_handle_t bind_handle
);
Arguments
- bind_handle
Specifies
the binding to be removed.
This is the handle that the
atm_cmm_ppa_bind
routine returns to the convergence module.
Description
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 releases all VCs associated with the bind point.
Return Values
Upon successful completion, the
atm_cmm_ppa_unbind
routine returns
ATM_CAUSE_GOOD; otherwise, it returns an
ATM error number.
Related Information
atm_cmm_bind_info,
atm_cmm_del_ppa,
atm_cmm_new_ppa,
atm_cmm_ppa_bind,
atm_cmm_ppa_info
atm_cmm_receive
NAME
atm_cmm_receiveSynopsis
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
);
Arguments
- driver
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.
- mbp
Specifies a pointer
to a chain of mbufs that contain the data received.
- length
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.
- trailer
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.
- vc
Specifies a pointer
to the
atm_vc
structure of the VC on which the data was
received.
- pti
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.
- gfc
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.
Description
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.
Return Values
None
Related Information
xxx_xmit
Section 2.4.3
for information on the mbuf chain
Section 3.2
for information on receiving cells
atm_cmm_register_cvg
NAME
atm_cmm_register_cvgSynopsis
void * atm_cmm_register_cvg(
long version,
char *const name,
void *cvg_handle,
atm_cvg_params_t *params,
atm_cvg_handle_t *return_handle,
void *reserved
);
Arguments
- version
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.
- name
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.
- cvg_handle
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.
- params
Specifies a
pointer to a
atm_cvg_params
structure that defines the entry points and capabilities of the convergence
module.
To allow for future expansion of the structure, the convergence module
should call the
bzero
command to insert nulls into the
entire structure before filling in the fields.
For the registration call,
this pointer can reference private memory because the CMM copies the information
into its local memory before returning.
- return_handle
Specifies
a pointer to a
atm_cvg_handle_t
variable that CMM fills
in with a unique value to identify this instance of the convergence module.
The convergence module must use this value on all subsequent calls to the
CMM.
This value is set before the CMM calls any of the convergence module's
entry points, which can happen before the
atm_cmm_register_cvg
call returns.
- reserved
This parameter
is reserved for future use, and must be specified as NULL.
Description
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.
Return Values
Upon successful registration, the
atm_cmm_register_cvg
routine returns a non-NULL value; otherwise, it returns NULL.
Related Information
atm_cmm_unregister_cvg,
xxx_except,
xxx_mmi,
xxx_receive
Section 5.22.3
for the
atm_cvg_params
structure definition
Chapter 7
for information on the MMI
atm_cmm_register_dd
NAME
atm_cmm_register_ddSynopsis
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)
);
Arguments
- version
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.
- params
Specifies a
pointer to an
atm_drv_params
structure, which defines the
basic capabilities of the interface.
This structure must be completely initialized.
To allow for future expansion of the structure, the convergence module should
call the
bzero
command to insert nulls into the entire
structure before filling in the fields.
For the registration call, this pointer
can reference private memory because the CMM copies the information into its
local memory before returning.
- xxx_xmit
Specifies
the address of the routine for the CMM to call when it has data to transmit
on the interface.
- xxx_manage
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.
- xxx_mmi
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.
Description
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.
Return Values
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.
Related Information
xxx_manage,
xxx_mmi,
xxx_xmit
Section 2.4.3
for information on the mbuf chain
Chapter 3
for more information on the device driver
interface and the
atm_queue_param
structure
Chapter 7
for more information on the MMI
atm_cmm_register_sig
NAME
atm_cmm_register_sigSynopsis
void * atm_cmm_register_sig(
long version,
char *const id,
void *sig_handle,
atm_sig_params_t *params,
atm_sig_handle_t *return_handle,
void * reserved1,
void * reserved2,
void * reserved3,
void * reserved4,
void * reserved5,
void * reserved6,
void * reserved7
);
Arguments
- version
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.
- id
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.
- sig_handle
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.
- params
Specifies a
pointer to a
atm_sig_params
structure that defines the entry points and capabilities of the signaling
module.
To allow for future expansion of the structure, the convergence module
should call the
bzero
command to insert nulls into the
entire structure before filling in the fields.
For the registration call,
this pointer can reference private memory because the CMM copies the information
into its local memory before returning.
- return_handle
Specifies
a pointer to a
atm_sig_handle_t
variable that CMM fills
in with a unique value to identify this instance of the signaling module.
The signaling module must use this value on all subsequent calls to the CMM.
This value is set before the CMM calls any of the signaling module's entry
points, which can happen before the
atm_cmm_register_sig
call returns.
- reserved1
This parameter
is reserved for future use, and must be specified as NULL.
- reserved2
This parameter
is reserved for future use, and must be specified as NULL.
- reserved3
This parameter
is reserved for future use, and must be specified as NULL.
- reserved4
This parameter
is reserved for future use, and must be specified as NULL.
- reserved5
This parameter
is reserved for future use, and must be specified as NULL.
- reserved6
This parameter
is reserved for future use, and must be specified as NULL.
- reserved7
This parameter
is reserved for future use, and must be specified as NULL.
Description
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.
Return Values
Upon successful registration, the
atm_cmm_register_sig
routine returns a non-NULL value; otherwise, it returns NULL.
Related Information
xxx_add,
xxx_drop,
xxx_enquery,
xxx_except,
xxx_mmi,
xxx_release,
xxx_restart,
xxx_setup
Section 4.16
for the
atm_sig_params
structure definition
Section 6.6
for a description of signaling VC initialization
Chapter 7
for a discussion of the MMI
atm_cmm_reject
NAME
atm_cmm_rejectSynopsis
void atm_cmm_reject(
atm_addr_p addr
);
Arguments
- 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.
Description
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.
Return Values
None
Related Information
atm_cmm_accept,
atm_cmm_new_call
atm_cmm_release
NAME
atm_cmm_releaseSynopsis
atm_err_t atm_cmm_release(
atm_cvg_handle_t cm,
atm_vc_t *vc
);
Arguments
- cm
Specifies the value
that the registration routine returns to the convergence module.
This uniquely
identifies the convergence module making the request.
- vc
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.
Description
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.
Return Values
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.
Related Information
atm_cmm_con_release
atm_cmm_reply
NAME
atm_cmm_replySynopsis
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
);
Arguments
- sm
Specifies the signaling
module's handle assigned to it when it registered with the CMM.
- addr
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.
- ies
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.
- vpi
Specifies the VPI
value for the connection.
The network should assign this before the routine
is called.
- vci
Specifies the VCI
value for the connection.
The network should assign this before the routine
is called.
- call_reference
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.
Description
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.
Return Values
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.
Related Information
atm_cmm_activate_con
atm_cmm_reserve_resources
NAME
atm_cmm_reserve_resourcesSynopsis
atm_err_t atm_cmm_reserve_resources(
atm_ppa_p ppa,
atm_cvg_handle_t cm,
atm_vc_services_p s
);
Arguments
- ppa
Specifies the underlying
driver or adapter bandwidth pool from which to allocate the resources.
The
underlying driver or adapter must support CBR.
These resources can be applied
only to point-to-point connections set up over bind points associated with
the same PPA.
- cm
Specifies the value
returned to the convergence module by the registration request routine.
This
uniquely identifies the convergence module reserving the resources.
- s
Specifies an
atm_vc_services_p
pointing to a properly set
atm_vc_services
structure that defines the CBR circuit parameters.
Description
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.
Return Values
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.
Related Information
atm_cmm_free_services
atm_cmm_restart
NAME
atm_cmm_restartSynopsis
atm_err_t atm_cmm_restart(
atm_sig_handle_t sm,
unsigned int class,
unsigned int vpi,
unsigned int vci
);
Arguments
- sm
Specifies the signaling
module's handle returned by the CMM when the signaling module registers.
- class
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).
- vpi
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.
- vci
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.
Description
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.
Return Values
If the restart is successfully initiated, the
atm_cmm_restart
routine returns
ATM_CAUSE_GOOD; otherwise, it
returns an appropriate ATM error number.
Related Information
atm_cmm_new_call,
atm_cmm_restart_ack
atm_cmm_restart_ack
NAME
atm_cmm_restart_ackSynopsis
void atm_cmm_restart_ack(
void *handle,
unsigned int class,
unsigned int vpi,
unsigned int vci
);
Arguments
- handle
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.
- class
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).
- vpi
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.
- vci
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.
Description
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.
Return Values
None
Related Information
atm_cmm_restart
atm_cmm_send
NAME
atm_cmm_sendSynopsis
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
);
Arguments
- cm
Specifies the value
returned to the convergence module by the registration function call.
This
uniquely identifies the convergence module making the request.
- vc
Specifies a pointer
to the
atm_vc
structure of the VC on which the data is
to be sent.
- data
Specifies a pointer
to a chain of mbufs that contain the data to be transmitted.
- length
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.
- clp
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.
- gfc
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.
Description
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.
Return Values
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.
Related Information
xxx_xmit
Section 2.4.3
for more information on the mbuf chain
Chapter 9
for information on flow control in the
ATM subsystem
atm_cmm_set_cause
NAME
atm_cmm_set_causeSynopsis
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
);
Arguments
- cm
Specifies the value
the registration request function call returned to the convergence module.
This uniquely identifies the convergence module making the request.
- vp
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.
- addr
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.
- reason
Specifies a
NULL-terminated character string that contains descriptive text for the error.
- cause
Specifies the
atm_error_t
value that describes the condition.
- location
Specifies
an
atm_location_t
value that identifies the location in
the network where the error occurred.
- diag_length
Specifies
the length (in bytes) of the data in the
diag
argument.
- diag
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.
Description
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.
Return Values
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.
Related Information
atm_cmm_adi_set_cause,
atm_cmm_next_cause,
atm_cmm_set_log,
atm_cmm_smi_set_cause
Section 2.9.7
for information on cause information
atm_cmm_set_log
NAME
atm_cmm_set_logSynopsis
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
);
Arguments
- cm
Specifies the value
the registration request function call returned to the convergence module.
This uniquely identifies the convergence module making the request.
- vp
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.
- addr
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.
- reason
Specifies a
NULL-terminated character string that contains descriptive text for the error.
- cause
Specifies the
atm_error_t
value that describes the condition.
- location
Specifies
an
atm_location_t
value that identifies the location in
the network where the error occurred.
- diag_length
Specifies
the length (in bytes) of the data in the
diag
argument.
- diag
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.
Description
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.
Return Values
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.
Related Information
atm_cmm_adi_set_log,
atm_cmm_next_cause,
atm_cmm_set_cause,
atm_cmm_smi_set_log
Section 2.9.7
for information on cause information
atm_cmm_smi_set_cause
NAME
atm_cmm_smi_set_causeSynopsis
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
);
Arguments
- sm
Specifies the signaling
module handle that the registration function call returned.
- vp
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.
- addr
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.
- reason
Specifies a
NULL-terminated character string that contains descriptive text for the error.
- cause
Specifies the
atm_error_t
value that describes the condition.
- location
Specifies
an
atm_location_t
value that identifies the location in
the network where the error occurred.
- diag_length
Specifies
the length (in bytes) of the data in the
diag
argument.
- diag
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.
Description
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.
Return Values
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.
Related Information
atm_cmm_adi_set_cause,
atm_cmm_smi_set_log,
atm_cmm_next_cause,
atm_cmm_set_cause
Section 2.9.7
for information on cause information
atm_cmm_smi_set_log
NAME
atm_cmm_smi_set_logSynopsis
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
);
Arguments
- sm
Specifies the signaling
module handle that the registration function call returned.
- vp
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.
- addr
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.
- reason
Specifies a
NULL-terminated character string that contains descriptive text for the error.
- cause
Specifies the
atm_error_t
value that describes the condition.
- location
Specifies
an
atm_location_t
value that identifies the location in
the network where the error occurred.
- diag_length
Specifies
the length (in bytes) of the data in the
diag
argument.
- diag
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.
Description
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.
Return Values
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.
Related Information
atm_cmm_adi_set_log,
atm_cmm_next_cause,
atm_cmm_set_log,
atm_cmm_smi_set_cause
Section 2.9.7
for information on cause information
atm_cmm_status_done
NAME
atm_cmm_status_doneSynopsis
void atm_cmm_status_done(
atm_addr_p addr
);
Arguments
- 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.
Description
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.
Return Values
None
Related Information
atm_cmm_enquery
atm_cmm_unregister_cvg
NAME
atm_cmm_unregister_cvgSynopsis
atm_error_t atm_cmm_unregister_cvg(
atm_cvg_handle_t cm
);
Arguments
- cm
Specifies a value
that identifies the convergence module.
The
atm_cmm_register_cvg
call returns this value.
Description
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,
delete any ESIs it created, 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.
Return Values
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 repeat the unregister call until the routine returns
ATM_CAUSE_GOOD.
It might take up to several seconds for all connections
to clear completely.
Related Information
atm_cmm_register_cvg
atm_cmm_vc_control
NAME
atm_cmm_vc_controlSynopsis
atm_err_t atm_cmm_vc_control(
atm_cvg_handle_t cm,
atm_vc_t *vc,
int operation,
void *arg
);
Arguments
- cm
Specifies the value
returned to the convergence module by the registration function call.
This
uniquely identifies the convergence module making the request.
- vc
Specifies the VC
to which the function call applies.
- operation
Specifies
the type of operation to be performed on the VC.
- arg
Specifies further
data for the operations.
The type and use of this argument depend 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 a pointer
to an
unsigned int
whose value is the new aging parameter
(see
Table 6-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. |
Description
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.
Return Values
Upon successful completion, the
atm_cmm_vc_control
routine returns
ATM_CAUSE_GOOD; otherwise, it returns an
ATM error number.
Related Information
Section 3.4.2
for information on the
atm_queue_param
structure
Section 6.3
for information on connection aging
atm_cmm_vc_get
NAME
atm_cmm_vc_getSynopsis
atm_vc_p atm_cmm_vc_get(
atm_drv_handle_t driver,
unsigned int vpi,
unsigned int vci
);
Arguments
- driver
Specifies the
device driver handle for the PPA to which the VC being queried is attached.
- vpi
Specifies the VPI
values for the VC.
- vci
Specifies the VCI
values for the VC.
Description
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.
Return Values
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.
Related Information
atm_cmm_status_done,
atm_cmm_vc_stats
atm_cmm_vc_stats
NAME
atm_cmm_vc_statsSynopsis
atm_error_t atm_cmm_vc_stats(
atm_vc_p vc,
atm_vc_stats_p stats
);
Arguments
- vc
Specifies a pointer
to the VC for which statistics are to be reported.
- stats
Specifies a pointer
to an
atm_vc_stats
structure allocated by the caller into
which the CMM can copy the statistics.
Description
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.
Return Values
Upon successful completion, the
atm_cmm_vc_stats
routine returns
ATM_CAUSE_GOOD; otherwise, it returns an
ATM error.
Related Information
atm_cmm_vc_control,
atm_cmm_vc_get
xxx_add
NAME
xxx_addSynopsis
atm_error_t xxx_add(
atm_addr_p addr
);
Arguments
- addr
Specifies a pointer
to the
atm_addr
structure for the endpoint to be added.
Description
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.
Return Values
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.
Related Information
atm_cmm_register_sig
xxx_connect
NAME
xxx_connectSynopsis
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
);
Arguments
- bind_handle
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.
- addr
Specifies a pointer
to the
atm_addr
structure, indicating the endpoint that
is initiating the connection.
- myaddr
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.
- vc
Specifies a pointer
to the VC of the new connection.
- reply
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.
- requested
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.
- avail
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.
The convergence module can pace outbound traffic on
the new UBR connection by setting
avail
to the
address of an
atm_vc_services
structure that has the
ATM_SERVICES_PACING
flag set and the peak bit rates set to the rates
you want.
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.
Description
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.
Notes
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.
Example
See
Section B.3
for a code example of the
xxx_connect
routine.
In the example,
new_connect
is the name of the routine.
Return Values
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.
Related Information
atm_cmm_accept,
atm_cmm_ppa_bind,
atm_cmm_reject
xxx_drop
NAME
xxx_dropSynopsis
atm_error_t xxx_drop(
atm_addr_p addr
);
Arguments
- addr
Specifies a pointer
to the
atm_addr
structure for the endpoint to be dropped.
Description
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.
Return Values
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.
Related Information
atm_cmm_register_sig
xxx_endpt_receive
NAME
xxx_endpt_receiveSynopsis
void xxx_endpt_receive(
atm_vc_t *vc,
struct mbuf *mbp,
int length,
struct mbuf *trailer,
char pti,
char gfc,
atm_addr_p addr
);
Arguments
- vc
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.
- mbp
Specifies a pointer
to a list of mbufs that contain the data received.
A unique mbuf chain is
provided for each endpoint.
All chains might point a single physical copy
of the data.
- length
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).
- trailer
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.
- pti
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.
- gfc
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.
- addr
Specifies the
endpoint on the specified VC for which this data is being delivered.
The convergence
module might use its two private structure members in the
atm_addr
structure to hold local information about the endpoint.
Description
The
xxx_endpt_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_endpt_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.
Return Values
None
Related Information
atm_cmm_register_cvg,
atm_cmm_receive
Section 2.4
for a description of ATM data formats
Chapter 3
and
Chapter 5
for information
on device drivers and convergence modules, respectively
xxx_enquery
NAME
xxx_enquerySynopsis
atm_error_t xxx_enquery(
atm_addr_p addr
);
Arguments
- addr
Specifies a pointer
to the
atm_addr
structure for the endpoint to be queried.
Description
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.
Return Values
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.
Related Information
atm_cmm_register_sig
xxx_except
NAME
xxx_exceptSynopsis
int xxx_except(
void *handle,
unsigned int exception,
void *arg
);
Arguments
- handle
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.
- exception
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
atm_addr_p
that specifies
the endpoint to which the CMM was trying to connect.
The cause information
in the
atm_addr
structure is set to indicate the reason
for the call failure, which can be the failure of both a point-to-point call
and the failure of adding a leaf to a point-to-multipoint call.
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_addr_p
to the
atm_addr
structure of the endpoint that
is now active. |
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_addr_p
to the
atm_addr
structure of the endpoint that is down.
Use this notification for both point-to-point
and point-to-multipoint connections.
The convergence module receives exactly
one of these notifications for each endpoint associated with a VC (that is,
one notification for point-to-point VCs and one notification for each endpoint
of a point-to-multipoint connection). |
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_vc_p
for the
VC that has aged.
The convergence module may return either
ATM_AGER_OK
to allow the CMM to delete the VC or
ATM_AGER_RESET
to restart the aging timer and not to delete the VC. |
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
atm_esi
structure for the new ESI.
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
ATM_CAUSE_GOOD
if the new
ESI is accepted by the signaling module.
The signaling module does not need
to create the new PPAs immediately (and probably cannot), so the CMM will
not expect to have any new PPAs on return from this call.
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_drv_params
structure, do
not use those values.
Use only an ESI set with this exception value in the
creation of new PPAs. |
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. |
- arg
Specifies an additional
argument whose interpretation depends on the exception value.
Description
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.
Return Values
If a command has no explicit return value specified, it always returns
ATM_CAUSE_GOOD; otherwise, it returns one of the specified values.
Related Information
atm_cmm_register_cvg,
atm_cmm_register_sig
Section 6.3
for information on connection aging
Chapter 9
for more information on flow control in
the ATM subsystem
xxx_manage
NAME
xxx_manageSynopsis
atm_error_t xxx_manage(
int unit,
unsigned int command,
void *arg
);
Arguments
- unit
Specifies the
unit number to which the command applies.
- command
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
atm_vc
structure for the new VC.
This call cannot block.
The driver
allocates resources for the VC, but does not make the VC active.
The driver
uses the
queue
value to assign the VC to the indicated
queue (the driver should make no queue assignments other than those indicated
by the CMM).
The value of the
queue
member is in the range
of 0<=
queue
<=
maxqueue, where
maxqueue
is the number of queues the driver told the CMM it supports.
If the driver has insufficient resources to meet the QOS specified
for the VC, it must return a value other than
ATM_CAUSE_GOOD.
Note that the VPI and VCI in the
atm_vc_services
structure
are not necessarily valid at this time.
They become valid when the VC is
enabled.
This call gives the driver a chance to allocate resources for a
VC before the VC is set up on the network.
The connection operation cannot
proceed unless all the local resources needed for the new VC are allocated.
|
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.
|
- arg
Specifies any data
needed to perform the function.
Description
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.
Return Values
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.
Related Information
atm_cmm_error,
atm_cmm_register_dd
xxx_mmi
NAME
xxx_mmiSynopsis
int xxx_mmi(
void *handle,
unsigned int command,
void *arg,
int *retval,
struct ucred *cred
);
Arguments
- handle
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.
- command
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.
- arg
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.
- retval
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.
- cred
Specifies the
credentials or access information passed by the system to the CMM in the
ioctl
call.
Description
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 operating system
ioctl
call with the following exceptions:
Return Values
If the operation completes successfully, the
xxx_mmi
routine returns
ESUCCESS; otherwise, it returns an 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.
Related Information
atm_cmm_register_cvg,
atm_cmm_register_dd,
atm_cmm_register_sig
Chapter 7
for information on MMI and
ioctl
calls
xxx_receive
NAME
xxx_receiveSynopsis
void xxx_receive(
atm_vc_t *vc,
struct mbuf *mbp,
int length,
struct mbuf *trailer,
char pti,
char gfc
);
Arguments
- vc
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.
- mbp
Specifies a pointer
to a list of mbufs that contain the data received.
- length
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).
- trailer
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.
- pti
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.
- gfc
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.
Description
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.
Return Values
None
Related Information
atm_cmm_register_cvg,
xxx_endpt_receive
Section 2.4
for a description of ATM data formats
Chapter 3
and
Chapter 5
for information
on device drivers and convergence modules, respectively
xxx_release
NAME
xxx_releaseSynopsis
atm_error_t xxx_release(
atm_addr_p addr
);
Arguments
- addr
Specifies the
pointer to the
atm_addr
structure.
Description
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).
Return Values
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.
Related Information
atm_cmm_register_sig
xxx_restart
NAME
xxx_restartSynopsis
atm_error_t xxx_restart(
void *handle,
unsigned int class,
unsigned int vpi,
unsigned int vci
);
Arguments
- handle
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.
- class
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.
- vpi
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.
- vci
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.
Description
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.
Return Values
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.
Related Information
atm_cmm_register_sig,
atm_cmm_restart_ack
xxx_setup
NAME
xxx_setupSynopsis
atm_error_t xxx_setup(
atm_addr_p addr,
unsigned long *refptr
);
Arguments
- addr
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.
- refptr
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.
Description
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.
Return Values
The
xxx_setup
routine returns
ATM_CAUSE_GOOD
if the setup is proceeding or an ATM error number if the call cannot
proceed.
Related Information
atm_cmm_register_sig
xxx_xmit
NAME
xxx_xmitSynopsis
atm_error_t xxx_xmit(
int unit,
struct mbuf *data,
long length,
atm_vc_p vc,
unsigned char clp,
unsigned char gfc
);
Arguments
- unit
Specifies the
unit number on which to send the data.
- 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.
- length
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.
- vc
Specifies the VC
on which to send the data.
- clp
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.
- gfc
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.
Description
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.
Return Values
None
Related Information
atm_cmm_register_dd