sa_util(3)

NAME

sa_util, sa_open, sa_close, sa_attach, sa_detach, sa_bind, sa_unbind, sa_setraw, sa_add_vpci, sa_delete_vpci, sa_allocate_bw, sa_release_bw − Sun ATM driver utilities

SYNOPSIS

cc [ flag ... ] file ... −latm [ library ... ]

#include <atm/sa.h>

int sa_open(register char ∗interface);

int sa_close(int fd);

int sa_attach(int fd, u_long ppa, int timeout);

int sa_detach(int fd, int timeout);

int sa_bind(int fd, u_long sap, int timeout);

int sa_unbind(int fd, int timeout);

int sa_setraw(int fd);

int sa_add_vpci(int fd, vci_t vpci, int encap, int buf_type);

int sa_delete_vpci(int fd, vci_t vpci);

int sa_allocate_bw(int fd, int bw);

int sa_release_bw(int fd);

MT-LEVEL

Safe.

AVAILABILITY

The functionality described in this man page is available in the SUNWatma package included with a SunATM adapter board. The libatm.a library, which is located in /usr/lib, must be included at compile time as indicated in the synopsis.

DESCRIPTION

These utilities perform various operations on the SunATM device driver, sa. They may be used by application programs that need to transmit and receive data over an ATM connection to set up a data stream to the ATM driver.

Data may be transmitted over a vc connection in one of two modes: raw mode, or dlpi mode. The mode is specified by the choice of encapsulation indicated in the call to sa_add_vpci(). NULL encapsulation indicates raw mode, while LLC encapsulation indicates dlpi mode. The mode chosen defines the format in which data should be sent to the driver.

Raw mode implies that only a single mblock will be sent to the driver, containing a four-byte vpci followed by the data. When a message is received on a vpci running in raw mode, it will be directed to upper layers based on the vpci. The four-byte vpci will be sent up with the data if sa_setraw() has been called; if sa_setraw() has not been called, the vpci will be stripped and only the data will be sent up.

DLPI mode implies that two mblocks will be sent to the driver. The first, of type M_PROTO, contains the dlpi message type, which is dl_unitdata_req for transmit and dl_unitdata_ind for receive. The vpci is included in this mblock as well; its format is defined in the header file <sys/dlpi.h>. The second mblock is of type M_DATA and contains the message. When the driver gets a message of this type from the upper layer, it will remove the first mblock, add a LLC header containing the sap which has been bound to this stream using sa_bind() to the message mblock, and transmit it. On receive, the LLC header is stripped, the M_PROTO mblock is added, and the two-mblock structure is sent up the stream indicated by the sap in the LLC header.

NOTE: If the application is running in user space rather than kernel space, the M_PROTO and M_DATA mblocks correspond to the ctl and data buffers, respectively, which are passed into putmsg(2) or received from getmsg(2).

sa_open() opens a stream to the physical interface (i.e. sa0, sa1, etc.) passed in as a null-terminated string in interface. On success, the file descriptor ( > 0 ) is returned.

sa_close() closes the stream specified by its file descriptor, fd.

sa_attach() associates a physical point of attachment, ppa, with an opened sa device specified by its file descriptor, fd. The ppa is usually defined as the physical interface number (0 for sa0, 1 for sa1, etc.). timeout may optionally be used to specify an amount of time in milliseconds to wait for the function to complete. The function will fail if it does not complete in the specified amount of time. Possible values for timeout are -1, which blocks until completion, 0, which returns immediately, or a number greater than 0 which specifies a number of milliseconds to wait. This value will be rounded up to an implementation-dependent minimum value, which is currently at approximately 100 ms.

sa_detach() detaches the stream specified by its file descriptor fd from its ppa. Values of timeout apply as described in sa_attach().

sa_allocate_bw() specifies a bandwidth amount in megabits per second (in the SunATM-155 products, the user may allocate up to 135 Mbps; 2 Mbps is reserved by the ATM software stack, and 20 Mbps is lost to cell header and physical layer overhead) passed in as bw, that will be allocated for transmitting data from the stream identified by the file descriptor fd. All unallocated bandwidth is assigned to IP and dlpi mode traffic. This step is not necessary if a stream is only to be used to receive data; and SHALL NOT be called if a stream is using dlpi mode.

sa_release_bw() releases all bandwidth that has been previously allocated to the stream identified by fd.

sa_add_vpci() adds the given virtual path connection identifier, vpci, to those recognized on the specified stream (identified by its file descriptor, fd). The type of encapsulation that is being used on this connection must also be specified in encap; the possible values are NULL_ENCAP, LLC_ENCAP, and NLPID_ENCAP, as defined in <atm/saioctl.h>. Finally, the buffer type must be specified in buf_type; definitions may also by found in <atm/saioctl.h> for the possible types SMALL_BUF_TYPE, BIG_BUF_TYPE, and HUGE_BUF_TYPE.

sa_delete_vpci() deletes given virtual path connection identifier, vpci, from the specified stream (identified by its file descriptor, fd).

sa_bind() binds a service access point, sap, to an opened stream, specified by its file descriptor, fd. sap values of 0x800 and 0x806 are reserved for IP and ARP traffic, respectively; the user shall not use these values. The sap is used by the driver to direct traffic to upper layers if LLC encapsulation is used. This function also has a timeout parameter; the values of timeout described in sa_attach() apply in sa_bind() as well.

sa_unbind() disassociates a stream-to-sap binding. The stream is specified by its file descriptor, fd. Values of timeout apply as described in sa_attach().

sa_setraw() indicates to the driver that the stream specified by the file descriptor fd will be transmitting and receiving raw data which will be interpreted directly by the application at the stream head. The only header information included in messages passed down the stream will be the 4-byte virtual path connection identifier. When a message is received, the vpci will be used to direct the message to upper layers.

The ordering of the sa utility function calls is important. After calling sa_open(), the order must be sa_attach(), followed by sa_allocate_bw() if required, and sa_add_vpci(). Next, depending on the type of encapsulation used on this stream, should be either sa_bind() for LLC encapsulation or sa_setraw() for for null encapsulation. All functions must be called only once per interface, with the exception of sa_add_vpci(), which may be called multiple times to support multiple vpcis.

RETURN VALUES

All functions return -1 on error. With the exception of sa_open, which returns the file descriptor on success, all functions return 0 on success.

EXAMPLES

The following example opens a stream to sa0 and sets up that stream to communicate over vpci 0x100 at 10 Mbits/sec in raw mode.

#include <stdio.h>
#include <sys/types.h>
#include <sys/stropts.h>
#include <sys/errno.h>
#include <atm/sa.h>
main()
{

char     interface[] = "sa0";
int      fd;
int      ppa;
int      bw = 10;
int      vpci = 0x100;
char     ctlbuf[256];
char     databuf[256];
struct strbuf   ctl, data;
ctl.buf = ctlbuf;
data.buf = databuf;
ctl.maxlen = data.maxlen = 256;
ppa = atoi(&interface[strlen (interface) - 1]);
if ((fd = sa_open(interface)) < 0) {

perror("open");
exit(-1);

}
sa_attach(fd, ppa);
if (sa_allocate_bw(fd, bw) < 0) {

perror("sa_allocate_bw");
exit(-1);

}
if (sa_add_vpci(fd, vpci, NULL_ENCAP, BIG_BUF_TYPE) < 0) {

perror("sa_add_vpci");
exit(-1);

}
if (sa_setraw(fd) < 0) {

perror("sa_setraw");
exit(-1);

}
<construct a message to pass down in ctlbuf and databuf>
if (putmsg(fd, &ctl, &data, 0) < 0) {

perror("putmsg");
exit(-1);

}

The following example opens a stream to sa0 and sets up that stream to communicate over vpci 0x100, using sap 0x100, in dlpi mode.

#include <stdio.h>
#include <sys/types.h>
#include <sys/stropts.h>
#include <sys/errno.h>
#include <sys/dlpi.h>
#include <atm/sa.h>
main()
{

char     interface[] = "sa0";
int      fd;
int      ppa;
int      vpci = 0x100;
int      ∗vpcip;
int      sap = 0x100;
char     ctlbuf[256];
char     databuf[256];
struct strbuf      ctl, data;
dl_unitdata_req_t ∗dludp;
ctl.buf = ctlbuf;
data.buf = databuf;
ctl.maxlen = data.maxlen = 256;
ppa = atoi(&interface[strlen (interface) - 1]);
if ((fd = sa_open(interface)) < 0) {

perror("open");
exit(-1);

}
sa_attach(fd, ppa);
if (sa_add_vpci(fd, vpci, LLC_ENCAP, BIG_BUF_TYPE) < 0) {