3    ATM Subsystem General Features

This chapter describes the following ATM features that writers of ATM device drivers, signaling modules, and protocol convergence modules can use:

• Header files

• Kernel data file

• Module configuration management

• Error codes

• Data formats

• Physical point of attachment

• Memory allocation

• ATM locking macros

• Types of circuits

• Global data structures

3.1    Header Files

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/sys directory):

• atm.h -- Common ATM subsystem structures, function prototypes, and ATM error codes (required by all ATM kernel modules)

• atm_adi.h -- Device driver interface function prototypes and structures (required by all ATM device drivers)

• atm_smi.h -- Signaling protocol module interface function prototypes and structure definitions (required by all signaling protocol modules)

• atm_cmi.h -- Protocol convergence module interface function prototypes and structure definitions (required by all protocol convergence modules)

• atm_osf.h -- Macros and constants for DIGITAL UNIX services that ATM subsystem modules use

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.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.

3.2    Kernel Data File

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.

3.3    ATM Module Configuration

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 Configuration and Tuning for information on tuning the ATM subsystem.

3.4    Error Codes

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.

3.5    Data Formats

The type of data transmitted and received on a virtual circuit (VC) depends on the type of ATM Adaption Layer (AAL) protocol 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:

• Raw ATM cells (full ATM cells, including cell headers)

• Cooked packet Protocol Data Units (PDUs)

3.5.1    Raw ATM Cells

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.

3.5.2    Cooked Data

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.

3.5.3    How the Data Is Carried

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.

3.5.4    Time-Stamping

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 constant 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.

3.6    Physical Point of Attachment

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 ATM End System Addresses (AESAs). An AESA uniquely identifies both the network services endpoint and a specific network services user attached to that endpoint.

UNI 3.0/3.1 AESA-format ATM addresses consist of the following parts:

• A prefix -- Assigned by the switch

• End system identifier (ESI) -- Assigned by the local host

• A selector byte -- Used by the network services provider on the end system to route a call to a specific network services user attached to a PPA

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 Integrated 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 ESIs configured in the ATM adapter's read-only memory (ROM)

• ESIs configured by the system or network administrator, who uses the atmconfig command

• ESIs configured by convergence modules that need to create their own ATM addresses

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 AESA 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 AESAs.

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:

• Permanent virtual circuit (PVC) PPAs, which manage PVCs

• Switched virtual circuit (SVC) PPAs, which manage SVCs

You can specify as many services for PVC connections as for SVC connections.

3.6.1    Permanent Virtual Circuit PPAs

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 AESA, 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.

3.6.2    Switched Virtual Circuit PPAs

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 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 AESA 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 AESA address. Therefore, all SVC activity must use a bind point as the local endpoint object. Calls received for an unbound AESA are rejected, and no calls can be placed without first creating a bind point and calling party's AESA.

The bind space for SVC PPAs is 8 bits long, the size of an AESA 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.

3.7    Memory Allocation

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_MALLOC_VAR(pointer,cast,size) ATM_MALLOCW_VAR(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. You should use these macros if the size of the allocation is determined at compile time, as they are optimized for that purpose.

The ATM_MALLOC_VAR and ATM_MALLOCW_VAR macros perform the same function as ATM_MALLOC and ATM_MALLOCW. You should use these macros when the allocation size is computed at run time.

The ATM_MALLOC and ATM_MALLOC_VAR macros do not block if the requested memory is not available, but return NULL. You should use these macros in the majority of cases since any routine called by the ATM Subsystem is not allowed to block (except Module Management Interface (MMI) calls).

The ATM_MALLOCW and ATM_MALLOCW_VAR macros block until the requested memory is available. However, they can still return NULL if an error occurs during the allocation processing. Use these macros 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 any ATM_MALLOC macro. 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);

3.8    ATM Locking Macros

The base ATM subsystem is symmetric multiprocessing (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.

3.8.1    Locking Guidelines

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.

3.8.2    Types of Locking Methods

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

• Funneling

• Using threads

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.

3.8.3    Order of Locking Macros

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:

1. Declare and initialize the lock information structure.

   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.

2. Declare a lock.

   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.

3. Initialize the lock.

   atm_lock_setup(&lock_name,&lock_info_name);

   Be sure to pass the address of the lock and lock information structures in this macro.

4. Take the lock.

   atm_lock(&lock_name);

   Be sure to raise the processor priority immediately before taking the lock.

5. Release 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.

6. If the lock is no longer needed, (for example, when storage for a structure with an embedded lock is being released), terminate the lock.

   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);

3.8.4    Creation of ATM Threads

ATM modules can create kernel threads for the following reasons:

• To schedule work in the module to be performed in a context that is private to that module. For example, a module may process incoming data from a thread rather than on the interrupt stack (incoming data is passed to convergence modules on the driver's interrupt stack).

• To perform functions that have to occur at periodic intervals such as protocol timeouts or garbage collection.

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.

3.9    Types of Circuits

The ATM subsystem supports the following circuits:

• Available bit rate (ABR)

• Constant bit rate (CBR)

  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.

• Pacing

  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.

3.10    Global Data Structures

The following data structures are visible to all modules of the ATM subsystem and to the protocol convergence module:

• atm_vc

• atm_addr

• atm_vc_services

• atm_uni_call_ie

• atm_ppa

• atm_esi

• atm_cause_info

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.

3.10.1    The atm_vc Structure

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 one or more local endpoints 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:

• Only the CMM allocates and frees the structure.

• The CMM and other ATM modules use the structure for keeping track of an active VC. The CMM also uses it to maintain all per-VC state information.

• Some structure members are reserved for use by the various modules in the ATM subsystem. This enables all ATM modules to use a common reference for a specific VC. All modules use the pointer to this structure as the handle for a specific VC.

• Each module of the ATM subsystem can write only those members of the structure that are assigned for its use. All other structure members should be considered read-only.

• The structure's size and members might change in the future, but the arrangement of the per-module structure members should not change.

• 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.

• You use a pointer of type atm_vc_p to reference the structure.

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.

Table 3-1:  The atm_vc Structure Members

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

3.10.1.1    The conv_pp1 and conv_pp2 Members

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.

3.10.1.2    The sig_pp1, sig_pp2, drv_pp1, and drv_pp2 Members

The sig_pp1, sig_pp2, drv_pp1, and drv_pp2 members have corresponding meanings for ATM signaling protocol modules and ATM device drivers, respectively.

3.10.1.3    The vcs Member

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.

3.10.1.4    The call_reference Member

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.

3.10.1.5    The errno Member

The errno member contains the last error number that was reported on the VC.

3.10.1.6    The vci and vpi Members

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.

3.10.1.7    The ppa Member

The ppa member indicates the PPA to which the VC belongs.

3.10.1.8    The selector Member

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 AESA address.

3.10.1.9    The direction Member

The direction member provides information about the direction of the call. The CMM sets this member to one of the following:

• ATM_DIRECTION_PVC, if the VC structure references a PVC

• ATM_DIRECTION_CALLING, if the VC structure references a call placed by the local system

• ATM_DIRECTION_CALLED, if the VC structure references a call received by the local system.

This structure member is set only by the CMM and must not be modified by any other module.

3.10.2    The atm_addr Structure

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 stores all address- and state-related information for a connection endpoint. This structure contains only endpoint information, not information about the connection to the endpoint. The connection information is maintained in the atm_vc structure that is referenced in the atm_addr structure. Except at structure initialization time, all address structures are associated with a VC.

• All function calls that perform an action related to a specific endpoint use a pointer to this structure.

• The structure maintains local address information since the local address is also a connection endpoint.

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.

Table 3-2:  The atm_addr Structure Members

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 *

3.10.2.1    The vc Member

The vc member references the atm_vc structure of the VC to which this endpoint belongs.

3.10.2.2    The address Member

The address member is an array that contains the 20-byte ATM address of the endpoint.

3.10.2.3    The ton Member

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).

3.10.2.4    The anpi Member

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.

3.10.2.5    The subaddress Member

The subaddress member is an array that contains the subaddress of the endpoint. If the endpoint has no subaddress, the Authority and Format Indicator (AFI) byte of the subaddress array must be 0.

3.10.2.6    The subaddress_type Member

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).

3.10.2.7    The eprtype Member

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.

3.10.2.8    The endpoint 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.

3.10.2.9    The state Member

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.

3.10.2.10    The atm_error Member

The atm_error member contains the error number for the last error reported on the endpoint.

3.10.2.11    The setup Member

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.

3.10.2.12    The connect Member

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.

3.10.2.13    The location, cause, diag_length, and diagnostic Members

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.

3.10.2.14    The endstate Member

Only the signaling module fills in the endstate member as part of the enquiry processing.

3.10.2.15    The conv_p1 and conv_p2 Members

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.

3.10.2.16    The sig_p1 and sig_p2 Members

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.

3.10.2.17    Allocating the atm_addr Structure

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.

3.10.3    The atm_vc_services Structure

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:

• One structure must be allocated and the members set to valid values for each new connection by the entity that creates the connection (convergence protocol module on outgoing calls or signaling protocol module on incoming calls). Once the connection service parameters are set you cannot change them.

• The CMM keeps track of these structures on a per-VC basis and frees them when the connection is torn down.

• The structure defines those services the CMM and driver manage. Every signaling and convergence module must properly set up the structure regardless of the signaling protocol used to actually set up the connection.

• Signaling protocol modules may use the structure to obtain information needed to create various signaling protocol messages used in call management (available to all modules).

• The structure is also used to track resource reservations. A convergence module can reserve resources for allocation to incoming or outgoing calls at a later time. You use this structure to define what resources are to be reserved and to track the reserved resources. See Section 7.1 for more complete information on the use of this structure in resource reservation.

• This structure defines parameters relative to the local system, independent of the actual call direction. The term forward means the sending side of the connection on the local system; the term backward means the receiving side of the connection on the local system. This is different from the ATM Forum UNI specification, which defines parameters based on the call direction.

  The signaling module must perform any conversions between the atm_vc_services structure members and the appropriate information elements (IEs) in the signaling message. This might require interchanging forward and backward fields, depending on the direction of the call.

• The structure is always referenced as a pointer of type atm_vc_services_p.

Table 3-3 lists those member names of the atm_vc_services structure, with their associated data types, that modules might reference.

Table 3-3:  The atm_vc_services Structure Members

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 *

3.10.3.1    The vc Member

The vc member is a pointer to the VC structure for the connection.

3.10.3.2    The fqos and bqos Members

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 values and meanings for fqos and bqos:

3.10.3.3    The fmtu and bmtu Members

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.

Only device driver modules use the fmtu and bmtu members to allocate resources for a connection; the signaling module does not use them to store MTU-related information elements (IEs). If a protocol requires explicit signaling of MTU information, the convergence module must use the atm_uni_call_ie structure to supply the IEs. See Section 3.10.4 for more information about the structure and its members. See Chapter 7 for information on making outgoing connections and accepting connections.

3.10.3.4    The valid_rates Member

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 values and meanings for valid_rates:

3.10.3.5    The fpeakcr, bpeakcr, fsustcr, bsustcr, fburstcr, and bburstcr Members

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 Cell 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.

3.10.3.6    The flags Member

The flags member contains a bit that specifies additional services required for the connection. The following table lists the values and meanings for flags:

3.10.3.7    The aal Member

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.

3.10.3.8    The queue Member

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.

3.10.3.9    The bearer_class Member

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.

3.10.3.10    The lerrstat Member

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:

3.10.3.11    The nerrstat Member

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).

3.10.3.12    The cmm_drv_handle Member

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.

3.10.3.13    The drv_resource Member

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.

3.10.3.14    The converge_handle 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.

3.10.3.15    Allocating the atm_vc_services Structure

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.

3.10.4    The atm_uni_call_ie Structure

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:

• The structure communicates only connection setup information between convergence protocol modules and the UNI 3.0/3.1 signaling protocol module.

• The CMM does not access or modify this structure.

• The information specified in this structure is taken directly from the various optional IEs used in the SETUP and CONNECT signaling messages. Mandatory IEs necessary for connection setup are built by the UNI 3.0/3.1 signaling protocol from information taken from the atm_addr and the atm_vc_services structures. See Section 3.10.2 and Section 3.10.3, respectively, for more information.

• The structure contains a union of all IEs that a convergence module can specify.

• Each instance of this structure specifies exactly one IE. To specify multiple IEs, you must define multiple instances of this structure. Convergence modules can specify as many IEs as are needed to place the call.

• The structure defines the terms forward and backward using the ATM Forum UNI specification definitions. Forward is the direction from the caller to the callee and backward is the direction from the callee to the caller. This is in contrast to the definitions used in the atm_vc_services struction. See Section 3.10.3 for more information.

Example 3-1 shows the atm_uni_call_ie structure definition.

Example 3-1:  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;
};
 

3.10.4.1    The ie_type Member

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.

3.10.4.2    The last Member

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.

3.10.4.3    The aal_params Member

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.

3.10.4.4    The bb_high_layer and bb_low_layer Members

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.

3.10.4.5    Allocating the atm_uni_call_ie Structure

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:

• Memory is allocated in multiples of the structure size so the minimum number of atm_uni_call_ie structures that provide enough storage must be allocated.

• The only address that convergence and signaling modules are permitted to use to reference this memory is the address returned from the atm_cmm_alloc_ie call.

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.

3.10.4.6    Setting Fields in the atm__uni_call_ie Structure

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 write values to and from the atm_uni_call_ie structure.

Table 3-4:  Information Element Macros

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.

3.10.5    The atm_ppa Structure

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:

• The CMM maintains exactly one PPA structure for each address or driver combination configured on the system.

• Only the CMM can change the contents of the PPA structure.

• Convergence modules can hold references to the PPA structures until they receive a notification that the PPA has been deleted.

• The structure is always referenced as type atm_ppa_p.

Table 3-5 lists those members of the atm_ppa structure, with their associated data types, that modules might reference.

Table 3-5:  The atm_ppa Structure Members

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 *

3.10.5.1    The driver Member

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.

3.10.5.2    The sig Member

The sig member indicates the signaling module to which the PPA belongs; the signaling module handles connection management for that PPA.

3.10.5.3    The ppas_id Member

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.

3.10.5.4    The ton Member

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).

3.10.5.5    The anpi Member

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.

3.10.5.6    The addrlen Member

The addrlen member contains the length (in bytes) of the endpoint address in the address array.

3.10.5.7    The address Member

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 AESA (with both network and ESI parts).

3.10.5.8    The uni Member

The uni member identifies the type of UNI interface to which this PPA belongs. The types of UNI interface are as follows:

• ATM_UNI_PRIVATE -- A private UNI interface

• ATM_UNI_PUBLIC -- A public UNI interface

In DIGITAL UNIX Version 4.0, all ATM interfaces are private UNI interfaces.

3.10.5.9    The type Member

The type member identifies the PPA type. The PPA types are as follows:

• ATM_PPA_PUBLIC -- Global PPAs that all convergence modules share.

• ATM_PPA_PRIVATE -- PPAs that are private to a specific convergence module. The PPA was created using an ESI provided by that convergence module.

3.10.5.10    The esi_arg Member

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.

3.10.6    The atm_esi Structure

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:

• The pointer to the structure is maintained as the system-wide reference to the structure.

• Only the CMM allocates and frees the structure. Only the CMM may modify the nonprivate structure members.

• Non-UNI signaling protocols are free to use the ESI data in any way that is appropriate for the protocol, including setting full addresses from the atm_esi structure.

Table 3-6 lists those members of the atm_esi structure, with their associated data types, that modules might reference.

Table 3-6:  The atm_esi Structure Members

Member Name	Data Type
esi[ATM_MAX_ESI]	unsigned char
esilen	unsigned int
driver	atm_drv_handle_t
sigp1	void *
sigp2	void *

3.10.6.1    The esi and esilen Members

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.

3.10.6.2    The driver Member

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.

3.10.6.3    The sigp1 and sigp2 Members

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.

3.10.7    The atm_cause_info Structure

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:

• Cause 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.

• Logging information

  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:

• All ATM modules use this structure to read cause and logging information from a VC or endpoint.

• Only the CMM allocates the structure.

• All cause and logging information retrieval functions return a pointer to this structure.

• The structure is not used for setting cause and logging information.

• The CMM writes cause and logging information when logging routines are called. The structure contents are not directly modified.

Table 3-7 lists those members of the atm_cause_info structure, with their associated data types, that modules might reference.

Table 3-7:  The atm_cause_info Structure Members

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

3.10.7.1    The cause Member

The cause member specifies the type of ATM error that occurred.

3.10.7.2    The location Member

The location member specifies the ATM location code indicating where the error occurred (that is, user and network).

3.10.7.3    The module_name Member

The module_name member specifies the ATM module in which the error occurred.

3.10.7.4    The reason Member

The reason member is a string that describes the error.

3.10.7.5    The diag_length Member

The diag_length member specifies the length of the diagnostic information.

3.10.7.6    The diag Member

The diag member contains diagnostic information from the diagnostic field in the Cause IE.