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

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) {
      perror("open");
      exit(-1);
}

---

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

---

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) {
      perror("close");
}

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;
fd=open("/dev/atm0",O_WRONLY|O_NDELAY);

/*Set the nonblocking mode*/

if(ioctl(fd,FIONBIO,O_NDELAY)<0
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.

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

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

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:

The following rules apply to transmissions:

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.

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

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

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

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

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

ioctl(fd_atm, COMMAND
, arg);

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:

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

---

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:

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

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

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.

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:

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.

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:

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:

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.

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.^[4] 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).^[5]

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.

---

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:

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:

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: