4 Signaling Module Interface

The ATM subsystem signaling module interface enables signaling protocol modules to communicate with the ATM subsystem for connection management only. The primary signaling module provided with the base system is the UNI 3.0/3.1-compliant signaling module. However, you can add new signaling modules if the modules do not conflict with each other (such as in the use of well-known virtual circuits (VCs)). Once configured, any convergence module can use a signaling module on a per-call basis.

Note

New signaling modules should make no assumptions about which convergence modules use them, though the convergence modules may need to know about specific signaling modules.

The signaling module interface does not provide functions that allow the signaling module to exchange data with an ATM switch. To exchange data, signaling modules must also register as convergence modules for purposes of creating signaling VCs, usually permanent virtual circuits (PVCs), and of exchanging signaling data with the network.

The ATM signaling module interface enables signaling modules to:

Register the signaling module

Receive, reply to, activate, release, and delete connections

Restart a VC

Drop endpoints

Add and delete physical points of attachment (PPA)

Report a connection failure, a completed restart, a completed status enquiry, and Management Information Base (MIB) access

Request VC and endpoint status

This chapter describes each task, the function calls involved, and the relevant data structures that signaling module writers can use. Appendix A contains a reference page for each signaling module interface routine.

4.1 Registering the Signaling Module

When a signaling module is initialized, the module must use the atm_cmm_register_sig function call to register with the Connection Management Module (CMM). 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. See Section 6.6 for a description of signaling VC initialization.

4.2 Receiving a New Call

When a signaling module receives a new call, it uses the atm_cmm_new_call function call to notify 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.

4.3 Reporting a VC Activation

When a signaling module receives notification from the switch that a new connection has been completed and a new VC activated, the signaling protocol module uses the atm_cmm_reply function call to notify the CMM. The CMM passes the notification to the device driver and protocol convergence module.

This call notifies the CMM of both the activation of point-to-point connections and of the addition of endpoints in point-to-multipoint connections.

4.4 Activating a Connection

When a signaling module receives the necessary indication from the network that the circuit is connected, the signaling module uses the atm_cmm_activate_con function call to inform 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.

4.5 Reporting a Connection Failure

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 uses the atm_cmm_con_failed function call to notify the CMM of the call failure and the reason for the failure.

4.6 Releasing a Connection

When a signaling module receives a request to tear down a connection from the network or endpoint, the module uses the atm_cmm_con_release function call to notify the CMM that the connection will be released. 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.

4.7 Dropping an Endpoint

When a signaling module receives a request to drop an endpoint from a connection, the module uses the atm_cmm_ep_dropped function call to notify the CMM that the endpoint must be dropped. The CMM then 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.

4.8 Deleting a Connection

When a signaling module receives confirmation of a connection's release from the switch, the module uses the atm_cmm_con_deleted function call to notify 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.

4.9 Restarting a Virtual Circuit

When a signaling module receives a RESTART request, the module uses the atm_cmm_restart function call 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.

4.10 Reporting a Completed Restart

After the CMM requests a restart, the signaling module uses the atm_cmm_restart_ack function call to notify the CMM when the restart has completed. Once notified, the CMM returns the indicated VCs to the NULL state and frees their resources.

4.11 Reporting a Completed Status Enquiry

After the CMM requests a status enquiry of a VC, the signaling module uses the atm_cmm_status_done function call to notify the CMM when the enquiry has completed. Once notified, the CMM either examines the enquiry data itself or passes it to the convergence module that requested the enquiry.

4.12 Requesting Endpoint Information

Since signaling modules can receive messages for existing VCs at any time, the modules use the atm_cmm_findaddr function call 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 locking conventions are followed.

4.13 Adding a PPA

Signaling protocols usually perform some protocol registration-specific registration with the switch, including registering local addresses. When a signaling module creates a new address (creating a new PPA), the module uses the atm_cmm_new_ppa function call to inform the CMM that this new PPA exists. A convergence module can use the PPA to make and receive calls.

For example, when a UNI 3.0/3.1 signaling module is informed of a new address prefix, through the Integrated 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.

4.14 Deleting a PPA

When a signaling protocol, in cooperation with a switch, deletes an address from the list of recognized addresses on an interface, it uses the atm_cmm_del_ppa function call to inform 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 can 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).

See Section 2.5.1 for more information on PVC PPAs.

4.15 Requesting VC Status

When a signaling module needs to access status information about a VC that is currently in service, based on the virtual path identifier (VPI) and virtual channel identifier (VCI), it calls the atm_cmm_vc_get function call. The call returns a reference to a VC.

4.16 Using the atm_sig_params Structure

The CMM needs to know the capabilities and entry points of each signaling module. Signaling modules use the atm_sig_params structure to pass this information to the CMM as part of the atm_cmm_register_sig function call. To allow for future expansion of the atm_sig_params structure, the signaling module should call the bzero command to insert nulls into the entire structure before filling in the known fields.

Example 4-1 shows the atm_sig_params structure definition.

Example 4-1: The atm_sig_params Structure Definition

struct atm_sig_params {
        atm_error_t (*sig_setup)(atm_addr_p addr,
                unsigned long *refptr);
        atm_error_t (*sig_release)(atm_addr_p addr);
        atm_error_t (*sig_add)(atm_addr_p addr);
        atm_error_t (*sig_drop)(atm_addr_p addr);
        atm_error_t (*sig_enquery)(atm_addr_p addr);
        atm_error_t (*sig_restart)(void *handle,
                unsigned int class,
                unsigned int vpi,
                unsigned int vci);
        atm_error_t (*sig_exception)(void *sig_handle,
                unsigned int exception,
                void *arg);
        int (*sig_mmi)(void *sig_handle,
                int command,
                void *arg,
                int *retval,
                struct ucred *cred);
        atm_error_t (*sig_mib)(void *sig_handle,
                atm_ppa_p ppa,
                atm_mib_request_t command,
                atm_mib_var_p request);
        void *reserved1;
        void *reserved2;
        void *reserved3;
};

4.16.1 The sig_setup Member

The sig_setup member specifies a pointer to a routine that the CMM calls to request the creation of a new connection (make a call).

4.16.2 The sig_release Member

The sig_release member specifies a pointer to a routine that the CMM calls to request the deletion of a connection (a hangup).

4.16.3 The sig_add Member

The sig_add member specifies a pointer to a routine that the CMM calls to request the addition of an endpoint to a point-to-multipoint connection.

4.16.4 The sig_drop Member

The sig_drop member specifies a pointer to a routine that the CMM calls to request the dropping of an endpoint to a point-to-multipoint connection.

4.16.5 The sig_enquery Member

The sig_enquery member specifies a pointer to a routine that the CMM calls to request status for an endpoint.

4.16.6 The sig_restart Member

The sig_restart member specifies a pointer to a routine that the CMM calls to request a RESTART message be sent.

4.16.7 The sig_exception Member

The sig_exception member specifies a pointer to a routine that CMM uses to notify the signaling module of errors and exception conditions.

4.16.8 The sig_mmi Member

The sig_mmi member specifies a pointer to a routine that CMM uses to manage the signaling module through the ATM Module Management Interface (MMI). A signaling module must supply an xxx_mmi routine if it is to be managed through the MMI.

4.16.9 The sig_mib Member

The sig_mib member is reserved, and must be initialized to zero.

4.16.10 The reserved1, reserved2, and reserved3 Members

The reserved1, reserved2, and reserved3members are reserved for future use, and should be specified as NULL.