![[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 chapter describes the following ATM features that writers of ATM device drivers, signaling modules, and protocol convergence modules can use:
When building kernel modules to interface with the Digital UNIX ATM subsystem, your application must include the following header files (located in the /usr/include/io/atm directory):
In addition, the protocol convergence module code must include any signaling protocol-specific module header files that define structures used by protocol convergence modules.
The atm/atm.h header file defines all the global data structures as well as the revision level of these structures. The ATM_REVISION constant, which is defined in this file, is passed to the CMM by device drivers, signaling modules, and convergence modules during their registration process. The CMM uses this constant to determine which version of global structures the modules use; it should not be changed.
![[Previous Section]](PREV.GIF)
The kernel data file (/sys/data/atm_data.c) is supported in Digital UNIX Version 4.0 for backward compatibility only and will not be supported in future releases. Therefore, Digital recommends that all ATM modules use the standard kernel module configuration manager to configure module initialization routines and module tunable parameters.
All ATM modules should use the standard Digital UNIX configuration management interface for initializing and configuring modules. This interface also provides the sysconfig utility, which allows you to tune ATM modules without having to use a data file or recompile code. See Writing Device Drivers: Tutorial and sysconfig(8) for information on the Digital UNIX configuration management interface and sysconfig utility, respectively. See Chapter 11 and System Tuning and Performance Management for information on tuning the ATM subsystem.
The /usr/sys/include/io/atm/sys/atm.h header file contains ATM-specific error codes that are returned by all modules within the ATM subsystem to indicate the result of an operation. These codes consist of standard User-Network Interface (UNI) 3.0/3.1 error numbers and error numbers specific to Digital UNIX.
When a function call is completed with no errors, the function must return the value ATM_CAUSE_GOOD. Unsuccessful completion is indicated by the return of some other value. Only the values listed in the atm.h header file can be returned. Routines returning error codes to system calls or management routines must return standard Digital UNIX error codes as defined in the sys/errno.h file.
All ATM subsystem routines use type atm_error_t to indicate the outcome of an operation and all ATM subsystem modules must also do so. An atm_error_t can take on one of the values listed in atm.h. The ATM signaling modules are responsible for translating values to external network representations when necessary.
The type of data transmitted and received on a virtual circuit (VC) depends on the type of ATM Adaption Layer Protocol (AAL) the convergence module specifies when setting up the VC.
The type of data a convergence module and the CMM exchange depends on the Segmentation and Reassembly (SAR) capabilities of the underlying device driver and hardware adapter. Convergence modules must be prepared either to handle drivers of differing capabilities or to recognize a driver that does not support the capabilities required by the convergence module. The convergence module interfaces provide a mechanism for convergence modules to obtain a driver's capabilities for making this determination.
Some device drivers or adapters implement some SAR functions in hardware or in a combination of hardware and software. This makes sending and receiving specific types of data more efficient. For example, TURBOchannel and Peripheral Component Interconnect (PCI) ATM adapters implement AAL5 in hardware. Other hardware may implement AAL3/4 or may be able to handle only raw ATM cells. Since the Digital UNIX ATM subsystem is designed to accommodate a wide variety of drivers, it provides mechanisms for dealing with drivers of varying capabilities. It is the convergence module's responsibility to use the capabilities of a driver or an ATM interface in the best way possible for the protocol it is implementing.
The Digital UNIX ATM subsystem can handle the following types of ATM data:
If a convergence module needs to transmit raw ATM cells, it should first determine if the underlying driver supports this service (some drivers may support only cooked data). If the driver cannot handle raw cells, the convergence module should not make or accept connections over the interface controlled by the driver. The convergence module should use the driver only if the driver provides compatible capabilities.
If a convergence module needs to transmit cooked data (data packets, such as AAL5, rather than individual cells), it should first determine if the underlying driver supports this service (some drivers may support only raw data or may not cook the data in the needed AAL format). The convergence module should use the driver if the driver provides compatible capabilities. If a driver does not support the required capabilities, but does support raw cells, the convergence module can perform the SAR functions internally and then send and receive raw cells. Otherwise, the convergence module should not accept or make connections over the interface controlled by the driver.
Both cell and packet data in the ATM subsystem are carried in a chain of mbufs. The routines for allocating and manipulating the mbufs are the same as those the Digital UNIX networking subsystem uses. The data representation within the mbuf chain depends on the type of data (raw or cooked) being carried by the mbufs. When an mbuf chain contains raw cells, each mbuf in the chain contains exactly one ATM cell, a full 53-byte cell with Generic Flow Control (GFC) and Payload Type Indicator (PTI) bits set.
An mbuf chain can contain one or more ATM cells, each in its own mbuf. When an mbuf chain is carrying packet Protocol Data Units (PDUs) (AAL3/4 or AAL5 PDUs), the mbuf chain will contain exactly one packet PDU. On outgoing packets, the number of bytes in the packet must be less than or equal to the maximum transmission unit (MTU) of the VC on which the packet is transmitted. The mbuf chain must contain the appropriate headers and trailers (the AAL3/4 or AAL5 Convergence Sublayer Protocol Data Unit (CS-PDU) headers and trailers). If the device driver or adapter adds headers and trailers, the driver must strip off this extra information on outgoing packets. The drivers must include the CS-PDU headers and trailers on received packets.
When a driver receives raw ATM cells, the driver must be capable of optionally time-stamping the incoming cells to assist convergence modules or other protocol modules in determining intercell intervals; this might be required when processing continuous bit rate (CBR) or variable bit rate (VBR) traffic. If a convergence module enables time-stamping of incoming data, the device driver must add an 8-byte time-stamp immediately after the cell bytes in the mbuf, increasing the mbuf length to 61 bytes.
On Digital UNIX systems, the time-stamp is the value read from the free-running system clock at the time the packet was received by the driver. This value has a 10-nanosecond resolution, but the value is accurate to only a few microseconds. This is because the time-stamp is not generated by the hardware when the packet arrives, but by the driver during its receive interrupt processing.
The driver can also optionally indicate lost or corrupted cells in the data stream. Cell loss can be due to hardware errors, the failure of cyclical redundancy checks (CRC), or insufficient resources to hold the incoming cell. The actual cause of local cell loss can vary between drivers. To indicate a lost cell in the data stream, the driver should insert a 0 length mbuf in the data stream where the cell was lost. Only one of these needs to be inserted if multiple sequential cells are lost. If time-stamping is enabled, the lost cell indicator will be an 8-byte mbuf with the time-stamp indicating the temporal position of the lost cell. The protocol convergence module can use this information for clock recovery, if necessary.
The physical point of attachment (PPA) is a network services endpoint. It is the point at which the network services are provided and to which network services users attach to the network services. Each PPA represents a unique addressable entity on the network, identifying a provider of network services on both the local system and the network. When a call is placed on an ATM network, only the PPA is addressed; the PPA's address is registered with the ATM switch.
Although the network can address the PPA through the PPA address, the network cannot use the same address to address individual network services users attached to the PPA. For this, the ATM network uses network services access points (NSAPs). An NSAP uniquely identifies both the network services endpoint and a specific network services user attached to that endpoint.
UNI 3.0/3.1 NSAP-format ATM addresses consist of the following parts:
The first two parts together are registered with the ATM switch and network, and uniquely identify a PPA to which network services users may attach. Both the host and the switch must combine these two pieces of information to form complete addresses. This is done through the Interim Local Management Interface (ILMI) protocol when new addresses are added or deleted. The CMM, in cooperation with signaling modules, keeps track of these two parts so that all addresses associated with either a prefix or an ESI are properly managed. Since the prefix is assigned by the switch, the CMM leaves the management of the prefixes up to the address registration and management portion of the signaling module.
ESI values have the following sources:
The first two ESIs are considered global or public ESIs. All PPAs created from global ESIs are available to all convergence modules. Only the system or network administrator can delete global ESIs. ESIs that convergence modules create are considered private. All PPAs created from private ESIs are available only to the convergence module that configured the ESI on the system. These ESIs can be deleted by either the system or network administrator or by the creating convergence module. The CMM keeps track of ESI sources (in the atm_esi structure) to assure that only the correct entity can remove an ESI (and all associated PPAs and the VCs associated with those PPAs).
Since ATM permits an arbitrary number of ESIs and prefixes to be registered for a specific connection to the network, an end system can have an arbitrary number of PPAs. Users of the ATM network services (convergence modules) can attach their service to any combination of PPAs to make their service available on the network. The process of attaching a service to a PPA is called binding, and creates a full NSAP that uniquely identifies a specific instance of a service on the network. In the Digital UNIX ATM architecture, all calls must be placed and received through bind points that represent valid NSAPS.
In the Digital UNIX ATM subsystem, PPAs are created whenever an address is successfully registered with the local network switch. When a PPA comes into existence, convergence modules are notified and may bind their services to the PPAs. Each PPA contains three pieces of information that uniquely identify it among the different networks to which the host may be attached. Associated with each PPA is a device driver (representing the physical connection to a network), a signaling module (representing the protocol that controls the administration of the PPA), and the PPA's address on the network to which it is attached. This permits PPAs on separate, disjoint networks to have the same logical address, but to still be unique on the local system.
The Digital UNIX ATM subsystem has two types of PPAs:
You can specify as many services for PVC connections as for SVC connections.
When an interface becomes active on a network, the CMM automatically creates a special PPA for use in connecting PVCs to network services users. A PVC PPA is a special PPA that has no network address and no associated signaling module. It represents a path between the network and a network services user. There is exactly one PVC PPA for each interface that is operational. PVC PPAs are destroyed only when a driver is taken down or unregistered with the CMM. PVC PPAs remain in place throughout network disruptions.
Since PVC PPAs have no associated address, you must decide how to bind a specific network services user to a PPA and how to uniquely identify the user on that PPA. Since PVCs are created locally either with the atmconfig administration command or by convergence modules, and do not have any identifying characteristic that is unique on the network, you can assign an arbitrary addressing scheme to PPA bindings. The only requirements are that each network services user be uniquely identifiable and that there be a large enough address space to accommodate as many services as all the SVC PPAs can bind. See atmconfig(8) for more information.
In the Digital UNIX ATM subsystem, a PVC bind point is identified not by an NSAP, but by values unique to each network services user (convergence module) that binds to a PVC PPA. These values are the convergence module's name (provided when the convergence module registers with the CMM) and a selector value used to specify a specific instance of a service on the convergence module. Thus, a PVC network services user is identified by a driver/convergence/selector tuple that identifies a specific instance of a specific service on a specific network. The selector space for PVC bind points is 31-bits wide and is local to each convergence module; each convergence module has complete control over the selector values used to access instances of its service. This provides a large enough bind space to enable convergence modules to create a PVC binding for every SVC binding and to accommodate both PVC and SVC access to its services.
When an ATM network interface is brought up, the signaling protocol that uses the interface must contact the local switch to register the end system with the network. For UNI 3.0/3.1, this involves exchanging addressing information with the switch to create full ATM addresses, minus the selector values. Each ATM address comprises a prefix value, which is assigned by the network, and an end system identifier (ESI), which identifies the end system. ATM permits the switch to assign an arbitrary number of prefixes and the end system to provide an arbitrary number of ESIs, within reason and subject to implementation-specific limitation. Each combination of prefix and ESI forms an ATM address, or a network services endpoint (PPA).
When an address is registered with a switch, the registering signaling module informs the CMM that a new network services endpoint exists. The CMM then creates a PPA for the new address and notifies each convergence module or the network services users of the new PPA so that they can create NSAP bindings, if necessary. Calls to remote systems are given the calling party number of the bind point and PPA through which the call is placed. Incoming calls are routed to bind points based on the called party's NSAP address. Therefore, all SVC activity must use a bind point as the local endpoint object. Calls received for an unbound NSAP are rejected, and no calls can be placed without first creating a bind point and calling party's NSAP.
The bind space for SVC PPAs is 8 bits long, the size of an NSAP selector. If a convergence module needs a larger binding space, it can create more PPAs to which it can bind additional instances of its services. A convergence module can create an SVC PPA for its private use by defining a new ESI to the system. By defining a new ESI, one or more new PPAs are created with the new ESI and the current prefixes provided by the switch. The Digital UNIX ATM subsystem recognizes PPAs made with ESIs created by a convergence module and makes the new PPAs available only to the module that created the ESI. This allows convergence modules to create their own address space on the ATM network.
ESIs taken from an adapter's ROM and ESIs created by using the atmconfig command are considered global. All resulting PPAs are not restricted to specific convergence modules. All other ESIs and their resulting PPAs are considered private.
When a driver is taken down or a connection to the network is lost, the CMM destroys all SVC PPAs, along with any bind points and VCs associated with the PPAs. If the connection to the network is reestablished, the signaling module must reregister all the ESIs; only the creator of the ESI or the system administrator, using the atmconfig command, can remove ESIs. The PPAs are then recreated. The convergence modules must bind to the new PPAs.
All modules that allocate memory for use in the ATM subsystems should use the same allocation mechanism. This enables the system to keep track of memory allocated for use by ATM and provides a consistent programming model. The following macros for allocating and freeing memory can be safely called in any context:
ATM_MALLOC(pointer,cast,size)
ATM_MALLOCW(pointer,cast,size)
ATM_FREE(pointer)
The ATM_MALLOC and ATM_MALLOCW macros allocate memory of at least size bytes. They place the address of the allocated memory into pointer, casting it with the type of cast. The allocated memory is correctly aligned for any operation.
The ATM_MALLOC macro does not block if the requested memory is not available, but returns NULL. You should use this macro in the majority of cases since any routine called by the ATM Subsystem is not allowed to block (except MMI calls).
The ATM_MALLOCW macro blocks until the requested memory is available. However, it can still return NULL if an error occurs during the allocation processing. Use this macro only in contexts that can block (system calls and private kernel threads). All memory allocated by these macros is mapped in kernel virtual memory and can be passed to any kernel function.
The ATM_FREE macro frees memory allocated previously by ATM_MALLOC. The value of pointer must be identical to that returned from the ATM_MALLOC macro. Once memory is freed, do not reference it again.
The macros return NULL if no memory is available. All modules must check the return value before dereferencing them to assure that memory was successfully allocated. Modules should also be prepared to handle situations where memory is not available; this should not be a fatal error.
The following code fragment shows how to use these macros:
struct my_struct *msp;
ATM_MALLOC(msp,struct my_struct *,sizeof(struct my_struct)); if(msp == NULL) { /* allocation failed */ return ATM_CAUSE_NOMEM; } /* use memory referenced by msp */ ATM_FREE(msp);
In Digital UNIX Version 4.0, the base ATM subsystem is SMP and realtime (RT) safe. The CMM is highly parallelized and supports fine-grain concurrency in all attached modules. ATM modules that are included with the base ATM subsystem are either parallelized or funnel to the master processor. Therefore, any user-created ATM module must be both SMP and RT safe. The module must at least use funneling to force the module to run on the master processor. The module can also use fine-grain concurrency and locking.
The following section provides a brief overview of locking as it applies to ATM modules. See Writing Device Drivers: Advanced Topics for a complete description of locking within the Digital UNIX kernel.
Because of the way in which the ATM subsystem operates, you should write all routines of any ATM module that is called by the CMM to execute on an interrupt stack. Many ATM functions execute either off a device interrupt, the system soft clock, or an internal ATM thread. This means that no ATM routine that the CMM calls can block (with the exception of the xxx_mmi routine described in Appendix A). Therefore, all locks must be nonblocking simple locks. You can use blocking locks only from within a module's private thread, or when in a system call context.
No ATM module should hold a simple lock when calling outside the module (in general, simple locks should be held the minimum amount of time). Thus, when calling any CMM routine or any other kernel routine, no locks should be held. When the CMM calls any module's routine, no CMM locks are held across the call.
Finally, before taking a simple lock, raise the processor priority to SPLIMP so that interrupts are blocked if the locking thread happens to be running on the master processor.
Modules that do not implement high levels of parallelism can implement one of the following locking methods (in increasing order of preference):
Coarse-grain locking uses one lock (or perhaps a few) to lock a large code path or an entire module. Avoid this type of locking because it requires that a simple lock be held for long periods of time, possibly causing all other processors to block while waiting on the lock. Also, if the lock is held through function calls outside the module, locking hierarchy violations or deadlocks could result.
Funneling forces the module's thread of execution onto a single CPU. Since the module runs only on the master, it is effectively running in a uniprocessor environment. Once funneled, all calls outside the module also run on the master processor even though the called routine may be parallelized. Funneling causes severe context switch overhead that adversely affects module, ATM, and system performance. This is because the module's thread is suspended on the slave and then placed in the master processor's scheduling queue.
To funnel a thread, place the unix_master() function call at the start of and the unix_release() function call at the end of the code block to be funneled. There must be a corresponding unix_release() call for every unix_master() call. You must account for this when designing error paths through a code block.
Creating a thread for the module and then queuing work to the thread is the preferred option. All the module's work is performed in the thread that can run on only one processor (any processor in a multiprocessor environment). Thus, within the thread's code path no locks are required. Only the queuing mechanism, which enqueues and dequeues requests to the thread, requires locking.
Using this strategy, all module routines that can be called from outside the module would allocate some queue structure, take the arguments to the routine along with some identifier to identify the routine that has been called, place them in this structure, and then enqueue the structure to a service queue (locking service queue access). Once the structure is enqueued, the module's thread would be scheduled through one of the thread-management calls. Then, when the thread is run, it would dequeue a request from the service queue (again, locking the service queue) and process the request in the thread's context. The thread would run until there were no more requests on the service queue. This does incur the overhead of a context switch on a uniprocessor system, but on a multiprocessor system the enqueuing could take place on one processor at the same time the thread is being run on another.
The ATM locking functions are really macros that invoke other macros, and are defined in the atm_osf.h file. The following sequence of steps lists the locking macros and the order in which you call them in your module:
atm_lock_info(,lock_info_name);
This declares the lock information structure and allocates storage for it. Lock information structures are declared as globals, so this macro should appear outside all functions. When creating a lock for structures that are dynamically allocated, you need only a single lock information structure that can be applied to all instances of the structure.
atm_lock_decl(lock_name)
Note
Do not put a semicolon at the end of the declaration.
This declares the lock and allocates storage for it. You can use the macro within a structure declaration or by itself in a global context.
atm_lock_setup(&lock_name,&lock_info_name);
Be sure to pass the address of the lock and lock information structures in this macro.
atm_lock(&lock_name);
Be sure to raise the processor priority immediately before taking the lock.
atm_unlock(&lock_name);
Be sure to lower the processor priority immediately after releasing the lock. Do not lower the processor priority while the lock is held.
atm_lock_terminate(&lock_name);
Once terminated, you can no longer use the lock unless you reinitialize it.
The following code fragment shows the sequence of calls in creating and using a lock:
atm_lock_decl(some_lock) atm_lock_info(,some_lock_info); int oldpri;
/* initialize the lock */ atm_lock_setup(&some_lock,&some_lock_info);
/* take the lock */ oldpri = splimp(); atm_lock(&some_lock);
/* release lock */ atm_lock(&some_lock); splx(oldpri);
/* terminate the lock when it will no longer be used */ atm_lock_terminate(&some_lock);
ATM modules can create kernel threads for the following reasons:
The Digital UNIX kernel provides many kernel thread primitives that modules are free to call directly. These are described in greater detail in Writing Device Drivers: Advanced Topics. However, to create a thread for use by an ATM module, the ATM subsystem provides the atm_cmm_new_thread function. This function combines many of the Digital UNIX thread primitives to provide an easier interface for ATM modules. See Appendix A for a description and format of this function.
The ATM subsystem supports the following circuits:
A circuit in which both end systems and the network dedicate the resources necessary to handle transmission and reception of the circuit's traffic at the specified bit rate. CBR circuits requiring end-to-end timing are not supported because the drivers and adapters do not support the AAL1 capability.
A circuit that allows convergence modules to specify that the local driver perform cell pacing on non-CBR circuits. It requires that the sending system dedicate resources to insure that traffic is injected onto the network at the specified bit rate. A pacing circuit has local significance only. To the network and target system, the pacing circuit is a best-effort ABR connection. You can use pacing circuits, for example, to limit the local host's transmission rate without having both end systems and the network treat the circuit as CBR.
The default best-effort ABR connections do not require the end systems to dedicate resources (such as bandwidth) to the connections. However, CBR and pacing connections require the end systems to dedicate resources to those connections. These resources can either be allocated transparently at the time the connection is made or received, or they can be reserved in advance by the sending or receiving convergence module and later applied to a connection setup or incoming call. See Section 7.1 and Section 7.2 for information on reserving resources for connections.
The following data structures are visible to all modules of the ATM subsystem and to the protocol convergence module:
The ATM subsystem uses these structures to keep track of information for each VC, such as VC service parameters, connection endpoint addresses, VC numbers, and traffic statistics. When a module other than the CMM must allocate memory for a structure, the CMM provides a function call or macro to allocate structure memory in a consistent manner, to properly initialize the structures, and to allocate the correct version of the structure. Module writers must not use any routines other than those that the CMM supplies to allocate structure memory. The following sections describe these data structures.
The ATM subsystem uses the atm_vc structure to reference a VC. A VC is the object on which data is sent and received. VCs are associated with exactly one local endpoint and one or more remote endpoints. An action performed on a VC usually affects all the endpoints associated with the VC. For example, transmitting data on a VC sends the data to all endpoints currently connected to the VC.
The atm_vc structure has the following characteristics:
When a module is first informed of the presence of a new connection, it receives a reference to an atm_addr structure for the connection endpoint. The atm_addr structure references the atm_vc structure for the connection. At this point, the module can use its private structure members in the atm_vc structure to hold information necessary to keep track of the VC and can use its private pointer structure members to store any information it requires.
When the VC is torn down and local resources are deallocated, the CMM calls each module to deallocate any resources associated with the VC. At this time, the module must zero out its atm_vc structure private members to signify that it no longer has any reference to the defunct VC. The CMM checks all the atm_vc private members before freeing the structure memory and prints a warning to the console if any private structure member is not 0.
Table 3-1 lists those member names of the atm_vc structure, with their associated data types, that modules might reference.
| Member Name | Data Type |
| conv_pp1 | void * |
| conv_pp2 | void * |
| sig_pp1 | void * |
| sig_pp2 | void * |
| drv_pp1 | void * |
| drv_pp2 | void * |
| vcs | atm_vc_services_p |
| call_reference | long |
| errno | atm_error_t |
| vci | int |
| vpi | int |
| ppa | atm_ppa_p |
| selector | int |
| direction | atm_direction_t |
The conv_pp1 and conv_pp2 members are pointers reserved for the use by convergence modules only; no other ATM module is permitted to use these structure members. Typically, a convergence module uses these members to reference local structures and resources associated with the connection that the atm_vc structure controls. However, convergence modules may use these fields in other ways.
The sig_pp1, sig_pp2, drv_pp1, and drv_pp2 members have corresponding meanings for ATM signaling protocol modules and ATM device drivers, respectively.
The vcs member is a pointer to an atm_vc_services structure that contains all the service parameters for the VC. The CMM sets this pointer.
Note
This member and any member of the structure that it references should never be written by any module other than the CMM.
The call_reference member is a unique call identifier assigned to the VC. This value is assigned only by the CMM and signaling protocol modules and must not be modified by any other module.
The errno member contains the last error number that was reported on the VC.
The vci and vpi members contain the virtual circuit's virtual path identifier (VPI) and virtual channel identifier (VCI) values. These are assigned by the CMM in cooperation with the signaling protocol module that set up the connection.
The ppa member indicates the PPA to which the VC belongs.
The selector member is the selector value assigned to the bind point to which the VC is attached. This value combined with the address information in the PPA form the full NSAP address.
The direction member provides information about the direction of the call. The CMM sets this member to one of the following:
This structure member is set only by the CMM and must not be modified by any other module.
The ATM subsystem uses the atm_addr structure to reference a connection endpoint. One atm_addr structure exists for every connection to every endpoint. Multiple endpoints and multiple address structures can be associated with a single VC (for example, point-to-multipoint connections). A pointer to this structure is the handle that the ATM subsystem uses to reference a specific connection endpoint.
The atm_addr structure has the following characteristics:
The structure may contain additional members for the internal use of the CMM. ATM modules should make no assumption about the actual length of the structure. Table 3-2 lists those members of the atm_addr structure, with their associated data types, that modules might reference.
| Member Name | Data Type |
| vc | atm_vc_p |
| address[20] | unsigned char |
| ton | unsigned char |
| anpi | unsigned char |
| subaddress[20] | unsigned char |
| subaddress_type | unsigned char |
| eprtype | unsigned char |
| endpoint | unsigned short |
| state | unsigned char |
| atm_error | atm_error_t |
| setup | void * |
| connect | void * |
| location | unsigned char |
| cause | atm_err_t |
| diag_length | unsigned char |
| diagnostic[27] | unsigned char |
| endstate | unsigned char |
| conv_p1 | void * |
| conv_p2 | void * |
| sig_p1 | void * |
| sig_p2 | void * |
The vc member references the atm_vc structure of the VC to which this endpoint belongs.
The address member is an array that contains the 20-byte ATM address of the endpoint.
The ton member is a value that specifies the endpoint's address type. These bits are identical to the type of number field in the Called Party Number information element (IE) (right justified).
The anpi member is the address or numbering plan identification information for the address. These bits are identical to those in the corresponding field of the Called Party Number IE.
The subaddress member is an array that contains the subaddress of the endpoint. If the endpoint has no subaddress, the American Flow Indicator (AFI) byte of the subaddress array must be 0.
The subaddress_type member is a numeric value that specifies the type of subaddress that the endpoint uses. These bits are identical to those in the Type of subaddress field of the Called Party Subaddress IE (right justified).
The eprtype member is the endpoint reference type of the endpoint referenced by the structure. Signaling modules fill in this information, indicating the type of endpoint contained in the endpoint structure member.
The endpoint member is the endpoint reference value that the ATM subsystem uses to reference an endpoint in a point-to-multipoint connection. The CMM assigns this value when processing point-to-multipoint connection requests.
The state member is the Call state value or global interface state value field from the last Call State IE received for the connection. Only the signaling module fills in this member.
The atm_error member contains the error number for the last error reported on the endpoint.
The setup member is a pointer to a signaling protocol-specific structure that contains the parameters sent or received in the call setup phase of connection creation. These parameters indicate the call parameters set by the calling party of a connection. On incoming calls (the local host is the called party), the signaling protocol module sets this member. On outgoing calls (the local host is the calling party), the protocol convergence module that initiates the call sets this member.
The protocol convergence module and the signaling module must agree on the format of the object referenced by this member. The protocol convergence module can free storage for the objects referenced only when the associated connection is torn down.
The connect member is a pointer to a signaling protocol-specific structure that contains the parameters sent or received in the connection phase of connection creation. These parameters indicate the actual parameters the ATM subsystem uses to establish the service between the endpoints. These could differ from the setup parameters in cases where parameter negotiation took place. Both sets of parameters are maintained so that any differences between requested and negotiated parameters can be easily determined.
The protocol convergence module and the signaling module must agree on the format of the object referenced by this member. The protocol convergence module can free storage for the objects referenced only when the associated connection is torn down.
The location, cause, diag_length, and diagnostic members are filled in by the CMM from the Cause IE received for the connection. Convergence modules can use this information to determine the reason for a call failure. The diagnostic array contains diag_length valid bytes taken from the Cause IE length field.
Only the signaling module fills in the endstate member as part of the enquiry processing.
The conv_p1 and conv_p2 members are reserved for use by convergence modules only; no other module may access these members. Typically, these members store state information associated with the endpoint.
The sig_p1 and sig_p2 members are reserved for use by signaling modules only; no other module may access these members. Typically, these members store state information associated with the endpoint.
No locking is required for access to this data structure. Since each module is permitted to modify only those fields assigned to it, there is no need to coordinate access to the entire structure with other modules. Access within a module may be locked if necessary.
One atm_addr structure is allocated by a protocol convergence module for each endpoint it calls and by signaling modules for each endpoint that calls the local host. Convergence and signaling modules use the atm_cmm_alloc_addr function call to allocate memory for the structure. The atm_cmm_alloc_addr call returns a valid pointer, if memory was successfully allocated and initialized; a NULL, if an error occurred. This is the only valid means to allocate memory for the structure.
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. Once the CMM accepts a connection request (either incoming or outgoing), only the CMM can free storage for this structure. See Appendix A for a description of the two routines.
Every connection on the system is allocated some amount of network resources (a portion of the network bandwidth). When a new connection is requested, the requester tells the ATM subsystem the type of physical resources required by the connection. The CMM ensures those resources are available and allocates them to the connection.
The CMM uses the atm_vc_services structure to keep track of connection resources and to inform the device drivers of the resources that must be allocated for a connection. The atm_vc_services structure has the following characteristics:
Table 3-3 lists those member names of the atm_vc_services structure, with their associated data types, that modules might reference.
| Member Name | Data Type |
| vc | atm_vc_p |
| fqos | atmqos_t |
| bqos | atmqos_t |
| fmtu | unsigned int |
| bmtu | unsigned int |
| valid_rates | unsigned int |
| fpeakcr[2] | unsigned int |
| bpeakcr[2] | unsigned int |
| fsustcr[2] | unsigned int |
| bsustcr[2] | unsigned int |
| fburstcr[2] | unsigned int |
| bburstcr[2] | unsigned int |
| flags | unsigned int |
| aal | atmaal_t |
| queue | unsigned int |
| bearer_class | unsigned int |
| lerrstat | enum atm_lerr_t |
| nerrstat | unsigned int |
| cmm_drv_handle | atm_drv_handle_t |
| drv_resource | void * |
| converge_handle | void * |
The vc member is a pointer to the VC structure for the connection.
The fqos and bqos members are the forward and backward quality of services (QOS) types, respectively. These indicate the QOS the caller is requesting for the connection. The following table lists the QOS values:
| Value | Meaning |
| ATM_QOS_CLASSA | Connection-oriented, constant bit rate (CBR) traffic with source or destination timing relationships. |
| ATM_QOS_CLASSB | Connection-oriented, variable bit rate (VBR) traffic with source or destination timing relationships. |
| ATM_QOS_CLASSC | Connection-oriented, variable bit rate (VBR) traffic with no timing relationships. |
| ATM_QOS_CLASSD | Connectionless, variable bit rate (VBR) traffic with no timing relationships. |
| ATM_QOS_CLASSX | Undefined bit rate traffic. |
| ATM_QOS_CLASSY | Available bit rate (ABR) traffic. |
| ATM_QOS_NONE | No specified quality of service. |
The fmtu and bmtu members are the forward and backward maximum transmission unit (MTU) size (in bytes), respectively. These indicate the maximum packet size that can be transmitted and received on the connection when the connection carries AAL3/4 or AAL5 data.
The valid_rates member is a bit mask that indicates which line rates have been specified and which have been left unspecified. The following table lists the value and meaning for this member:
| Value | Meaning |
| ATM_VCRV_FPEAK0 | Forward peak cell rate for CLP=0 |
| ATM_VCRV_FPEAK1 | Forward peak cell rate for CLP=1 |
| ATM_VCRV_BPEAK0 | Backward peak cell rate for CLP=0 |
| ATM_VCRV_BPEAK1 | Backward peak cell rate for CLP=1 |
| ATM_VCRV_FSUST0 | Forward sustainable cell rate for CLP=0 |
| ATM_VCRV_FSUST1 | Forward sustainable cell rate for CLP=1 |
| ATM_VCRV_BSUST0 | Backward sustainable cell rate for CLP=0 |
| ATM_VCRV_BSUST1 | Backward sustainable cell rate for CLP=1 |
| ATM_VCRV_FBURST0 | Forward burst cell rate for CLP=0 |
| ATM_VCRV_FBURST1 | Forward burst cell rate for CLP=1 |
| ATM_VCRV_BBURST0 | Backward burst cell rate for CLP=0 |
| ATM_VCRV_BBURST1 | Backward burst cell rate for CLP=1 |
The fpeakcr, bpeakcr, fsustcr, bsustcr, fburstcr, and bburstcr members are the arrays that contain the forward and backward peak, forward and backward sustainable, and forward and backward burst cell rates, respectively. These indicate the network bandwidth requested by the caller. The first element of each array specifies the value for cells that have the Connection Loss Priority (CLP) bit clear (CLP=0). The second element of each array specifies the value for cells that have the CLP bit set (CLP=1). Only certain combinations of these rates may be valid for a given signaling protocol or for a specific QOS type. Those rates that are explicitly specified are designated by setting the appropriate bit in the valid_rates member.
Note
To set a cell rate of 0, set the appropriate cell rate and mark it as valid; do not leave the cell rate unspecified.
The flags member contains a bit that specifies additional services required for the connection. The following table lists the values and meanings for flags:
| Value | Meaning |
| ATM_SERVICES_BEI | Indicates that the connection should use the best effort service. |
| ATM_SERVICES_BTAG | Indicates that the network should enable tagging in the backward direction. |
| ATM_SERVICES_CBR | Indicates that the local ATM interface should pace cells out to the network and that the circuit should be set up so that the requested bandwidth is guaranteed for the VC. This flag causes both local cell pacing to be enabled and the circuit to be signaled as a CBR circuit. CBR can be enabled only on hardware that supports this feature. |
| ATM_SERVICES_CLIPPING | Indicates that the network should enable clipping of cells on this circuit. |
| ATM_SERVICES_FTAG | Indicates that the network should enable tagging in the forward direction. |
| ATM_SERVICES_NOTIMING | Indicates that the circuit has no end-to-end timing requirements. If neither this flag nor the ATM_SERVICES_TIMING flag are set, the circuit is signaled as having unspecified timing requirements. |
| ATM_SERVICES_PACING | Indicates that the local ATM interface should pace cells out to the network as if the circuit were a CBR circuit. This flag has local significance only and does not affect any of the signaling messages used in creating the connection. This flag is used mainly when a convergence module wants to limit the rate at which cells can be transmitting on a specific VC. Pacing can be enabled only on hardware that supports this feature. |
| ATM_SERVICES_TIMING | Indicates that this circuit has some end-to-end timing requirements. When set, the circuit is signaled as having timing requirements. Also, the local system may enable features to facilitate the delivery of data with timing constraints. |
| ATM_SERVICES_VBR | Indicates that the local ATM interface and the network should treat this circuit as a variable bit rate circuit. This flag both enables VBR cell processing on the local adapter and causes the circuit to be signaled as a VBR circuit. VBR can be enabled only on hardware that supports this feature. |
The aal member specifies the AAL type for the connection and can have one of the following values: ATM_AAL1, ATM_AAL2, ATM_AAL3/4, or ATM_AAL5.
The queue member specifies the driver send queue to use for the VC (for drivers that support multiple send queues). The CMM sets this value; it must not be set by any other module.
The bearer_class member specifies the bearer class information to be used when signaling the call or that was signaled by the caller. For UNI signaling, this must be set to one of the following values: ATM_BBEARER_BCOB_A, ATM_BBEARER_BCOB_C, or ATM_BBEARER_BCOB_X.
The lerrstat member contains error indications that result from the CMM checking the validity of the structure contents. The following table lists the values and meanings for lerrstat:
| Value | Meaning |
| ATM_LERR_GOOD | Indicates that no errors were found in the structure contents. |
| ATM_LERR_PEAKMISSING | Indicates that the peak cell rate for CLP0+1 has not been specified. A peak cell rate must be specified on all circuits (though the rates may be specified as 0). |
| ATM_LERR_PEAKTOOBIG | The specified CLP0+1 rate exceeds the rate that is permitted by the hardware or the system configuration. |
| ATM_LERR_NOBWAVAIL | The specified peak CLP0+1 bandwidth exceeds the available bandwidth on the interface. |
| ATM_LERR_BADPEAKCR0 | The specified CLP0 peak cell rate exceeds the specified CLP0+1 peak cell rate. The CLP0 cell rate must be less than or equal to the CLP0+1 cell rate, depending on the connection type. |
| ATM_LERR_BADBURSTCR0 | The CLP0 burst cell rate exceeds the CLP0+1 burst cell rate. |
| ATM_LERR_BURSTTOOBIG | The specified CLP0 or CLP0+1 burst cell rate exceeds the specified peak CLP0+1 cell rate. |
| ATM_LERR_BADSUSTCR0 | The specified CLP0 sustained cell rate exceeds the specified CLP0+1 sustained cell rate. |
| ATM_LERR_SUSTTOOBIG | The specified CLP0 or CLP0+1 sustained cell rate exceeds the specified CLP0+1 peak cell rate. |
| ATM_LERR_RATETOOSMALL | The specified peak cell rate is smaller than the minimum rate the local hardware can allocate. A peak cell rate of 0 is always allowed. |
| ATM_LERR_BADTRAFFTYPE | Invalid traffic flags specified. This error occurs when neither the CBR or PACING flags are set, but the circuit is being configured as a CBR circuit. |
| ATM_LERR_BADDRVHANDLE | When applying a reserved resource, the driver on which the resources were reserved does not match the driver on which the VC is being created. |
| ATM_LERR_RESNOTALLOC | When applying a reserved resource, the atm_vc_services structure is not backed by allocated resources. This indicates that an atm_vc_services structure that does not reference previously reserved resources is being applied in a context where reserved resources are required. |
| ATM_LERR_RESALREADY | When reserving resources, the atm_vc_services structure already references reserved resources. This indicates that an atm_vc_services structure that has already been used to reserve resources is being reused to reserve the same or different resources. |
| ATM_LERR_RATESCHANGED | When applying reserved resources, the information specified in the atm_vc_services structure has been changed since the resources referenced by the structure were originally reserved. Once resources are reserved, convergence modules are not allowed to change any of the entries in the atm_vc_services structure. |
| ATM_LERR_RATESINCOMPAT | When applying a reserved resource, the rates specified in the atm_vc_services structure are incompatible with the rates requested in an incoming call. |
| ATM_LERR_VCALREADY | When applying a reserved resource, the VC to which the resource is being applied already has a previously applied resource. Resources can be applied only once, and each VC can be assigned resources only once. |
Signaling modules use the nerrstat member to report signaling protocol-specific validity checking errors on the contents of the atm_vc_services structure. The values of this member depend on the signaling module. This structure is currently always set to zero (0).
The cmm_drv_handle member contains the driver handle of the driver for which resources have been reserved (CBR and pacing circuits only). This may be compared to the driver handle information in the atm_ppa structure if a convergence module needs to determine whether reserved resources can be applied to a specific VC. This member is set by the CMM and must not be modified by any other module.
Device drivers use the drv_resource member to store private information necessary to track reserved resources. The contents of this member have meaning only to the specific device driver on which resources have been reserved, and are not examined by the CMM. Only the driver on which the resources have been reserved can modify this member.
Convergence modules use the converge_handle member to help track reserved resources. The contents of this member have meaning only to the specific convergence module that requested the reservations of resources, and are not examined by the CMM. Only the convergence module that reserved resources can modify this member.
To allocate the atm_vc_services structure, use the atm_cmm_alloc_services function call. This call allocates memory for the structure and initializes its members to default values for best-effort available bit rate (ABR) service. Once allocated, other ATM modules can change the members of this 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 Appendix A for syntax and a description of the two routines.
The CMM uses the atm_uni_call_ie structure to store optional information elements (IEs) when the UNI 3.0/3.1 signaling protocol module sets up a VC. Since UNI 3.0/3.1 is the default signaling protocol that the Digital UNIX ATM subsystem uses, the structure is described in this section. The atm_uni_call_ie structure has the following characteristics:
Example 3-1 shows the atm_uni_call_ie structure definition.
struct atm_uni_call_ie {
atm_ie_types_t ie_type;
char last;
union {
union {
struct {
unsigned short subtype;
unsigned short cbr_rate;
unsigned short multiplier;
unsigned short crt;
unsigned short err_corr;
unsigned short sdt;
unsigned short pfc;
} aal1;
struct {
unsigned int fsdu;
unsigned int bsdu;
unsigned int mid;
unsigned short mode;
unsigned short sscs;
} aal34;
struct {
unsigned int fsdu;
unsigned int bsdu;
unsigned short mode;
unsigned short sscs;
} aal5;
unsigned short user_aal[4];
} aal_params;
struct {
unsigned short hlit;
unsigned short hlisz;
unsigned short hli[8];
} bb_high_layer;
struct {
unsigned short layer2proto;
unsigned short mode2;
unsigned short q933;
unsigned short window_size;
unsigned short user2proto;
unsigned short layer3proto;
unsigned short mode3;
unsigned short dpsize;
unsigned short pktwindow;
unsigned short user3proto;
unsigned int ipi;
unsigned short snapid;
unsigned short oui[3];
unsigned short pid[2];
} bb_low_layer;
struct {
unsigned short bbri;
} bbrepeat;
unsigned short bytes[28];
} ie;
};
The ie_type member indicates the type of IE specified in the current instance of the structure. You must specify exactly one IE type per structure instance.
The last member indicates the last element of the IE array. This member must have a nonzero value for the last element of the array and a value of 0 for all other elements. The last element of the array does not need to be the last physical element of the array. This indicates the last logical element so that a module reading the array can determine where the last valid element is located. To declare an element between the start of the array and the last element as unused, set the element's type to ATM_IET_NONE.
The aal_params member is a union that contains the data to be placed in (or read from the SETUP message) the AAL Parameters IE in the SETUP and CONNECT signaling messages. The way the system interprets this union depends on the value of the ie_type member. The meaning of each member of each structure in the aal_params union corresponds to a data field in the AAL Parameters IE. See the UNI 3.0/3.1 specification for details on the meaning and use of these IE fields.
The bb_high_layer and bb_low_layer members are structures that specify information from their corresponding IE. Data in these structures is stored in machine native form, not just as a series of bytes from the network. Information in each structure is set either as numeric values or from constants as defined in the atm/sys/atm.h file. Also, the IE headers (the first 5 bytes of each IE that identifies the IE type and length) are not stored.
Note
Do not use the bbbc structure any more.
A convergence module can allocate as many instances of the structure as are needed. The only valid way to allocate storage for and initialize the atm_uni_call_ie structure from a convergence module is to use the atm_cmm_alloc_ie function call.
IE structures are allocated in contiguous virtual memory so that convergence and signaling modules can access them as an array of structures. Each IE structure in the array can be accessed as an index from the value returned from this call. For example, the following code fragment shows how to access the nth structure in the array:
atm_uni_call_ie_p upp, pp; register int i;
/* Allocate 3 IE's */ upp = atm_cmm_alloc_ei(3); /* Make the first IE a repeat indicator */ p = upp; p->ie_type = ATM_IET_REPEAT; ATM_IE_SETVAL(p->ie.bbrepeat.bbri,2); /* make the next two BLLI */ p = upp+1; p->ie_type = ATM_IET_BLLI; ATM_IE_SETVAL(p->ie.bb_low_layer,layer2proto,...); /* fill in structure */ p = upp+2; p->ie_type = ATM_IET_BLLI; ATM_IE_SETVAL(p->ie.bb_low_layer.layer2proto,...); /* fill in structure */
If you are using non-UNI signaling protocols, the convergence modules that use these protocols might not be able to use this structure directly, but must still allocate memory for passing call setup information between the signaling and convergence modules. To do this, use the atm_cmm_alloc_ie routine to allocate memory and assist the CMM in properly freeing the memory when the connection is destroyed. The allocating module is free to use memory returned from this call, with the following restrictions:
To allocate some arbitrary amount of memory for use in call setup, use the following algorithm:
register char *p; register int size;
size = (bytes_to_alloc + (sizeof(struct atm_uni_call_ie)-1)) / sizeof(struct atm_uni_call_ie); p = (char *)atm_cmm_alloc_ie(size);
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.
If the connect or related call fails, the CMM does not free the memory for structures passed in as arguments since it permits the calling routine to retain the memory for future tries. In this case, the convergence module must free the memory for these structures if they will not be retained for future call attempts. Modules can call the atm_cmm_free_ie function call with the value returned from atm_cmm_alloc_ie to free memory.
When a protocol convergence module needs to create a new connection, the module allocates and fills in an atm_call_ie structure array and passes this array to the CMM as part of the atm_cmm_connect function call. The convergence module must completely set all information in each IE that it creates; there are no default values. All IEs must be allocated using the routines described in Section 3.10.4.5 and must be referenced as an array of structures. Only the value returned from the atm_cmm_alloc_ie routine can be used to pass references to the IE array to the CMM. Never pass a pointer to an arbitrary element within the array to the CMM.
Since many of the IE fields are optional, each field explicitly set by a convergence module or by an incoming SETUP message must be explicitly flagged. Table 3-4 describes macros that provide the only valid means to read and and write values to and from the atm_uni_call_ie structure.
| Macro | Meaning |
| ATM_IE_SETVAL(Field,Value) | Sets a value in an IE field. This sets the field to the specified value and marks the field as valid; any previous field value in the field is destroyed. The Field argument is a C statement that references the field to be written, and Value is the value to write to the field. |
| ATM_IE_ISVALID(Field) | Determines if the referenced field holds valid data (was explicitly specified by the entity that created the IE). |
| ATM_IE_GETVAL(Field) | Reads values from an IE field. This returns 0 if the field does not contain valid data. To distinguish between a valid value of 0 and an unspecified field, use the ATM_IE_ISVALID() macro to determine the field's state. |
| ATM_IE_CLRVAL(Field) | Deletes valid information from an IE field. This deletes the data in the field and marks the field as invalid. This is the only way to remove (unset) a value from a field. |
The ATM subsystem uses the atm_ppa structure to identify a unique address/interface/signaling triple in the Digital UNIX ATM subsystem. The PPA specifies the calling party address on outgoing calls and specifies the called party addresses to which the ATM subsystem will respond on incoming calls. The atm_ppa structure has the following characteristics:
Table 3-5 lists those members of the atm_ppa structure, with their associated data types, that modules might reference.
| Member Name | Data Type |
| driver | atm_drv_handle_t |
| sig | atm_sig_handle_t |
| ppas_id | void * |
| ton | unsigned char |
| anpi | unsigned char |
| addrlen | unsigned char |
| address[ATM_PPA_MAX_ADDR] | unsigned char |
| uni | atm_uni_type_t |
| type | atm_ppa_type_t |
| esi_arg | void * |
The driver member indicates the driver or physical interface to which this PPA belongs. Since each interface can have any number of PPAs (one for each registered address plus one PVC PPA), this member identifies the underlying device. This value is significant only to the ATM subsystem, but it can be used by convergence modules to determine if two PPAs are associated with the same physical interface.
The sig member indicates the signaling module to which the PPA belongs; the signaling module handles connection management for that PPA.
The ppas_id member is a value provided by the signaling module that created the PPA for it to use in identifying or managing the PPA. The signaling module provides this value when registering the PPA with the CMM. The CMM does not use or modify this value.
The ton member is a value that specifies the endpoint's address type. These bits are identical to the type of number field in the Called Party Number IE (right justified).
The anpi member is the address or numbering plan identification information for the address. These bits are identical to those in the corresponding field of the Called Party Number IE.
The addrlen member contains the length (in bytes) of the endpoint address in the address array.
The address member is an array that contains one complete ATM address for the PPA. This is the fully registered address that contains either a valid E.164 address or a valid NSAP (with both network and ESI parts).
The uni member identifies the type of UNI interface to which this PPA belongs. The types of UNI interface are as follows:
In Digital UNIX Version 4.0, all ATM interfaces are private UNI interfaces.
The type member identifies the PPA type. The PPA types are as follows:
The esi_arg member stores the convergence module private argument passed to the CMM when a private ESI is registered. Convergence modules use this information to track which PPAs are created from specific ESIs. This member is valid only for private PPAs, but contains NULL in public ESIs.
The atm_esi structure accommodates non-UNI ESI or equivalent address information for signaling modules that have similar requirements in forming full network addresses. Only the signaling module cares about the actual structure of the address since it is the entity that interprets this information for registration with the network. Of course, any entity that creates an ESI must make the ESI conform to the format that the signaling module uses. In addition, the atm_esi structure has the following additional characteristics:
Table 3-6 lists those members of the atm_esi structure, with their associated data types, that modules might reference.
| Member Name | Data Type |
| esi[ATM_MAX_ESI] | unsigned char |
| esilen | unsigned int |
| driver | atm_drv_handle_t |
| sigp1 | void * |
| sigp2 | void * |
The esi member is an array that holds esilen bytes of the ESI. The length of the ESI must be less than ATM_MAX_ESI. For UNI signaling, the ESI length must be 6 bytes.
The driver member is the driver handle for the interface on which the ESI is configured. Each ESI is associated with exactly one interface. However, different interfaces can have the same ESI values, but they must be in separate ESI structures.
The sigp1 and sigp2 members are for the private use of signaling modules to keep internal information about the ESI. The CMM does not modify these members.
The atm_cause_info structure enables the CMM to keep track of all errors that occur on a VC or endpoint as well as record information that may be used to log activity on a VC or endpoint. The structure stores the following types of information:
This can be any VC and endpoint errors that are made visible to the network and to the other end of the connection through a Cause IE. Cause information also contains information of local significance only (such as text describing the error), but must contain a valid ATM cause code.
This can be any VC and endpoint activity information that is simply logged on the local system and not converted to Cause IE. Logging information provides information about VC or endpoint activity that a system or network administrator can view on the local system by using ATM administration tools.
The atm_cause_info structure has the following additional characteristics:
Table 3-7 lists those members of the atm_cause_info structure, with their associated data types, that modules might reference.
| Member Name | Data Type |
| cause | atm_error_t |
| location | atm_location_t |
| module_name | char * |
| reason | char * |
| diag_length | unsigned char |
| diag[ATM_DIAGNOSTIC_LENGTH] | unsigned char |
The cause member specifies the type of ATM error that occurred.
The location member specifies the ATM location code indicating where the error occurred (that is, user and network).
The module_name member specifies the ATM module in which the error occurred.
The reason member is a string that describes the error.
The diag_length member specifies the length of the diagnostic information.
The diag member contains diagnostic information from the diagnostic field in the Cause IE.