Chapter 1. API Specification

This document describes the Silicon Graphics application programming interface (API) for IRIS Asynchronous Transfer Mode (ATM) products. This first chapter provides a general overview of the API and its use. Subsequent chapters contain detailed descriptions of API commands. The product includes a C-language coding example for an application that uses the switched virtual circuit API in the following location: /usr/lib/atm/examples/sigtest.c.

Each chapter describes the commands relevant for one of the following types of implementations:


The IRIS ATM API is based on the following features of the IRIS ATM product:

  • ATM adaptation layer 5 (AAL5) protocol mapping (RFC 1483, Multiprotocol Encapsulation over ATM Adaptation Layer 5 and RFC 1626, Default IP MTU for Use over ATM AAL5).

  • ATM signaling (ATM Forum UNI 3.0/3.1) (RFC 1755, ATM Signaling Support for IP over ATM and RFC 1932, IP over ATM: A Framework Document).

  • Network and address management via ILMI and the ATM management information database (MIB) for multiple ATM user-network interfaces (UNIs) (ATM ILMI management information base, simple network management protocol (SNMP) based ATM Forum MIB implementation).

  • RFC 1577 compliant (classical IP) as well as noncompliant configurations, such as the Simple Protocol for ATM Network Signaling (SPANS). IRIS ATM has the ability to function as the address resolution (ATMARP) server or as a client for each IP subnetwork.

The IRIS ATM API supports the following ATM services:

  • Permanent virtual circuits (PVC) for point-to-point, bidirectional or unidirectional connections with constant bit rate (CBR), variable bit rate (VBR), or best-effort service. The traffic can be IP (with or without logical link control/subnetwork access point (LLC/SNAP) encapsulation) or non-IP.

  • Switched virtual circuits (SVC) for bidirectional point-to-point and unidirectional point-to-multipoint connections via ATM signaling with CBR, VBR, or best-effort service. Supports non-IP traffic only, with or without LLC/SNAP encapsulation. (IP-over-SVC traffic is handled by the IRIS ATM driver via the standard BSD socket interface.)

  • Connections with symmetric or asymmetric bandwidth requirements.

  • ATM quality of services (QoS) for classes unspecified, A, B, and D.

  • Strict VCI-based packet multiplexing.

Driver Architecture and Theory of Operations

The services of the IRIS ATM subsystem can be accessed using PVCs or SVCs, for IP or non-IP traffic. These four access scenarios are briefly described in the following list, and are discussed in more detail in the paragraphs that follow:

  • Non-IP traffic over PVCs

    The character device interface (IRIS ATM API) allows traffic to be sent constant bit rate, variable bit rate, or best-effort, as requested.

  • IP traffic over PVCs

    The character device interface (IRIS ATM API) is used to establish PVCs (using constant bit rate, variable bit rate, or best-effort, as requested) and associate them with IP addresses. LLC/SNAP encapsulation is the default, but can be disabled. The standard BSD socket interface is used for transmit or receive once the PVC is established. IP-to-VC address resolution is handled via a lookup table.

  • Non-IP traffic over SVCs

    The character device interface (IRIS ATM API) allows traffic to be sent constant bit rate, variable bit rate, or best-effort service, as requested.

  • IP traffic over SVCs

    The standard IRIX BSD socket interface to the IP protocol stack allows traffic to be sent best-effort service over SVCs. LLC/SNAP encapsulation is done on all packets.

    Note: To use the standard IP socket interface, simply configure the IRIS ATM software for IP-over-ATM, as described in the IRIS ATM Configuration Guide, publication 007-2333- xxx. Once the software is configured, the services of the IRIS ATM subsystem are available to upper-layer IP applications.

Access to the IRIS ATM subsystem is described in the following list and illustrated in Figure 1-1:

  • Non-IP data through PVCs

    For each VC, this interface consists of opening a file descriptor ( open()), using the ATMIOC_CREATEPVC ioctl() command to create the VC, and then exchanging data, using the read(), write(), or writev() command.

  • IP-over-ATM traffic through PVCs

    For each VC, this interface consists of opening a file descriptor ( open()), using the ATMIOC_CREATEPVC command to create the VC with a tag for IP, and using the ATMIOC_SETARP command to create an address resolution mapping. Or, instead, you can configure and run the atmarp utility. When atmarp is running, customer applications can simply use the BSD socket interface, as described in the next paragraph. (For more information about atmarp, see “PVC Management by atmarp”.)

    In either case, once the PVCs are established, the BSD socket interface is used to exchange data. Commands used for this exchange are socket() , connect(), bind(), accept(), read(), write(), or writev(). Address resolution is provided by RFC 1577 software that responds to InverseARP requests and ILMI software, as described in “Address Resolution for IP-Over-PVCs”.

  • Non-IP data through SVCs

    For each VC, this interface consists of opening a file descriptor ( open()), using IRIS ATM ioctl() commands, such as ATMIOC_SETUP or ATMIOC_REGISTER, ATMIOC_LISTEN, and ATMIOC_ACCEPT, to create the VC , and then exchanging data by using read(), write(), or writev() commands.

  • IP-over-ATM traffic over SVCs through the BSD socket interface

    Applications that use the standard IRIX BSD socket interface for the IP suite of protocols access the services of the IRIS ATM subsystem like other IRIX network subsystems. This interface consists of standard functions (for example, socket(), bind(), listen(), connect(), read(), write(), writev(), and standard, non-ATM ioctl() calls). This interface is not described in this document. Address resolution is provided by software based on RFC 1577 that communicates with the subnetwork's ATM address resolution server and ILMI software, both of which are included in the IRIS ATM software.

    Note: For more information on the socket interface, see the following man pages: accept(2), bind(2), connect(2), fcntl(2), getsockname(2), getsockopt(2), ioctl(2), listen(2), read(2), recv(2), select(2), send(2), socket(2), socketpair(2), write(2), and writev(2).

    Figure 1-1. IRIS ATM driver architecture

    IRIS ATM driver architecture

Character Device Interface

The character device interface for IRIS ATM supports applications (sending IP or non-IP traffic) that require CBR, VBR, or best-effort service, as well as applications that manage, configure, or control the ATM subsystem. Through the character device interface, applications can use any combination of PVCs and SVCs. Standard IP applications that can tolerate best-effort service are encouraged to use the IP-over-SVC support that is built into the IRIS ATM driver via IP logical network interfaces ( atm0, atm1, atm2, and so on) and the BSD socket interface.

Within the ATM subsystem, there is no implicit binding between a VC and an ATM port. Because of this design, each hardware device (ATM port) simultaneously supports multiple VCs. There is, however, a one-to-one binding between each file descriptor and its associated VC; that is, each open file descriptor supports only one VC. These relationships are portrayed in Figure 1-2.

Figure 1-2. Relationship of VCs, file descriptors, and ATM hardware

Relationship of VCs, file descriptors,
and ATM hardware

The following sections provide the following character device information:

  • Include files

  • open () function

  • close () function

  • read () function

  • write () function

  • Command format

  • ATM-OC3c management and configuration

Include Files

The following files define structures and constants that must be used with the ATM character device interface:

  • “sys/atm.h”

  • “sys/atm_user.h”

  • “sys/if_atm.h” (required only for IP-over-PVCs)

open() Function

When the open() function is invoked on an IRIS ATM device file, the returned file descriptor has established a kernel-level connection to the selected ATM board. There can be multiple character device interfaces active for each installed IRIS ATM port. Each open file descriptor services one VC.

During startup, a symbolic link is created in the /dev directory for each IRIS ATM port listed in the hardware graph (for example, /hw/atm/0). By standard convention, the assigned port number is reflected in the device file name. For example, an IRIS ATM port that has been assigned port number 2 has an entry of /dev/atm2.

The following example illustrates proper usage where the ATM-OC3c device is identified as port 0 (/dev/atm0):

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>

int fd_atm;

if ((fd_atm = open("/dev/atm0", O_RDWR)) < 0) {

Note: At this point, no VC is created; no read() or write() calls can be made. To create the desired VC, the ATMIOC_CREATEPVC, ATMIOC_REGISTER, or ATMIOC_SETUP ioctl() call must be used on the returned file descriptor. These ioctl() calls are described in Chapter 2, “ Commands for Permanent VCs”, and Chapter 3, “Commands for Switched VCs”.

close() Function

The close() function tears down the bound VC after all the buffered data for the VC has been transmitted. The close() results in closing the kernel-level link to the ATM-OC3c port, removing the associated VC from the ATM subsystem, and freeing the port and driver resources. The following example illustrates proper usage:

#include <unistd.h>

if (close(fd_atm) < 0) {

read() Function

The default behavior for read() commands on an ATM device is blocking; that is, read() calls return only after data has been read or made available. However, you can open the file descriptor in nonblocking mode by using the O_NDELAY flag (defined in the fcntl.h file).

Note: Do not use the O_NONBLOCK, FNONBLOCK, or FNONBLK flags. They do not work with ATM file descriptors and they destroy the O_NDELAY flag, having the effect of a NULL flag if used in combination with O_NDELAY .

The following example shows the use of the O_NDELAY flag:

#include <fcntl.h> ...

main() { int fd;

/*Set the nonblocking mode*/

perror("Couldn't set no delay!\n");

With the default blocking mode, read() calls wait for data to become available. With the nonblocking mode, read() calls return with an EAGAIN failure whenever no data is available.

For each ATM read-access interface, it is the responsibility of the application to perform enough read() calls to consume the data. There is one receive queue for each VC; each queue is 50 ATM Adaptation Layer (AAL) convergence sublayer protocol data units (CSPDUs) deep. If an application fails to consume incoming data fast enough and the receive queue in the kernel overflows, CSPDUs are dropped.

The examples in the following sections illustrate correct usage for large- and small-sized data in the current implementation.

Small-Sized Data

For data that occupies less than one page of system memory, the following usage is correct:

#include <sys/types.h>
#include <sys/uio.h>
#include <unistd.h>
#include <sys/atm_user.h>

buf = (char*) malloc(size);
retvalue = read(fd_atm, buf, MAX_USER_BYTES_PDU);

Large-Sized Data

For data that is greater than or equal to an operating system page of memory, it is recommended that page-aligned buffers be used in order to optimize performance. This optimization is optional. If page-aligned buffers are not provided, the driver retrieves the data by copying it, as in the following example:

#include <sys/types.h>
#include <sys/uio.h>
#include <unistd.h>
#include <sys/atm_user.h>

buf = (char*) valloc(size);
retvalue = read(fd_atm, buf, MAX_USER_BYTES_PDU);

write() Function

The default behavior for write() commands on an ATM device is blocking. However, after opening the file descriptor, nonblocking behavior can be specified (using the standard ioctl() FIONBIO command). In the default blocking mode, write() commands wait for the direct memory access (DMA) to the board to complete before returning. In nonblocking mode, write() commands return immediately, before the DMA is complete; however, if the previous DMA is not complete, a nonblocking write() fails and returns the EAGAIN error.

The following list summarizes two methods for transmitting over the ATM-OC3c subsystem with the ATM character device interface:

  • Invoking the write() call, using one buffer of any size and resulting in one or more AAL CSPDUs. The ATM subsystem divides the data into fully filled CSPDUs, and when necessary, pads the final CSPDU.

  • Invoking the writev() call, using 1 to IOV_MAX buffers (also known as iovecs), and resulting in one or more PDUs (that is, as many PDUs as necessary). The data is concatenated and divided into PDUs. When necessary, incomplete PDUs are padded.

The following rules apply to transmissions:

  • All buffers must begin on 8-byte boundaries.

  • All buffers must be pinned down.

  • In the default blocking mode, calls block until the very last byte of data for the call has accessed the board via DMA.

  • The buffer (or iovec) size can end at any byte position (odd or even). For the writev() call, any buffer that is not a multiple of 8 causes the ATM subsystem to pad out the current CSPDU and transmit it. The data from the next iovec, if one is present, is placed into a new CSPDU.

  • As long as buffers are multiples of 8 bytes, but not of MAX_USER_BYTES_PDU in size, there is no correlation between the iovec boundaries and the CSPDU boundaries. That is, the driver does not force new CSPDUs to start on iovec boundaries.

    Note: If a buffer is not pinned down, an EFAULT error may occur and it is possible that useless data will be sent.

Most audio and video applications have one very large buffer (multiple megabytes) in user virtual address space. By starting the first write() on an 8-byte boundary, and making every write() a multiple of 8 bytes, all subsequent writes will be automatically properly aligned.

General write() Example

The example below demonstrates correct usage of the write() call:

#include <unistd.h>
#include <stdlib.h>
#include <sys/lock.h>

while (needed) {
      buf = (char*) memalign(8, size);  /* any size */
      mpin (buf, size);
      retvalue = write(fd_atm, buf, size);

Sending Multiple Buffers of Data

To send a number of buffers of data, use a writev() call, as shown in the following example.

struct iovec iov[IOV_MAX];

for (vec=0; vec<vec_count, vec++) {
      iov.iov[vec].iov_base = (caddr_t) memalign( 8, size );
      iov.iov[vec].iov_len = size;
      mpin( iov.iov[vec].iov_base, size );

retvalue = writev( fd_atm, iov, vec_count );

This method can result in many CSPDUs. For best performance, the size of each of the buffers, except the last one, should be a multiple of 8 bytes. As long as each buffer size is a multiple of 8, the ATM subsystem concatenates the data, divides it into chunks that completely fill CSPDUs, and transmits it. When the ATM subsystem gathers data that is not a multiple of 8, it places that data into the current CSPDU, pads out the CSPDU and transmits it; the next buffer, if there is one, is contained in a new CSPDU.

Gathering Data into One Packet

A number of buffers can be gathered into a single CSPDU by using a writev() call, as shown in the following example. The size (length) of each buffer, except the last one, must be a multiple of 8 bytes, and the total data for all the buffers must be less than or equal to MAX_USER_BYTES_PDU .

struct iovec iov[IOV_MAX];

for (vec=0; vec < (vec_count), vec++) {
      /* size = multiple of 8*/
      iov.iov[vec].iov_base = (caddr_t) memalign( 8, size );
      iov.iov[vec].iov_len = size;
      mpin( iov.iov[vec].iov_base, size );

/* total size ≤ MAX_USER_BYTES_PDU */
      retvalue = writev( fd_atm, iov, vec_count );

Sending One Buffer of Data

To send a single buffer, use the write() call. The ATM subsystem divides the data into chunks that completely fill CSPDUs, and transmits the CSPDUs, as in the following example. If the final chunk of data does not completely fill a CSPDU, the ATM subsystem pads it and transmits it. Amounts of data smaller than MAX_USER_BYTES_PDU can be written, and the ATM subsystem does all appropriate padding; however, throughput is adversely affected.

char *buf = memalign(8, size);
mpin (buf, size)				
retvalue = write(fd_atm, buf, size);

IRIS ATM API Command Format

All the IRIS ATM API commands are available through the IRIS character device interface in the following format:

ioctl(fd_atm, COMMAND
, arg);

Managing and Configuring the ATM-OC3c Subsystem

Before an application can use the IRIS ATM API to utilize the services of an ATM subsystem, one or more control programs (also called management programs) must take care of the tasks listed in Table 1-1. The IRIS ATM driver performs these tasks at startup, thus making available a default configuration of the subsystem. For environments using this default configuration, no additional control program is necessary. For environments requiring a nondefault configuration, a customer-developed control program must reconfigure the subsystem after the IRIS ATM driver has completed its tasks.

Table 1-1, indicates which ATM ioctl() command is used to carry out each task. It is not important if one or multiple programs are created to perform these tasks; however, the following restrictions apply:

  • For any single ATM-OC3c port, each specific task listed in the Task column should be performed by only one control program. Chaos can occur if a number of programs are doing the same task to the same port.

  • The tasks must be performed in the order shown in the Task column.

  • A program doing the tasks described in the table can (if desired) also do user-data transfers.

  • Each task assumes an open file descriptor to the port it is configuring. The file descriptor can be closed whenever the program has finished its tasks.

    Table 1-1. Configuration Tasks That Must Be Done for Each ATM-OC3c Board

    Task (in order)



    More Info

    Configure operational modes



    Retrieve the current configuration.

    If changes are needed, set new configuration parameters.

    “ATMIOC_GETCONF” in Chapter 5

    “ATMIOC_SETCONF” in Chapter 5

    For IRIS ATM HIO boards only, configure one or more rate queues, if not correctly configured. [a]





    Rate queue ##

    Rate queue ##

    Rate queue ##

    Rate queue ##

    “ATMIOC_SETRATEQ” in Chapter 5

    Monitor status (optional)



    Retrieve board statistics.

    Retrieve driver-internal statistics.

    “ATMIOC_GETSTAT” in Chapter 5

    “ATMIOC_GETIOSTAT” in Chapter 5

    [a] See “Characteristics of the ATM-OC3c Hardware” for a description of how IRIS ATM configures and manages transmission rates.

Each application that wants to transfer data through the ATM subsystem must wait until the control program has completed its tasks, then it must obtain a file descriptor and create a VC before reading or writing data. When the data transfer is finished, the application simply closes its file descriptor. The ATM subsystem clears the VC, cleans up, and releases resources.

Note: When IP applications are going to use the ATM subsystem, there are additional management requirements, as described in “IP Support for PVCs”.

IP Support for PVCs

The following sections describe IRIS ATM support for IP-over-ATM using PVCs.

Address Resolution for IP-Over-PVCs

IRIS ATM address resolution for IP-over-PVC traffic can be divided into two parts: IP-to-ATM address resolution and IP-to-VC address resolution, described as follows:

  • IP-to-ATM address resolution consists of obtaining (registering) an ATM address from the adjacent switch or self-assigning this address, and responding to InverseARP requests[1]in order to verify or provide the IP address that is mapped to the ATM address. The first process is handled automatically by ILMI software modules on both the adjacent switch and the local system, and InverseARP is handled automatically by RFC 1577 software on both the local system and the other endpoint.

    Note: On PVCs, IRIS ATM address resolution software responds to received InverseARP requests when LLC/SNAP encapsulation is enabled; however, it does not generate InverseARP requests.

  • IP-to-VC address resolution consists of mapping an IP address to a PVC that is identified by a local hardware address made from a virtual path identifier or virtual channel identifier (VPI or VCI) value and an ATM port identification number. All of the mappings are stored in the kernel-resident ATM address resolution (AR) table. The atmarp utility (or equivalently the ATMIOC_SETARP command) loads PVC address resolution information into the AR table. The ATMIOC_GETARPTAB command retrieves the contents of the table.

The VC address is defined by the atm_laddr_t structure, illustrated in Figure 1-3. The atm_laddr_t structure fits conveniently into the standard hardware address, arp_ha structure, that the arpreq request uses.

Figure 1-3. ATM Address Resolution Table Entry: the atm_laddr_t Structure

ATM Address Resolution Table Entry: the 
atm_laddr_t Structure

The ATM-specific ioctl() calls that are available for address resolution are as follows. These calls are described in Chapter 2, “ Commands for Permanent VCs”.

  • ATMIOC_SETARP (adds an entry to the AR table)

  • ATMIOC_GETARP (retrieves one entry from the table)

  • ATMIOC_DELARP (deletes an entry from the AR table)

  • ATMIOC_GETARPTAB (retrieves the entire table)

Address resolution and internal routing of IP packets is handled in the following manner: the ATMIOC_CREATEPVC command with the IP flag set to on and the ATMIOC_SETARP command create the links between the IP interface and the PVC that allow incoming and outgoing IP packets to be routed correctly.

LLC/SNAP Encapsulation for PVCs

Each PVC can be configured to perform or not to perform subnetwork access protocol encapsulation (802.2 LLC/SNAP) for packets on VCs associated with an IP logical network interface. When LLC/SNAP encapsulation is enabled for a VC, the LLC and SNAP headers are attached to every packet on that VC, thus allowing ATM subsystems to differentiate among upper-layer protocol stacks (for example, IP and ARP). When LLC/SNAP is enabled on a VC, the IRIS ATM subsystem responds to InverseARP requests. When LLC/SNAP encapsulation is disabled, IP packets on that VC are not encapsulated and InverseARP requests are not answered. The default behavior is to enable LLC/SNAP encapsulation.

Configuration of LLC/SNAP encapsulation for each PVC can be done by either of the following methods:

  • Edit the IP-to-PVC address resolution table and let the VCs be opened and configured by the IRIS ATM atmarp utility.

  • Set the configuration for each PVC when it is created with the ATMIOC_CREATEPVC command.

IRIS ATM Subsystem Management for IP-Over-PVCs

Before any IP applications can use IP-over-PVC services, one or more control programs (also called management programs) must take care of the tasks listed in Table 1-2. For most implementations, the default control provided by the IRIS ATM utility atmarp (which is invoked during startup) is sufficient.

PVC Management by atmarp

During system startup, the /etc/init.d/network.atm script starts the atmarp PVC management application if the /var/atm/pvc.conf file exists. This user-configurable file maps IP addresses to local ports and VPI or VCI addresses. For each entry in the table, atmarp opens a file descriptor for the indicated port, and makes an ATMIOC_CREATEPVC and an ATMIOC_SETARP ioctl() call in order to establish a best-effort PVC and associate it with an IP address. The atmarp utility then goes to sleep, leaving the VCs open and ready for use. (If the file descriptors were to be closed, the PVCs would be torn down.) At this point, an IP application that opens a socket to any of the IP addresses in the table transmits or receives over the associated PVC. If atmarp is interrupted with a SIGHUP signal (for example, killall -HUP atmarp ) it wakes up, reloads the lookup table from the pvc.conf file, makes any changes necessary by closing file descriptors (for deleted entries) or establishing new PVCs (for new entries), then goes back to sleep.

PVC Management by a Customer-Developed Application

For implementations that do not use atmarp to manage their PVCs, the following guidelines should be adhered to when designing the management application. It is not important if one or multiple programs are created to perform these tasks; however, the following restrictions apply:

  • The tasks must be performed in the order shown in the “Task” column of Table 1-2.

  • Before doing any of the tasks listed in Table 1-2, the tasks in Table 1-1, must be performed, either by another control program or by the same program doing the tasks listed in Table 1-2.

  • The management program doing these tasks can (if desired) also read or write over these VCs.

  • The management program must keep the file descriptor open for the entire duration of the PVC's use.

    Table 1-2. Configuration Tasks That Must Be Done for Each ATM Network Interface Servicing IP if atmarp Is Not Running

    Task (in order)



    More Info

    Open as many file descriptors for the port as there will be PVCs.






    The control program must keep each file descriptor open as long as the associated PVC is being used.

    “open() Function”

    Create one virtual channel for each file descriptor.




    Each ioctl() call creates one virtual channel with a cellrate that is as close as possible to the requested rate. Tag each VC for IP.

    “ATMIOC_CREATEPVC” in Chapter 2

    Manage ATM address resolution.




    Create an IP-to-VC mapping in the ATM subsystem's address resolution table for each IP endpoint. Each SETARP ioctl() call creates one entry.

    “ATMIOC_SETARP” in Chapter 2

    Tear down a PVC.

    close (fd#)


    “close() Function”

    Monitor the AR table (optional).



    “ATMIOC_GETARPTAB” in Chapter 2

When the control program closes a file descriptor, the ATM subsystem automatically tears down the associated VC, cleans up the address resolution table, and releases the associated resources.

Each IP application that wants to transfer data through the ATM subsystem simply does what all IP applications do (use socket(), bind(), connect(), accept(), and so on) before reading or writing data. When the data transfer is finished, the application closes its socket. The ATM subsystem does not tear down the VC; only closing the file descriptor tears down the VC.

Characteristics of the ATM-OC3c Hardware

The following sections describe aspects of IRIS ATM hardware design that might be of interest to users of the IRIS ATM API. There is a separate section for each IRIS ATM board.

IRIS ATM-OC3c HIO Board for CHALLENGE and Onyx Platforms

The IRIS ATM-OC3c for CHALLENGE and Onyx HIO board manages transmission rates with rate queues and divisors. The board has eight rate queues organized as two banks: a0-a3 and b0-b3. Each queue can support one peak rate and 63 different sustainable rates. The “a” bank consists of four high-priority queues that are designed for constant bit rate traffic (CBR and VBR channels). The other bank (“b”) contains four low-priority queues and are only used for best-effort traffic.

High-priority queues are serviced before low-priority ones. As long as there is data awaiting transfer on any high-priority queue, low-priority data is not transmitted. This means that, for applications with a constant flow of data, only queues a0-a3 will ever operate.

During startup, the IRIS ATM driver configures each rate queue, as follows:

  • Queues that are mentioned in the /var/atm/atmhw.conf file are configured to a fixed rate, as specified in the file. The IRIS ATM driver never changes the rates for these queues; this ensures that site-specified rates are always available, even when the queues are not actively being used. Table 1-3, lists the supported rates, which range from 0 to 135,991,460 bits per second.

  • Queues that are not mentioned (or are commented out) in the file are left unconfigured. The driver configures these during operation.

During operation, as VCs are created, the driver associates each newly created VC with the queue whose transmission rate best matches the peak rate requested for that VC. For each ATMIOC_CREATEPVC or ATMIOC_SETUP command, the driver looks for a queue whose transmission rate best matches the rate requested in the API call, as follows:

  • For VCs carrying best-effort traffic, the driver uses the low-priority queue whose rate is closest to, but slower than, the requested peak rate.

  • For VCs carrying CBR and VBR traffic, the driver uses the high-priority queue whose configured rate exactly matches the requested peak rate. If the requested rate does not exist, the driver searches for a high-priority queue with the following characteristics and reconfigures it to the requested peak rate:

    • A queue that does not currently have a VC associated with it.

    • A queue that was not configured from the atmhw.conf file during startup.

    Note: There can be dozens of CBR and VBR virtual channels active on a board, but the peak rate for each one must be one of the four rates that are configured on the high-priority queues.

To set the sustainable transmission rate for a particular VC, one of the board's configured rates is divided by a divisor (ranging between 1 and 64). The IRIS ATM driver sets all divisors. Peak rates for CBR, VBR, or best-effort traffic use divisors of 1. Sustainable (average) rates for VBR traffic use divisors from 2 through 64 (inclusive).

To summarize, the IRIS ATM-OC3c HIO board simultaneously makes available for selection up to 8 different peak rates and up to 504 (8x63) sustainable rates. Four of these peak rates are available for use by CBR and VBR VCs. Not all of these available selections can be actively used simultaneously, since this exceeds the board's bandwidth. Rates that are not currently associated with an open VC can be reconfigured to a newly requested rates.

Table 1-3 summarizes the default settings configured for the IRIS ATM-OC3c HIO board's rates.

Table 1-3. Default Transmission Rates on ATM-OC3c HIO Board's Queues


Number Id


String Id

Default Cellrate (in ATM Cells Per Second)

Default Bit Rate (in User Payload Bits Per Second)

Priority / Use





High / CBR, VBR[a]





High / CBR, VBR





High / CBR, VBR





High / CBR, VBR





Low / BE





Low / BE





Low / BE





Low / BE

[a] CBR = constant bit rate; VBR = variable bit rate; BE = best-effort

A board is oversubscribed when the sum of all the open VCs multiplied by their average transmission rates is greater than the board's total payload bandwidth.[2] The IRIS ATM software contains a number of features that prevent performance degradation due to oversubscription. Whenever there is even one VC open for a CBR or VBR traffic contract, the IRIS ATM software refuses to create new VCs once the board's total payload bandwidth is allocated to open VCs (including best-effort ones).[3]

If all the VCs on a board are best-effort (regardless of which queues they are using), the IRIS ATM software allows the board to become oversubscribed and handles the transmission in the best manner possible.

Note: The default Transmission Control Protocol/Internet protocol (TCP/IP) configuration uses the maximum bandwidth for any connection. Therefore, a single TCP/IP connection can oversubscribe the port it uses and prevent CBR traffic. To prevent this, there are two options: (1) reduce the default TCP/IP bandwidth (for example, by editing the /var/atm/ifatm.conf file) or (2) use ifconfig to disable the TCP/IP logical network interfaces.

IRIS ATM-OC3c XIO Board for Origin2000 and Onyx2 Platforms

The IRIS ATM-OC3c XIO board for Origin2000 and Onyx2 platforms manages transmission rates with a cell-slot table that is controlled by firmware. There is one table for each port. The table has one entry for every cell-slot in the data stream going to the transmit SONET section of the board (illustrated in Figure 1-4). Due to this design, this board supports a virtually unlimited number of peak rates and there is no configuration required for the rates. In addition, a VC's sustainable rate is identical to its peak rate.

When an API call is made to create a VC, the software automatically creates enough entries in the cell-slot table to generate the transmission rate. If the request cannot be granted, an error is returned, as explained below. The driver for the IRIS ATM-OC3c 4Port XIO board does not allow oversubscription of any port. Whenever a requested rate cannot be provided, the request is denied. A denial can be due to either of these reasons:

  • Not enough table entries are free to create the requested transmission rate, that is, the request is denied when filling it would oversubscribe the line rate.

  • The spacing possible with the currently available table entries is not even enough to create a steady data flow for the VC. For example, if the table entries for a requested rate need to be spaced at intervals of 50 (table entries 8, 58, 108, 158, etc. or table entries 3, 53, 103, 153, etc.), the request is denied when one or more of the needed table entries are already filled and a nearby alternate cannot be found. This denial can occur even though the requested rate does not oversubscribe the connection's line rate.

    Figure 1-4. Generation of Transmission Rates in Origin2000 and Onyx2 Platforms

    Generation of Transmission Rates in Origin2000 and Onyx2

User-Level Commands

The IRIS ATM software includes utilities in the /usr/etc directory (atmarp, atmconfig, ifatmconfig,atmstat , and atmtest) and the /usr/lib/atm/bin directory (sigtest). Each utility is briefly described in the following sections. Complete details are provided in the online man pages.


The atmarp utility provides command-level support for displaying and reloading the IP-to-ATM address resolution table. Also, it operates as an IP-to-PVC address resolution daemon, managing the mappings between VCs, ATM hardware, and ATM logical network interfaces.

Note: The /etc/init.d/network.atm IP startup script invokes this utility during each system startup or each invocation of the script. The command loads the contents of the /var/atm/pvc.conf IP-to-VC address mapping file into the kernel-resident address resolution table, maintains the file, and responds to address resolution requests.


The atmconfig utility provides command-level support for on-the-fly configuring and controlling of the ATM hardware:

  • Configure the state of ATM ports up or down

  • Configure a port to operate without an ATM switch

  • Configure transmission rates on rate queues

  • Configure the size and the number of on-board transmit and receive buffers

  • Write firmware onto the Electrically Erasable Programmable Read-Only Memory (EEPROM)

  • Reset and reinitialize a port


The ifatmconfig utility provides command-level support for setting RFC 1577 Logical IP Subnetwork (LIS) parameters for IP-over-ATM. The command allows you to configure the ATM address resolution server, the time out for inactive VCs, the maximum cellrate to use for the VCs, and the ATM physical port to use for each LIS. Each ATM LIS appears as a logical network interface that can be given an IP address and can be enabled or disabled with ifconfig , just like other conventional IP network devices.

Note: The IRIS ATM startup script (/etc/init.d/atm) invokes this utility during each system startup or each invocation of the script, telling it to read the /var/atm/ifatm.conf LIS configuration file for settings of these parameters.


The atmstat utility provides command-level support for monitoring the status and operational statistics of ATM interfaces and IRIS ATM-OC3c ports.


The atmtest utility provides command-level support for testing data transmission over the ATM subsystem when it is physically looped back (that is, a port's output is connected to the same port's input). Command line options allow you to control parameters such as the length of the randomly generated data and the speed at which it is sent.


The sigtest utility provides command-level support for testing data transmission and reception for switched virtual circuits. The program allows you to create the following types of connections:

  • A point-to-point loopback connection through the switch: a transmitting VCC to the switch that feeds into a receiving VCC from the switch. The transmitter and receiver are two instances of sigtest running on the same system.

  • A point-to-point connection between two different systems that are both running sigtest.

  • A point-to-multipoint connection in which the members of the party (the receivers) can include any combination of the following: one receiving sigtest session on the same system that is setting up the call, and one receiving sigtest session on each remote system.

[1] An InverseARP request is a request for an IP address given a hardware address.

[2] When a VC does not specify a sustainable rate, the average rate that is used for this calculation is the peak rate.

[3] Total OC3c bandwidth is 155.52 megabits per second; however, of this, about 87.2% (135,631,698 bits) is available for user data. This is referred to as the payload bandwidth.