![[Return to Library]](BOOKSHELF.GIF)
![[Contents]](TOC.GIF)
![[Previous Chapter]](REW.GIF)
![[Next Section]](NEXT.GIF)
![[Next Chapter]](FF.GIF)
![[Index]](INDEX.GIF)
![[Help]](HELP.GIF)
This appendix contains a description of each of the routines described in this guide, in reference-page format. The routines are in alphabetical order.
Accepts a previously deferred call and informs the CMM that the call should be accepted
atm_error_t atm_cmm_accept
(atm_addr_p
addr,
atm_vc_services_t
give
);
The atm_cmm_accept routine is a convergence module interface that accepts a previously deferred incoming call, notifies the CMM, and sets the circuit resource parameters. The incoming call was deferred when a convergence module returned ATM_CAUSE_DEFER from its xxx_connect routine.
Typically, the determination is done within a set period of time, as defined by the signaling protocol, before the calling party times out on the call request.
The connection is not established and ready for use until the convergence module receives the appropriate exception notifications.
If connection setup is proceeding, atm_cmm_accept returns ATM_CAUSE_GOOD; otherwise, it returns an ATM error number that indicates the reason the call failed. If the call fails, the convergence module should remove any reference to the call.
Section 7.2 for information on accepting connections
![[Previous Section]](PREV.GIF)
Informs the CMM that a connection is ready to carry data
atm_error_t atm_cmm_activate_con
(atm_sig_handle_t
sm,
atm_addr_t
*addr);
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.
Note
Do not make this call before circuit connection.
If the indicated connection is found on the system no matter what the result of the operation, atm_cmm_activate_con returns ATM_CAUSE_GOOD. If the indicated connection is not found, an error value is returned indicating that the signaling module should release the connection since the CMM has no reference to it.
atm_cmm_con_release, xxx_setup, xxx_add
Section 7.4 for information on releasing connections
Creates a VC and establishes a connection to the first endpoint
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
);
The atm_cmm_add routine is a convergence module interface that adds endpoints to an existing point-to-multipoint connection. You can add endpoints at any time only to connections that were created with the ATM_CT_PTM flag set.
See Example B-2 for a code example of the atm_cmm_add routine.
If the endpoint add is proceeding, the atm_cmm_add function 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. The 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.
Chapter 7 for information on connections
Allocates memory for and initializes the atm_addr structure
atm_addr_p
atm_cmm_alloc_addr();
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 function call with the value returned from atm_cmm_alloc_addr to free memory.
See Section B.1 for a code example of the atm_cmm_alloc_addr routine.
If storage cannot be allocated, a NULL is returned; otherwise, a pointer to the allocated memory is returned.
Chapter 7 for information on connections
Allocates memory for and initializes the atm_uni_call_ie structure
atm_uni_call_ie_p atm_cmm_alloc_ie
(int
num_ie);
The atm_cmm_alloc_ie routine is a convergence module interface that allocates memory for the atm_uni_call_ie structure and initializes the structure members.
Typically, the convergence protocol module frees all UNI signaling structures associated with a VC when the VC is destroyed. However, under some error conditions (such as when a convergence module is allocating a series of structures and one allocation fails) the allocating module (either the convergence or signaling module) might have to free memory it has allocated. Convergence modules should not free memory for this structure if the atm_cmm_connect or related call succeeds because the CMM will free the memory.
See Section B.1, Section B.2, and Section B.3 for code examples of the atm_cmm_alloc_ie routine.
If storage cannot be allocated, a NULL is returned; otherwise, a pointer to the allocated memory is returned.
Chapter 7 for information on connections
Allocates memory for and initializes an atm_vc_services structure
atm_vc_services_p
atm_cmm_alloc_services();
The atm_cmm_alloc_services routine is a signaling and convergence module interface that allocates memory for the atm_vc_services structure and initializes the structure members to default values for best-effort available bit rate (ABR) service. Once allocated, other ATM modules can change the atm_vc_services structure as needed.
Typically, the CMM frees the atm_vc_services structure associated with a VC when the VC is destroyed. However, under some error conditions (such as when a convergence module is allocating a series of structures and one allocation fails), the allocating module might need to free memory it has allocated. In these cases, modules call the atm_cmm_free_services routine with the value returned from atm_cmm_alloc_services to free memory.
See Section B.1 for a code example of the atm_cmm_alloc_services routine.
If storage cannot be allocated, a NULL is returned; otherwise, a pointer to the allocated memory is returned.
Chapter 7 for information on connections
Queries parameters from a bind
unsigned long atm_cmm_bind_info
(atm_bind_handle_t
handle,
atm_bind_info_t
it);
| Value | Meaning |
| ATM_BIND_INFO_HANDLE | Returns the convergence module's bind handle, which the convergence module supplied at the time it created the NSAP 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 NSAP 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 it's allocation granularity. |
| ATM_PPA_ALLOCLIMIT | Returns a type of atm_bw_granularity_p, which reflects the underlying interface's per-VC bit rate limits, expressed in allocation granularity units. |
| ATM_PPA_AVAILRES | Returns a type of atm_services_granes_p, which reflects the amount of bandwidth (in granularity units) currently available for new CBR and pacing circuits over the underlying interface. |
| ATM_PPA_BRESVLIM | Returns the user-configurable limit, expressed as a percentage of backward bandwidth, on CBR circuits. |
| ATM_PPA_ESI | Returns the ESI that the signaling module supplied when the PPA was created. |
| ATM_PPA_ESIID | Returns the unique ESI identifier assocated with PPA's ESI. |
| ATM_PPA_ESILEN | Returns the length of the ESI that the signaling module supplied when the PPA was created. |
| ATM_PPA_ESIPID | Returns the ESI identifier of the PPA's parent ESI. |
| ATM_PPA_FRESVLIM | Returns the user-configurable limit, expressed as a percentage of forward bandwidth, on CBR and pacing circuits. |
| ATM_PPA_INFO_BURST_AVAIL | Returns the available burst cell rate in cells-per-second. This is the amount of burst cell rate that is available to be reserved by a convergence module. |
| ATM_PPA_INFO_BURST_MAX | Returns the maximum burst cell rate supported by the interface in cells-per-second. |
| ATM_PPA_INFO_CAPABILITIES | Returns the driver's capabilities for that interface. |
| ATM_PPA_INFO_DID | Returns a unique global value that can be used to reference the driver for the underlying interface. |
| ATM_PPA_INFO_DNAME | Returns the name of the driver for the underlying interface. |
| ATM_PPA_INFO_DUNIT | Returns the driver's unit number for underlying interface. |
| ATM_PPA_INFO_FC | Returns a nonzero value if hardware flow control is currently enabled on the interface. |
| ATM_PPA_INFO_HARD_MTU | Returns the largest PDU (in bytes) that the interface supports. This is valid only for interfaces that support AAL5 or AAL3/4 SAR functions in hardware. |
| ATM_PPA_INFO_HI_VCI | Returns the highest value that may be used for a VCI on the interface. |
| ATM_PPA_INFO_HI_VPI | Returns the highest value that may be used for a VPI on the interface. |
| ATM_PPA_INFO_ID | Returns a unique global value for referencing the PPA. Each PPA gets assigned a unique ID when it is created. An application program can use this value to specify a bind point (atmconfig uses these values to reference bind points). The returned value is 32-bits wide. |
| ATM_PPA_INFO_MAX_VCI | Returns the maximum number of VCIs that the interface supports. |
| ATM_PPA_INFO_MAX_VPI | Returns the maximum number of VPIs that the interface supports. |
| ATM_PPA_INFO_MEDIA | Returns a value that indicates the type of physical media to which the interface is connected. The return value is of the type atm_media_type_t. |
| ATM_PPA_INFO_PEAK_AVAIL | Returns the available peak cell rate (in cells-per-second). This is the amount of peak cell rate that is available to be reserved by a convergence module. |
| ATM_PPA_INFO_PEAK_MAX | Returns the maximum peak cell rate (in cells-per-second) that the interface supports. |
| ATM_PPA_INFO_QUEUES | Returns the number of scheduling queues that the driver has made visible to the CMM. |
| ATM_PPA_INFO_SNAME | Returns the name of the signaling module that created the PPA. |
| ATM_PPA_INFO_SUST_AVAIL | Returns the available sustainable cell rate (in cells-per-second). This is the amount of sustainable cell rate that is available for a convergence module to reserve. |
| ATM_PPA_INFO_SUST_MAX | Returns the maximum sustainable cell rate (in cells-per-second) that the interface supports. |
| ATM_PPA_INFO_TOTAL_VC | Returns the maximum number of VCs that can be opened on the interface at any given time. |
| ATM_PPA_INFO_TYPE | Returns a value that indicates the underlying interface type. The returned value is of the type atm_interface_t. |
| ATM_PPA_INFO_UNI | Returns the UNI type associated with the PPA, which the signaling module supplied at the time the PPA was created. The return value is of the type atm_uni_type_t. |
| ATM_PPA_INFO_VC_LEFT | Returns the number of unopened VCs on the interface at the time of the call. This is the total number of VCs (the value returned by ATM_PPA_INFO_TOTAL_VC) minus the number of VCs currently opened. |
| ATM_PPA_MAX_VC_BBW | Returns the user-configurable maximum per-VC backward (incoming) bit rate (in allocation granularity units) permitted over the underlying interface. |
| ATM_PPA_MAX_VC_FBW | Returns the user-configurable maximum per-VC forward (outgoing) bit rate (in allocation granularity units) permitted over the underlying interface. |
| ATM_PPA_MAXRES | Returns a type of atm_services_granes_p, which reflects the maximum bandwidths available for CBR and pacing circuits over the underlying interface. These bandwidths (expressed in granularity units) are a function of the interface limits and the user-configurable limits on the percentage of bandwidth available to CBR and pacing circuits. |
| ATM_PPA_NUM_VCI | Returns the current number of VCI's configured on the underlying interface. |
| ATM_PPA_NUM_VPI | Returns the current number of VPI's configured on the underlying interface. |
| ATM_PPA_PEAK_CELLRATE | Returns the peak PDU bit rate (in cells-per-second) for the underlying interface. |
| ATM_PPA_UNUSEDRES_BACK | Returns the amount of backward (incoming) bandwidth (in cells-per-second) currently reserved for, but not yet applied to, CBR circuits. |
| ATM_PPA_UNUSEDRES_FWD | Returns the amount of forward (outgoing) bandwidth (in cells-per-second) currently reserved for, but not yet applied to, CBR and pacing circuits. |
The atm_cmm_bind_info interface is a convergence module interface that queries the CMM for current information about an interface's physical capabilities (such as its bit rates) and the amount of specific resources left available on an interface (the remaining nonreserved sustainable bit rate). The CMM and device drivers keep track of this information.
Since convergence modules normally deal with either PPAs or NSAP bindings, the CMM allows convergence modules to query the information from the underlying interface by specifying the bind directly. Thus, the convergence module requires no specific knowledge of any device driver or device driver-related structures.
If an invalid query is made, atm_cmm_bind_info returns a value of 0.
atm_cmm_del_ppa, atm_cmm_new_ppa, atm_cmm_ppa_bind, atm_cmm_ppa_info
Section 4.4.1.15 for information on driver capabilities
Notifies the CMM that a connection does not exist
atm_err_t atm_cmm_con_deleted
(atm_sig_handle_t
sm,
atm_addr_p
addr
);
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 addition of parties in point-to-multipoint connections.
If the endpoint referenced is invalid, the atm_cmm_con_deleted function returns ATM_CAUSE_EIR to indicate that it has no previous entry for the connection; otherwise, it returns ATM_CAUSE_GOOD.
atm_cmm_activate_con, atm_cmm_con_release, xxx_add, xxx_setup
Section 7.4.2 for information on releasing connections
Notifies the CMM of a call failure
atm_error_t atm_cmm_con_failed
(atm_sig_handle_t
sm,
atm_addr_t
*addr
);
The atm_cmm_con_failed routine is a signaling module interface. When the CMM makes a connection request to a signaling module, the call to the remote system might fail for some reason. Since call creation is an asynchronous operation, the signaling module might encounter errors during call processing after the xxx_setup call has returned. In these cases, the signaling module notifies the CMM of failures both of point-to-point connections and of additional endpoints in point-to-multipoint connections. In the case of the failure of endpoints in a point-to-multipoint connection, the addr pointer points to the atm_addr structure of the added endpoint.
If the endpoint referenced is invalid, the function returns ATM_CAUSE_EIR to indicate that it has no previous entry for the connection; otherwise, it returns ATM_CAUSE_GOOD.
Section 7.1 for information on setting up connections
Notifies the CMM that a connection will be released
atm_error_t atm_cmm_con_release
(atm_sig_handle_t
sm,
unsigned long
reference
atm_ppa_p
ppa
);
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, not to drop a single endpoint from a connection. When this function is called, the CMM makes the connection unavailable for transmission, initiates the teardown of the referenced connection and all associated endpoints, and awaits notification that the VC has been torn down.
If the endpoint referenced is invalid, the atm_cmm_con_release function returns ATM_CAUSE_EIR to indicate that it has no previous entry for the connection; otherwise, it returns ATM_CAUSE_GOOD.
atm_cmm_activate_con, atm_cmm_con_deleted
Section 7.4 for information on releasing connections
Requests a connection to a remote system
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
);
| Connection | Meaning |
| ATM_CT_PTM | Specifies that the connection is the first connection in a point-to-multipoint connection. |
| ATM_CT_PTP | Specifies that the connection is a point-to-point connection only. |
| ATM_CT_PVC | Specifies that the connection is a permanent virtual circuit. |
The atm_cmm_connect routine is a convergence module interface that requests the CMM to create a connection to a remote system. This initiates the exchanges between the network and the remote host to create a new connection. The convergence module must specify all connection parameters to the CMM; these parameters are required to create the new connection.
By requesting a connection to a remote host, the convergence module owns the VC; the VC's ownership cannot be changed. The convergence module is notified of all incoming data and exceptions on the VC. Also, the convergence module is the only module that can transmit data on the VC.
To create a PVC, set the type argument to ATM_CT_PVC, set the calling argument to the atm_ppa_p for the PVC PPA, and set the params argument to the circuit parameters for the new PVC; the called and aging arguments are ignored.
If the system cannot provide the level of service specified in the params argument, the appropriate error is returned. No parameter negotiation is done for PVCs.
See Section B.1 for a code example of the atm_cmm_connect routine.
If the call is proceeding, the atm_cmm_connect function 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.
Section 6.22.2 for information on the atm_cmi_addr union
Section 7.3 for information on connection aging
Section 7.5 for information on PVC creation
Deletes an ATM address
atm_err_t atm_cmm_del_esi
(atm_cvg_handle_t, atm_esi_handle_t);
The atm_cmm_del_esi routine is a convergence module interface that deletes an ATM address. A convergence module uses this routine when it no longer needs a new address it has created. Only the convergence module that registered the address can unregister the address.
Deleting 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.
None
Notifies the CMM that a deleted PPA is invalid
atm_error_t atm_cmm_del_ppa
(atm_sig_handle_t
sm,
atm_ppa_p
ppa
);
The atm_cmm_del_ppa routine is a signaling module interface. When a signaling protocol, in cooperation with a switch, deletes an address from the list of recognized addresses on an interface, the signaling module calls this routine to notify the CMM that the deleted PPA associated with the address is no longer valid. The CMM then informs convergence modules bound to the PPA that the address is no longer valid and initiates a teardown of all VCs associated with the address.
All PPAs, except for the PVC PPAs, are owned by a signaling module. That is, a signaling module is always responsible for the creation and deletion of a PPA. This is required since the registration of addresses with a switch is handled entirely by signaling protocols. Also, PPAs may be deleted because of actions on the network that are completely unrelated to the local system. Because of this, the CMM does not automatically delete PPAs when an interface is taken down or loses its connection to the switch. The CMM responds to an interface shutdown by deleting the PVC PPA. Signaling modules will delete PPAs when it is appropriate for their protocols to do so (such as when they lose communications with the switch).
Upon successful completion, the atm_cmm_del_ppa function returns ATM_CAUSE_GOOD; otherwise, it returns an ATM error number.
atm_cmm_new_ppa, atm_cmm_ppa_bind, atm_cmm_ppa_info
Drops a connection to an endpoint
atm_err_t atm_cmm_drop
(atm_cvg_handle_t
cm,
atm_addr_t
*addr
);
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 function to manage multipoint VCs; you can also use it to initiate the teardown of point-to-point VCs.
If the endpoint teardown is proceeding, the atm_cmm_drop function 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.
Requests that connection state information for an endpoint be updated
atm_err_t atm_cmm_enquery
(atm_cvg_handle_t
cm,
atm_addr_t
*ep
);
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 function may be called any time a connection is active.
If the enquiry is initiated, the atm_cmm_enquery function 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.
Notifies the CMM to drop an endpoint
atm_err_t atm_cmm_ep_dropped
(atm_sig_handle_t
sm,
unsigned long
reference,
long
epreference,
atm_ppa_p
ppa
);
The atm_cmm_ep_dropped routine is a signaling module interface. A signaling module calls this routine when the module receives a request to drop an endpoint from a connection. This notifies the CMM to drop endpoints in a multipoint connection. The endpoint must already exist on the system.
The CMM notifies the convergence module that owns the endpoint's VC that the endpoint has been dropped and deletes the endpoint. If the last endpoint associated with a VC is dropped, the CMM initiates the release of the VC.
If the endpoint referenced is invalid, the atm_cmm_ep_dropped function returns ATM_CAUSE_EIR to indicate that it has no previous entry for the connection; otherwise, it returns ATM_CAUSE_GOOD.
Reports errors to the CMM
void atm_cmm_error
(atm_drv_handle_t
driver,
int
error,
atm_vc_t
*vc
);
| 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 value 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 value 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 value argument is the number of the queue that is being enabled (0 <= value < 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 value argument is a pointer to the failed VC. |
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.
None
Chapter 10 for information on flow control in the ATM subsystem
Requests endpoint and VC information from the CMM
atm_addr_p atm_cmm_findaddr
(long
call_reference,
long
endpoint,
atm_ppa_p
ppa
);
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 ENQUERY request, all the information necessary to format the STATUS reply is in the atm_addr structure. This routine returns a reference to the structure, enabling the signaling module to extract the data needed to format the reply.
Upon successful completion, the atm_cmm_findaddr call returns a pointer to the atm_addr structure for the specified endpoint. Signaling modules can use this information to find the atm_vc structure, if necessary. If the specified endpoint is not found, the CMM returns NULL.
Frees memory allocated to atm_addr structures
void atm_cmm_free_addr
(atm_addr_p
addr);
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 function call with the value returned from atm_cmm_alloc_addr to free memory.
None.
Frees memory allocated to IE structures
void atm_cmm_free_ie
(atm_uni_call_ie_p
u);
The atm_cmm_free_ie routine is a convergence module interface that convergence modules use to free IE structure memory that they have allocated.
See Section B.1 for a code example of the atm_cmm_free_ie routine.
None.
Frees memory allocated to atm_vc_services structures and releases reserved resources
atm_error_t atm_cmm_free_services
(atm_vc_services_p
s);
The atm_cmm_free_services routine is a convergence module interface that convergence modules use to free memory that they have allocated. Typically, the CMM frees the atm_vc_services structure associated with a VC when the VC is destroyed. However, under some error conditions (such as when a convergence module is allocating a series of structures and one allocation fails), the allocating module might need to free memory it has allocated. In these cases, modules call the atm_cmm_free_services routine with the value returned from atm_cmm_alloc_services to free memory.
A convergence module can also use the atm_cmm_free_services call to free a resource reservation or to terminate a resource reservation request (See Section 7.1 for more information.) The atm_cmm_free_services call frees the atm_vc_services_t memory and releases its reserved resources, if any.
If the CMM is able to free the memory and any reserved resources, the atm_cmm_free_services call returns ATM_CAUSE_GOOD. If the services structure is associated with a resource that is in the process of being released, the call returns ATM_CAUSE_BUSY. If the convergence module inadvertently attempts to free an atm_vc_services_t that is attached to an active connection, ATM_CAUSE_BUSY is also returned.
atm_cmm_alloc_services, atm_cmm_reserve_resources, xxx_except
Section 6.2.1 for information on convergence module exception handling.
Notifies the CMM of the completion of a MIB access
atm_error_t atm_cmm_mib_response
(void
*id,
unsigned int
fieldlen,
unsigned char
*fieldval
);
The atm_cmm_mib_response routine is a signaling module interface. Sometimes a signaling module's MIB access function call can block because of the need to contact some other network management entity. When the signaling module returns from the MIB access call, the module calls this routine to notify the CMM of the completion of a MIB access and report any retrieved values.
Upon successful completion, the atm_cmm_mib_response call returns ATM_CAUSE_GOOD; otherwise, it returns an ATM error number.
Notifies CMM of a connection request
enum atm_err
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
);
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 function call is nonblocking and returns with an indication about the disposition of the call.
The CMM evaluates the call parameters and determines if the call should be accepted. If the call is accepted, this function call 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 function returns an ATM error number indicating the reason and fills in the Cause IE information with the appropriate cause codes in the atm_addr structure pointed to by the addr argument. If you use a non-UNI 3.0 signaling module, the signaling module can deduce the nature of the reason for call rejection from the ATM error number returned and ignore the cause values. (Be aware that the errnos will not be as precise as the UNI 3.0 cause values.) 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.
Section 7.2 for information on receiving connections
Registers an ATM address with the network
atm_esi_handle_t atm_cmm_new_esi
(
atm_cvg_handle_t
cvg_handle,
unsigned char
*esi,
int
esilen,
atm_ppa_p
driver,
void
*arg
);
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 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 the registration process is proceeding, the atm_cmm_new_esi function returns a handle for the new ESI; otherwise, it returns a NULL.
atm_cmm_del_esi, atm_cmm_ppa_bind
Notifies the CMM that a new PPA exists
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
);
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 signaling module is informed of a new address prefix, through the Interim Local Management Interface (ILMI), that has been created on the switch, the module combines the new prefix with existing end system identifiers (ESIs) to form a new set of addresses for the new prefix. Then, the signaling module tells the CMM about each of these new addresses.
Upon successful completion, the atm_cmm_new_ppa function returns a valid PPA pointer for the new PPA; otherwise, it returns NULL.
atm_cmm_del_ppa, atm_cmm_ppa_bind, atm_cmm_ppa_info
Creates a kernel thread for use by an ATM module
thread_t atm_cmm_new_thread
(task_t
task,
void(*)(void * arg)
*first,
void
*arg,
int
pri
int
maxpri
);
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 function combines many of the Digital UNIX thread primitives to provide an easier interface for ATM modules.
Upon successful completion, the atm_cmm_new_thread function returns a pointer to a thread structure that is used to reference the thread in all subsequent calls to kernel thread routines. If a thread could not be created, it returns NULL.
See Section 3.8.4 for a description of ATM thread creation.
Passes OAM cells to the CMM
void atm_cmm_oam_receive
(atm_drv_handle_t
driver,
struct mbuf
*mbp,
atm_vc_t
*vc,
);
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.
None
Section 3.5.3 for information on how data are carried
Binds a convergence module to a PPA
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)
);
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 network services access point (NSAP) associated with the bound convergence module. The NSAP and the bind point identify the service on the network and local system. Convergence modules will be informed only of incoming calls on PPAs to which they have bound and can place calls only through a bind point. The CMM handles calls only to NSAPs. If the NSAP specified by the called party address of an incoming call does not exist, the CMM rejects the call.
By binding to a PPA, a convergence module is creating an NSAP and uniquely identifying its service on the network. Once this is done, incoming calls can be routed to the convergence module, and the convergence module can make outgoing calls. All call activity is directed at a bind point, and thus, 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 NSAP address, or it may allow the CMM to assign it a selector value. In both cases, the selector value must specify a unique endpoint on the PPA.
Note that a convergence module can bind to up to 256 times to a PPA (as long as all its selector values are unique), and may bind to as many PPA's as is necessary to provide its service.
Upon successful completion, the atm_cmm_ppa_bind function returns a value that the convergence module uses to reference the bind point; otherwise, it returns a NULL. Typically, bind failure occurs for the following reasons: insufficient memory, the PPA is no longer valid, the selector value specified is in use, or there are no free selectors available.
atm_cmm_bind_info, atm_cmm_del_ppa, atm_cmm_new_ppa, atm_cmm_ppa_info, atm_cmm_ppa_unbind, xxx_connect
Section 3.6 for information on PPAs and NSAPs
Queries parameters from a PPA
unsigned long atm_cmm_ppa_info
(atm_ppa_p
ppa,
atm_bind_info_t
it);
| Value | Meaning |
| 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_PPA_ALLOCGRANE | Returns a type of atm_bw_granularity_p, which reflects the underlying interface's units of bandwidth allocation or its allocation granularity. |
| ATM_PPA_ALLOCLIMIT | Returns a type of atm_bw_granularity_p, which reflects the underlying interface's per-VC bit rate limits, expressed in allocation granularity units. |
| ATM_PPA_AVAILRES | Returns a type of atm_services_granes_p, which reflects the amount of bandwidth (in granularity units) currently available for new CBR and pacing circuits over the underlying interface. |
| ATM_PPA_BRESVLIM | Returns the user-configurable limit, expressed as a percentage of backward bandwidth, on CBR circuits. |
| ATM_PPA_ESI | Returns the ESI that the signaling module supplied when the PPA was created. |
| ATM_PPA_ESIID | Returns the unique ESI identifier assocated with PPA's ESI. |
| ATM_PPA_ESILEN | Returns the length of the ESI that the signaling module supplied when the PPA was created. |
| ATM_PPA_ESIPID | Returns the ESI identifier of the PPA's parent ESI. |
| ATM_PPA_FRESVLIM | Returns the user-configurable limit, expressed as a percentage of forward bandwidth, on CBR and pacing circuits. |
| ATM_PPA_INFO_BURST_AVAIL | Returns the available burst cell rate (in cells-per-second). This is the amount of burst cell rate that is available for a convergence module to reserve. |
| ATM_PPA_INFO_BURST_MAX | Returns the maximum burst cell rate (in cells-per-second) that the interface supports. |
| ATM_PPA_INFO_CAPABILITIES | Returns the driver's capabilities for that interface. |
| ATM_PPA_INFO_DID | Returns a unique global value that can be used to reference the driver for the underlying interface. |
| ATM_PPA_INFO_DNAME | Returns a pointer to a character string that is the name of the driver for the underlying interface. |
| ATM_PPA_INFO_DUNIT | Returns the unit number of the driver for the underlying interface. |
| ATM_PPA_INFO_FC | Returns a nonzero value if hardware flow control is currently enabled on the interface. |
| ATM_PPA_INFO_HARD_MTU | Returns the largest PDU (in bytes) that the interface supports. This is valid only for interfaces that support AAL5 or AAL3/4 SAR functions in hardware. |
| ATM_PPA_INFO_HI_VCI | Returns the highest value that may be used for a VCI on the interface. |
| ATM_PPA_INFO_HI_VPI | Returns the highest value that may be used for a VPI on the interface. |
| ATM_PPA_INFO_ID | Returns a unique global value for referencing the PPA. Each PPA is assigned a unique ID when it is created. An application program can use this value when specifying a bind point (atmconfig uses these values to reference bind points). The returned value is 32-bits wide. |
| ATM_PPA_INFO_MAX_VCI | Returns the maximum number of VCIs that the interface supports. |
| ATM_PPA_INFO_MAX_VPI | Returns the maximum number of VPIs that the interface supports. |
| ATM_PPA_INFO_MEDIA | Returns a value that indicates the type of physical media to which the interface is connected. The return value is of the type atm_media_type_t. |
| ATM_PPA_INFO_PEAK_AVAIL | Returns the available peak cell rate (in cells-per-second). This is the amount of peak cell rate that is available for a convergence module to reserve. |
| ATM_PPA_INFO_PEAK_MAX | Returns the maximum peak cell rate (in cells-per-second) that the interface supports. |
| ATM_PPA_INFO_QUEUES | Returns the number of scheduling queues that the driver has made visible to the CMM. |
| ATM_PPA_INFO_SNAME | Returns a pointer to a character string containing the name of the signaling module that controls all SVCs created on the PPA. If the PPA is a PVC PPA, the returned value is NULL. |
| ATM_PPA_INFO_SUST_AVAIL | Returns the available sustainable cell rate (in cells-per-second). This is the amount of sustainable cell rate that is available for a convergence module to reserve. |
| ATM_PPA_INFO_SUST_MAX | Returns the maximum sustainable cell rate (in cells-per-second) that the interface supports. |
| ATM_PPA_INFO_TOTAL_VC | Returns the maximum number of VCs that can be opened on the interface at any given time. |
| ATM_PPA_INFO_TYPE | Returns a value that indicates the underlying interface type. The returned value is of the type atm_interface_t. |
| ATM_PPA_INFO_UNI | Returns the UNI type associated with the PPA, which the signaling module supplied at the time the PPA was created. The return value is of the type atm_uni_type_t. |
| ATM_PPA_INFO_VC_LEFT | Returns the number of unopened VCs on the interface at the time of the call. This is the total number of VCs (the value returned by ATM_PPA_INFO_TOTAL_VC) minus the number of VCs currently opened. |
| ATM_PPA_MAX_VC_BBW | Returns the user-configurable maximum per-VC backward (incoming) bit rate (in allocation granularity units) permitted over the underlying interface. |
| ATM_PPA_MAX_VC_FBW | Returns the user-configurable maximum per-VC forward (outgoing) bit rate (in allocation granularity units) permitted over the underlying interface. |
| ATM_PPA_MAXRES | Returns a type of atm_services_granes_p, which reflects the maximum bandwidths available for CBR and pacing circuits over the underlying interface. These bandwidths (expressed in granularity units) are a function of the interface limits and the user-configurable limits on the percentage of bandwidth available to CBR and pacing circuits. |
| ATM_PPA_NUM_VCI | Returns the current number of VCI's configured on the underlying interface. |
| ATM_PPA_NUM_VPI | Returns the current number of VPI's configured on the underlying interface. |
| ATM_PPA_PEAK_CELLRATE | Returns the peak PDU bit rate (in cells-per-second) for the underlying interface. |
| ATM_PPA_UNUSEDRES_BACK | Returns the amount of backward (incoming) bandwidth (in cells-per-second) currently reserved for, but not yet applied to, CBR circuits. |
| ATM_PPA_UNUSEDRES_FWD | Returns the amount of forward (outgoing) bandwidth (in cells-per-second) currently reserved for, but not yet applied to, CBR and pacing circuits. |
The atm_cmm_ppa_info routine is a convergence module interface that queries the CMM for current information about an interface's physical capabilities (such as its bit rates) and the amount of specific resources left available on an interface (the remaining nonreserved sustainable bit rate). The CMM and device drivers keep track of this information.
Since convergence modules normally deal with either PPAs or NSAP 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.
None
atm_cmm_bind_info, atm_cmm_del_ppa, atm_cmm_new_ppa, atm_cmm_ppa_bind, atm_cmm_ppa_unbind
Section 4.4.1.15 for a description of the capabilities member of the atm_drv_params structure
Unbinds convergence module service from a PPA
atm_error_t atm_cmm_ppa_unbind
(
atm_bind_handle_t
bind_handle);
The atm_cmm_ppa_unbind routine is a convergence module interface that unbinds a convergence module's service from a PPA. A convergence module uses this routine when it does not want to accept an incoming connection or to make outgoing calls, for example, a module awaiting a call from a specific caller. Typically, convergence modules should unbind a PPA if their service is no longer available, and must unbind before unregistering with the CMM.
Removing a binding does not affect any currently open VCs.
Upon successful completion, the atm_cmm_ppa_unbind function returns ATM_CAUSE_GOOD; otherwise, it returns an ATM error number.
atm_cmm_bind_info, atm_cmm_del_ppa, atm_cmm_new_ppa, atm_cmm_ppa_bind, atm_cmm_ppa_info
Presents received data to the CMM
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
);
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.
None
Section 3.5.3 for information on the mbuf chain
Section 4.2 for information on receiving OAM cells
Registers a convergence module with the CMM
atm_cvg_handle_t atm_cmm_register_cvg
(long
version,
char *const
name,
void
*cvg_handle,
void
(*const
xxx_receive
)(atm_vc_p
vc,
struct mbuf
*mdp,
int
length,
struct mbuf
*trailer,
char
pti,
char
gfc),
atm_error_t
(*const
xxx_except
)(void
*handle,
unsigned int
exception,
void
*arg),
int
(*const
xxx_mmi
)(void
*handle,
unsigned int
command,
void
*arg,
int
*retval,
struct ucred
*cred)
);
The atm_cmm_register_cvg 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.
This function returns a unique value that identifies an instance of the convergence module. The convergence module must use this value on all subsequent calls to the CMM.
atm_cmm_unregister_cvg, xxx_except, xxx_mmi, xxx_receive
Chapter 8 for information on the MMI
Registers a device driver with the CMM
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)
);
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 before returning from the attach.
Upon successful completion, atm_cmm_register_dd returns atm_drv_handle_t. The driver uses this handle in all subsequent calls to the CMM; otherwise, it returns NULL.
Section 3.5.3 for information on the mbuf chain
Chapter 4 for more information on the device driver interface and the atm_queue_param structure
Chapter 8 for more information on the MMI
Registers the signaling module with the CMM
atm_sig_handle_t atm_cmm_register_sig
(long
version,
char *const
id,
void
*sig_handle,
atm_error_t
(*const
xxx_setup
)(atm_addr_p
addr,
unsigned long
*refptr),
atm_error_t
(*const
xxx_release
)(atm_addr_p
addr),
atm_error_t
(*const
xxx_add
)(atm_addr_p
addr),
atm_error_t
(*const
xxx_drop
)(atm_addr_p
addr),
atm_error_t
(*const
xxx_enquery
)(atm_addr_p
addr),
atm_error_t
(*const
xxx_restart
)(void
*handle,
unsigned int
class,
unsigned int
vpi,
unsigned int
vci),
atm_error_t
(*const
xxx_except
)(void
*handle,
unsigned int
exception,
void
*arg),
int
(*const
xxx_mmi
)(void
*handle,
unsigned int
command,
void
*arg,
int
*retval,
struct ucred
*cred),
atm_error_t
(*const
xxx_mib
)(void
*sig_handle,
unsigned int
command,
atm_oid_p
oid,
unsigned int
fieldlen,
unsigned char
*fieldval,
void
*id)
);
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.
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.
None
xxx_add, xxx_drop, xxx_enquery, xxx_except, xxx_mib, xxx_mmi, xxx_release, xxx_restart, xxx_setup
Section 7.6 for a description of signaling VC initialization
Chapter 8 for a discussion of the MMI
Rejects an incoming call and notifies the CMM
void atm_cmm_reject
(atm_addr_p
addr);
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.
None
atm_cmm_accept, atm_cmm_new_call
Requests that a virtual circuit be disconnected
atm_err_t atm_cmm_release
(atm_cvg_handle_t
cm,
atm_vc_t
*vc
);
The atm_cmm_release 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 disconnected (referenced by an atm_addr structure) or that a VC be disconnected. These operations are equivalent on point-to-point connections; disconnecting only the endpoint results in the VC being torn down. If a convergence module requests that a point-to-multipoint VC be disconnected, the CMM first disconnects all endpoints associated with the VC. This task simplifies the task of disconnecting multipoint VCs and for disconnecting PVCs.
For an SVC, if the connection teardown is proceeding, the atm_cmm_release function 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 function 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.
Notifies the CMM that a virtual circuit has been activated
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
);
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 a new connection has been completed and a new VC activated or ready to carry data. You use this call to notify the CMM of both the activation of point-to-point connections and of the addition of endpoints in point-to-multipoint connections. The CMM passes the notification to the device driver and protocol convergence module.
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.
Since this function call is notifying the CMM that a previously referenced endpoint is not active, it can fail only if the endpoint 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.
Reserves resources for CBR and pacing services
atm_err_t
atm_cmm_reserve_resources
(atm_ppa_p
ppa,
atm_cvg_handle_t
cm,
atm_vc_services_p
s
);
The atm_cmm_reserve_resources routine is a convergence module interface. Convergence modules use this routine to reserve bandwidth resources and notify the CMM before making a call or accepting a connection. The CMM passes the notification to the device driver and protocol convergence module.
This function returns ATM_CAUSE_GOOD, if the CMM was able to allocate and reserve the necessary resources.
This function 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, this function returns an ATM error number indicating 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.
Notifies the CMM that a RESTART request was received
atm_err_t atm_cmm_restart
(atm_sig_handle_t
sm,
unsigned int
class,
unsigned int
vpi,
unsigned int
vci
);
The atm_cmm_restart is a signaling module interface. When a signaling module receives a RESTART request, the module calls this routine to pass all the appropriate information to the CMM. The CMM then initiates a restart of the indicated VC(s) before returning to the signaling module.
If the restart is successfully initiated, the atm_cmm_restart returns ATM_CAUSE_GOOD; otherwise, it returns an appropriate ATM error number.
atm_cmm_new_call, atm_cmm_restart_ack
Notifies the CMM that a restart has completed
void atm_cmm_restart_ack
(void
*handle,
unsigned int
class,
unsigned int
vpi,
unsigned int
vci
);
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.
None
Transmits data on an established virtual circuit
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
);
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 function call does not imply that the data was actually transmitted. In fact, the data could be discarded in the driver or on the network. The convergence module is not notified if the data is dropped locally.
If the data is successfully passed to the driver and the driver accepts the data, the atm_cmm_send function 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.
Section 3.5.3 for more information on the mbuf chain
Chapter 10 for information on flow control in the ATM subsystem.
Notifies the CMM that a ststus enquiry is completed
void atm_cmm_status_done
(atm_addr_p
addr);
The atm_cmm_status_done routine is a signaling module interface that signaling modules call to notify the CMM when a status enquiry is completed. Once notified, the CMM either examines the enquiry data itself or passes it to the convergence module that requested the enquiry.
None
Unregisters a convergence module from the CMM
atm_error_t atm_cmm_unregister_cvg
(
atm_cvg_handle_t
cm);
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 deconfigured from the system.
Before unregistering, a convergence module must close all existing connections and unbind from all PPAs. If all connections are not closed or if PPA bindings still exist, the CMM unregisters only the convergence module's connection routine. The CMM will continue to call the convergence module with incoming data and exception notifications. Once the convergence module is unregistered, the CMM does not call any of its routines.
If the convergence module is completely unregistered and the CMM will make no more calls to its routines, the atm_cmm_unregister_cvg call returns ATM_CAUSE_GOOD. If there are still connections associated with the convergence module, it returns ATM_CAUSE_BUSY. This means the module's xxx_connect routine is unregistered, but the CMM will continue to deliver data and exception notifications. Once the convergence module unregisters, the CMM will not accept any more connection requests from the module until it reregisters. The convergence module must make the unregister call again once all existing connections are closed.
Modifies virtual circuit parameters
atm_err_t atm_cmm_vc_control
(atm_cvg_handle_t
cm,
atm_vc_t
*vc,
int
operation,
void
*arg
);
| Operation | Meaning |
| ATM_VCC_AGING | Changes the circuit-aging algorithm applied to the VC. For this operation, arg is an int whose value is the new aging parameter (see Table 7-1 for a list of values). |
| ATM_VCC_QPARAM | Sets the queuing parameters for queuing raw calls in the driver. The argument to this operation is an atm_queue_param_p that points to a properly set atm_queue_param structure. This structure is referenced only within the context of the function call and may be a local variable in the calling function. |
The atm_cmm_vc_control routine is a convergence module interface that enables convergence modules to modify virtual circuit parameters, either to make the transfer of data more efficient or to control the VC aging. The QOS and circuit bandwidth parameters cannot be modified.
Upon successful completion, the atm_cmm_vc_control function call returns ATM_CAUSE_GOOD; otherwise, it returns an ATM error number.
Section 4.4.2 for information on the atm_queue_param structure
Section 7.3 for information on connection aging
Requests status information from a virtual circuit
atm_vc_p atm_cmm_vc_get
(atm_drv_handle_t
driver,
unsigned int
vpi,
unsigned int
vci
);
The atm_cmm_vc_get routine is a signaling module interface. When a signaling module needs to access status information about a VC that is currently in service, based on the VPI and VCI, the module calls this routine.
If the VC is currently configured on the system, the atm_cmm_vc_get function returns a pointer to that atm_vc structure; otherwise, it returns NULL.
atm_cmm_status_done, atm_cmm_vc_stats
Retrieves current VC information from the CMM
atm_error_t atm_cmm_vc_stats
(atm_vc_p
vc,
atm_vc_stats_p
stats
);
The atm_cmm_vc_stats routine is a convergence module interface that retrieves virtual circuit statistics from the CMM. The CMM returns the information in the atm_vc_stats structure.
The CMM keeps track of VC usage on a per-VC basis. This is done as part of the CMM's VC management and cannot be disabled.
No entity can reset the VC counters. If a convergence module needs to collect statistics between two events, it must query the statistics at the first event and the second event and subtract the first event's statistics from the second event's statistics.
Upon successful completion, the atm_cmm_vc_stats function returns ATM_CAUSE_GOOD; otherwise, it returns an ATM error.
atm_cmm_vc_control, atm_cmm_vc_get
Requests a signaling module to add an endpoint to a point-to-multipoint connection
atm_error_t xxx_add
(atm_addr_p
addr);
The xxx_add routine is a function 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 function (xxx_add) can be any valid C language function name. You pass the function 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 added.
This function 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.
Notifies a convergence module of a connection request
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);
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, only the forward and backward MTU sizes can be negotiated. No other circuit parameters can be modified.
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 choose to 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), and the backward (local system receive) rate can be greater than or equal to the requested rate (to ensure that local system can receive at least as much as the sender contracted to send).
The convergence modules can impose exact bit-rate matching, if necessary. The convergence module can change negotiable parameters by changing *avail, as for non-CBR circuits. If the supplied reserved resource cannot be applied to the call, the convergence module receives an ATM_CME_EP_DEAD exception notification; the VC cause information indicates the reason for the failure.
For CBR circuits, if the *avail argument is not NULL, the CMM was able to allocate the bandwidth resources necessary to establish a CBR connection. The convergence module can change negotiable parameters, as with non-CBR circuits. The convergence module also has the option of replacing the CMM-allocated resources with reserved resources held by the convergence module by setting *avail to the address of the reserved resources services structure. Restrictions on bit-rate matching still apply.
The xxx_connect routine is a function declared within a convergence module that the CMM calls to notify the convergence module of a connection request. The CMM calls the convergence module that is bound to the selector specified in the called party address.
The name of the function (xxx_connect) can be any valid C language function name. The function 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 function for both point-to-point and point-to-multipoint connections.
Connections are not shared between convergence modules at the bind point. If convergence modules must share connections, one module must own the connection and coordinate access to the connection with another module. Alternatively, modules could be layered on top of a multiplexor that assumes ownership of the connection.
If the convergence module rejects the call, the CMM and signaling module release the VC and notify the calling party that the call was rejected. The CMM never accepts a call without the explicit consent of a convergence module.
PVCs created by the atmconfig utility must have a convergence module specified since it is not possible for convergence modules to determine if they should accept a PVC call.
When the atmconfig utility creates a new PVC, the convergence module to which it belongs receives the connection notification. For PVCs, the myaddr argument points to the PVC PPA, the vc argument references the new atm_vc structure, and the requested argument references the new PVCs circuit parameters. The addr, reply, and avail arguments are NULL. Convergence modules cannot change or reject PVC circuit parameters; the system does not create the PVC unless it can provide the requested level of service as specified by the creator of the PVC.
When a convergence module accepts a connection, it can assume that the connection exists and that it will receive notifications if the connection is destroyed. It is free to use its private structure members in the atm_vc structure referenced in the atm_addr structure.
When a connection is accepted, it is not yet ready to carry data. The convergence module must not attempt to transmit data until it is notified that the connection is active. However, it should be ready to receive data since data can arrive ahead of the activation notification.
See Section B.3 for a code example of the xxx_connect routine. In the example, new_connect is the name of the routine.
If the convergence module accepts the connection, it should return ATM_CAUSE_GOOD. If the convergence module cannot immediately accept the connection (for example, if negotiation is needed with upper-level protocols or a user-level process), it must not block. It should return ATM_CAUSE_DEFER. Returning ATM_CAUSE_DEFER causes no immediate action to be taken on the connection since the ATM protocols allow some time for the called party to reply. When the convergence module makes a determination about the disposition of the call, it must communicate this to the CMM by using either the atm_cmm_accept or atm_cmm_reject calls. If the convergence module rejects the call, it must return an ATM error number other than ATM_CAUSE_GOOD or ATM_CAUSE_DEFER.
If a convergence module needs to change any MTU size in the atm_vc structure referenced by the give argument, the module must do this before returning ATM_CAUSE_DEFER.
atm_cmm_accept, atm_cmm_ppa_bind, atm_cmm_reject
Requests a signaling module to drop an endpoint in a point-to-multipoint connection
atm_error_t xxx_drop
(atm_addr_p
addr);
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 function (xxx_drop) can be any valid C language function name. The function 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.
This function 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.
Requests a signaling module to obtain status for an endpoint
atm_error_t xxx_enquery
(atm_addr_p
addr);
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 function (xxx_enquery) can be any valid C language function name. You pass the function to the CMM by reference only.
This function call is nonblocking. When the query response arrives, the signaling module uses a function call to notify the CMM.
This function must return ATM_CAUSE_GOOD if the signaling module is proceeding with the enquiry or an ATM error number if the call cannot proceed.
Reports exceptions, errors, and system configuration changes to convergence and signaling modules
int xxx_except
(void
*handle,
unsigned int
exception,
void
*arg);
| 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 command is the convergence module's bind handle, which it passed to the atm_cmm_ppa_bin call. 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 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_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 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_ADD_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 through this exception 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. |
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 function (xxx_except) can be any valid C language function name. You pass the function to the CMM by reference only.
Exception notifications have the following characteristics:
If a command has no explicit return value specified, it always returns ATM_CAUSE_GOOD; otherwise, it returns one of the specified values.
atm_cmm_register_cvg, atm_cmm_register_sig
Section 7.3 for information on connection aging
Chapter 10 for more information on flow control in the ATM subsystem
Instructs a device driver to perform some driver management functions
atm_error_t xxx_manage
(int
unit,
unsigned int
command,
void
*arg;)
| 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 ENOBUFS. 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 for the VC to be activated. The driver takes the VPI and VCI
values from the
atm_vc_services
structure referenced in the
atm_vc
structure.
This call is made only after a VC is set up on the network and can become 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. |
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 function (xxx_manage) can be any valid C language function name. You pass the function to the CMM by reference only.
If the function is completed successfully, the driver returns ATM_CAUSE_GOOD; otherwise, the driver returns an ATM error number indicating the cause of the failure.
atm_cmm_error, atm_cmm_register_dd
Requests MIB information from a signaling module
atm_error_t xxx_mib
(void
*sig_handle,
unsigned int
command,
atm_oid_p
oid,
unsigned int
fieldlen,
unsigned char
*fieldval,
void
id);
The xxx_mib routine is a function declared within a signaling module that the CMM calls to access fields of MIBs maintained by the signaling module. This function is provided only when a signaling module maintains a MIB. The values of MIB fields are returned through a call to atm_cmm_mib_response.
The name of the function (xxx_mib) can be any valid C language function name. You pass the function to the CMM by reference only.
The xxx_mib function call cannot block.
If the value is available immediately, atm_cmm_mib_response is called from within the signaling module's xxx_mib function and ATM_CAUSE_GOOD is returned. If the MIB value must be queried, ATM_CAUSE_DEFER must be returned and atm_cmm_mib_response called when the query is complete and the value is available. If a MIB set operation cannot be completed immediately, the signaling module must return ATM_CAUSE_DEFER and call atm_cmm_mib_response when the access has been completed. An error is indicated by returning the appropriate ATM error number.
Section 5.17 for a description of the atm_oid structure
Connects a convergence, device driver, or signaling module to the MMI
int xxx_mmi
(void
*handle,
unsigned int
command,
void
*arg,
int
*retval,
struct ucred
*cred
);
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 function (xxx_mmi) can be any valid C language function name. You pass the function to the CMM by reference only.
The xxx_mmi routine is called from within a system call context with no external locks held. It has access to the per-process data structures and user address space of the calling process. If necessary, the xxx_mmi routine can block as long as it does not hold simple locks while blocking.
If a module does not require any external management or configuration capabilities, it does not have to register a management function with the CMM.
This interface follows the standard Digital UNIX ioctl call with the following exceptions:
If the operation completes successfully, the xxx_mmi routine returns ESUCCESS; otherwise, it returns a Digital UNIX error number as defined in sys/errno.h. In addition, for successful completions modules can use the retval pointer to pass the return value from the ioctl system call to the calling program.
atm_cmm_register_cvg, atm_cmm_register_dd, atm_cmm_register_sig
Chapter 8 for information on MMI and ioctl calls
Passes incoming data to a convergence module
void xxx_receive
(atm_vc_t
*vc,
struct mbuf
*mbp,
int
length,
struct mbuf
*trailer,
char
pti,
char
gfc
);
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 function (xxx_receive) can be any valid C language function name. You pass the function to the CMM by reference only.
When designing receive functions, 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 function must not block.
None
Section 3.5 for a description of ATM data formats
Chapter 4 and Chapter 6 for information on device drivers and convergence modules, respectively
Requests a signaling module to tear down a connection
atm_error_t xxx_release
(atm_addr_p
addr);
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 function (xxx_release) can be any valid C language function name. You pass the function 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 function call 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).
This function must return ATM_CAUSE_GOOD if the circuit deletion is completed or an ATM error number if the circuit deletion fails.
Requests a signaling module to send a restart message
atm_error_t xxx_restart
(void
*handle,
unsigned int
class,
unsigned int
vpi,
unsigned int
vci);
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 function (xxx_restart) can be any valid C language function name. You pass the function to the CMM by reference only.
The xxx_restart function must return ATM_CAUSE_GOOD if the signaling module is proceeding with the restart or an ATM error number if the call cannot proceed.
atm_cmm_register_sig, atm_cmm_restart_ack
Notifies a convergence module of the result of a registration operation
atm_error_t xxx_receive
(void
*arg,
atm_esi_handle_t
esi,
atm_error_t
errno);
The xxx_result routine is a function declared within a convergence module that the CMM calls to report the result of the registration operation. The name of the function (xxx_result) can be any valid C language function name. You pass the function to the CMM by reference only.
This function is called when the final result of the address's registration process has been obtained, and called only if atm_cmm_new_esi returns a valid ESI handle.
None
Notifies a device driver that the CMM has data to transmit
atm_error_t xxx_setup
(atm_addr_p
addr,
unsigned long
*refptr);
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 function (xxx_setup) can be any valid C language function name. You pass the function 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 function call is nonblocking, and is used only to set up point-to-point connections or the first connection in a point-to-multipoint connection.
This function returns ATM_CAUSE_GOOD if the setup is proceeding or an ATM error number if the call cannot proceed.
Notifies a device driver that the CMM has data to transmit
atm_error_t xxx_xmit
(int
unit,
struct mbuf
*data,
long
length,
atm_vc_p
vc,
unsigned char
clp,
unsigned char
gfc);
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 function (xxx_xmit) can be any valid C language function name. You pass the function to the CMM by reference only.
The xxx_xmit function call 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.
None