ATM_INTRO(4N) DEVICES AND NETWORK INTERFACES ATM_INTRO(4N) NAME atm_intro - introduction to ATM user-level library functions DESCRIPTION FORE Systems' user-level ATM library routines provide a portable interface to the ATM data link layer. The library routines for SunOS and IRIX platforms are STREAMS-based and communicate with the ATM device driver using the Data Link Provider Interface (OSI Work Group, Unix International). The library routines for ULTRIX platforms are socket-based and communicate with the ATM device driver using the proto- col switch table. Although the internals differ, the same application programming interface is provided on all plat- forms. The ATM library routines provide a connection-oriented client and server model. Before data can be transferred a connection has to be established between client and server. The data transfer phase is a best effort delivery system. End-to-end flow control and retransmission are left to the application. The ATM library can be used to establish connections between two end-systems in a point-to-point configuration (i.e. in the absence of a switch). ADDRESSING End-systems and switches can be identified by name and Net- work Service Access Point (NSAP). The name is a unique ASCII string. The NSAP is also unique and specifies the ATM-layer network address. An ATM application is referred to as an ATM end-point. Each ATM end-point has a unique end-point address which is used for establishing communications. An end-point address is comprised of an NSAP and an Application Service Access Point (ASAP). The following structure is used to specify ATM end- points for use in the ATM library routines. typedef u_int Atm_sap; /* Service Access Point */ struct Atm_address { /* hardware address */ char addr[8]; }; typedef struct Atm_address Atm_address; struct Atm_endpoint { Atm_sap asap; /* Application Service Access Point */ Atm_address nsap; /* Network Service Access Point */ }; typedef struct Atm_endpoint Atm_endpoint; FSI Release 2.3 Last change: 7 June 1994 1 ATM_INTRO(4N) DEVICES AND NETWORK INTERFACES ATM_INTRO(4N) An ASAP is unique for a given end-system and is associated by the ATM device driver with a file desctriptor. An NSAP is comprised of an ATM switch id and a port number on the switch. Each ATM end-system is attached to a particular ATM switch port. The NSAP is used by the ASX switch control daemon (see asxd(8C)) to route connection requests and responses through the network. An NSAP is exchanged between ATM user-level library functions and the application. It typically does not need to be interpreted by the application. For example atm_gethostbyname(4N) returns an NSAP which can be passed directly to atm_connect(4N) by the application, and atm_listen(4N) returns an NSAP which can be passed directly to atm_accept(4N). ASAPs in the range of 0 through SAPS_RESERVED are reserved for use by the ATM device driver. ASAPs starting at SAPS_UNRESERVED are for general use. CONNECTION ESTABLISHMENT The ATM device driver uses a signaling protocol for estab- lishing connections to remote ATM end-points. The protocol is defined in SPANS: Simple Protocol for ATM Network Signal- ing, available from FORE Systems, Inc. Applications first open a file descriptor with atm_open(4N) and then bind a local ASAP to the file descriptor with atm_bind(4N). The local NSAP is also implicitly bound to the same file descriptor. The remote ASAP and NSAP are associated with the file descriptor when a connect indica- tion or a connect confirmation is received. Connections are established using atm_connect(4N) in combi- nation with atm_accept(4N). These operations allow the data transfer to be specified as simplex (data flowing in one direction), duplex (data flowing in both directions), or multicast (data flowing in one direction to multiple desti- nations). ATM Virtual Path Identifiers (VPI) and Virtual Channel Iden- tifiers (VCI) are allocated by the network during connection establishment. The ATM device driver associates the VPI/VCI with an ASAP which is in turn associated with a file descriptor. When a connection is duplex, both an incoming and an outgoing VPI/VCI are associated with the ASAP; the two need not be the same. Resources (bandwidth) are reserved for each connection. The peak bandwidth is the maximum (burst) rate at which the source produces data, measured in kilobits per second. The mean bandwidth is the average bandwidth expected over the FSI Release 2.3 Last change: 7 June 1994 2 ATM_INTRO(4N) DEVICES AND NETWORK INTERFACES ATM_INTRO(4N) lifetime of the connection, also measured in kilobits per second. The mean burst length is the average size in kilo- bits of packets sent at peak bandwidth. The network uses the bandwidth information in the connection request to reduce the chances of buffer overflow, and will refuse the connection if insufficient resources are avail- able. If the bandwidth is specified as zero, the connection is assumed to carry low-priority, loss-tolerant traffic; such a connection request will not be refused due to lack of intermediate resources. The following structures are used to specify the bandwidth requirements for use in the ATM library routines. struct Atm_qos_range { u_int target; /* target quality of service */ u_int minimum; /* minimum acceptable qos */ }; typedef struct Atm_qos_range Atm_qos_range; struct Atm_qos { Atm_qos_range peak_bandwidth; Atm_qos_range mean_bandwidth; Atm_qos_range mean_burst; }; typedef struct Atm_qos Atm_qos; Connections can be established when two end-systems are con- nected in a point-to-point configuration (i.e. without a switch). In the point-to-point configuration only the ASAP part of ATM end-point address is used to establish connec- tions. The NSAP is ignored. DATA TRANSFER Applications choose the ATM Adaptation Layer (AAL) to be used for data exchange. The following structure is used to specify the AAL for use in the ATM library routines. AAL types 1 and 2 are not currently supported, and types 3 and 4 are treated identically. enum Aal_type { /* Atm Adaptation Layer types */ aal_null, aal_type_1, /* circuit emulation */ aal_type_2, /* variable bit rate video */ aal_type_3, /* connection-oriented data */ aal_type_4, /* connectionless data */ aal_type_5, /* connection-oriented data */ }; typedef enum Aal_type Aal_type; AAL 3/4 and AAL 5 allow the application to send and receive data with the ATM device driver handling all segmentation of FSI Release 2.3 Last change: 7 June 1994 3 ATM_INTRO(4N) DEVICES AND NETWORK INTERFACES ATM_INTRO(4N) the data into ATM cells and the reassembly of ATM cells back into application data. The null AAL allows applications to exchange ATM cells. With this interface other AALs can be implemented by user pro- grams. Cells buffered for transmission and reception are encoded as per FORE Systems' ATM Computer Interface cell format (see the appropriate ATM Computer Interface User's Manual for details). With any given AAL, data transfer can be simplex, duplex, or multicast. Applications statically agree on the data flow type. The following structure is used to specify data flow for use in the ATM library routines. enum Atm_dataflow { simplex, /* unidirectional data flow */ duplex, /* bidirectional data flow */ multicast, /* multicast data flow */ }; typedef enum Atm_dataflow Atm_dataflow; FILES /dev/fa* .../fore/lib/libatm.a .../fore/include/fore_atm/fore_atm_user.h SEE ALSO atm_open(4N), atm_bind(4N), atm_listen(4N), atm_accept(4N), atm_connect(4N), atm_send(4N), atm_recv(4N), atm_close(4N), atm_client(4N), atm_server(4N), atm_error(4N), atm_setbatchsize(4N), atm_getbatchsize(4N), atm_intro(8C), asxd(8C) FSI Release 2.3 Last change: 7 June 1994 4