The atm_address_t structure contains an ATM subsystem's network layer address, used for identifying users (the two endpoints) of a VC. Separate addresses are used for the called and the calling ATM subsystems. All fields of this address, except the ESI and SEL fields of the ATM network service access point (NSAP), are assigned by an endpoint's switch.

Table 3-2, describes the atm_address_t structure. The first byte (addrType field) of the structure indicates the type of address: null, ATM NSAP, or native-E.164. The remaining field, addr, contains either a 20-byte ATM NSAP address (array of characters) or a variable-length E.164 address structure.

Figure 3-5. ATM NSAP Format

Following is an example of the atm_address structure, as defined in the sys/atm_user.h file:

typedef struct atm_address {
      #define NULLADDR_TYPE 0 /* No address specified */
      #define NSAP_TYPE 0x02
      #define E164_TYPE 0x11

char addrType; /* one of the above types */
union {
          nsap_address_t nsap;
          e164_address_t e164;
      } addr;
} atm_address_t;

#define AFI_DCC 0x39
#define AFI_ICD 0x47
#define AFI_E164 0x45

typedef char nsap_address_t[20];

typedef struct e164_address {
      unsigned char len;
      char addr[15];
} e164_address_t;

The cellrate_t structure (described in Table 3-5) is used to specify an SVC's transmission rate and other traffic contract parameters. The user selects one of the cellrate types listed in Table 3-4, and specifies that selection in the first byte of the cellrate_t structure. The format for the remaining portions of the cellrate_t structure depends on the content of the cellrate_type field. The various formats are described in Table 3-5. The specified peak cellrate must be supported by the hardware subsystem, as described in the “Characteristics of the ATM-OC3c Hardware” in Chapter 1; each IRIS ATM board handles transmission rates differently.

Following is an example of the cellrate_type structure, as defined in the sys/atm_user.h file:

typedef struct {
      char cellrate_type; /* a value from Table 3-4 */

      union {
          /* for cellrate_type = CRT_PEAK, CRT_PEAK_TAG */
          struct {
              int pcr0;
              int pcr01;
          } pcr_0_01;

          /* for cellrate_type = CRT_PEAK_AGG, CRT_BEST_EFFORT */
          struct {
              int pcr01;
          } pcr_01;

          /* for cellrate_type = CRT_PSB, CRT_PSB_TAG */
          struct {
              int pcr01;
              int scr0;
              int mbs0;
          } psb_0_01;

          /* for cellrate_type = CRT_PSB_AGG */
          struct {
              int pcr01;
              int scr01;
              int mbs01;
          } psb_01;

      } rate;
} cellrate_t;

Many of the ioctl() SVC commands provide information returned from the ATM network that indicates the cause when a signaling message fails or is rejected. The structure used for this information is reject_reason_t, summarized in Table 3-6.

Following is an example of the reject_reason_t structure, as defined in the sys/atm_user.h file:

typedef struct {
      char cause;/* value from Table C-1 or Table C-2 */
      char location;/* value from Table 3-7 */
      char diags[4];/* reserved for future use */
} reject_reason_t;

The 1-byte quality of service variables (fwdQOS and bwdQOS) are used in a number of ATM signaling commands to specify the forward and backward ATM service classes. Table 3-8, summarizes the valid values.

The broadband low layer information (BLLI) variable is used in a number of ATM signaling commands to specify or communicate the ATM user network interface (UNI) BLLI for a virtual channel connection (VCC). Calling parties can specify one to three BLLI options in their setup requests; after the request succeeds, the single negotiated BLLI option is returned in the first element of the array. Called parties register for one option. Each BLLI value can be registered (with ATMIOC_REGISTER) by only one process at a time. (This does not mean one VC, since by forking, the registered process can support multiple VCs, as explained in “ATMIOC_ACCEPT”.) Table 3-9, summarizes the supported BLLI values.

When the BLLI_ANY value is specified in an ATMIOC_REGISTER call, any incoming BLLI value from the other party is accepted (including a null BLLI). Use of all other values requires that the other party's specified BLLI selection match exactly; if there is no match, the IRIS ATM software rejects the connection request and does not place it on a reception queue.

The 1-byte BearerClass variable is used in a number of ATM signaling commands to specify the broadband bearer (also called transport or network) capability. Table 3-10, summarizes the valid values. See ATM UNI 3.1, Appendix F, for usage guidelines.

CSDU is a shortened version of CPCS-SDU, which stands for common-part convergence sublayer service data unit. The 2-byte MaxCSDU integer value specifies the maximum size for the data units (packets) at the convergence sublayer of the AAL layer. This variable is subject to negotiation during connection setup, so the MaxCSDU sizes that are actually used are not necessarily those requested with the SETUP, MPSETUP, or REGISTER command.

Valid values range from 8 to 0x2FF8, and must be divisible by 8.

Separate MaxCSDU sizes are specified for the forward and the back channels of a VC. The fwdMaxCSDU size specifies a maximum packet size for the forward channel (that is, the channel on which the calling party transmits and the called party receives). The bwdMaxCSDU size specifies a maximum packet size for the back channel (that is, the channel on which the calling party receives and the called party transmits).

---

Note: The forward and back channels are always labeled from the calling party's viewpoint.

---

The ATMIOC_ACCEPT ioctl() command accepts a connection setup request that has already been retrieved by an ATMIOC_LISTEN call. The file descriptor used in this call must be a new file descriptor for the same device used in the ATMIOC_REGISTER call. The application must block until the ATM software replies, which it does when an ATM UNI CONNECT ACKNOWLEDGE message returns from the calling party. The request is not removed from the queue until the call setup has completed (either by creating the SVC or by acknowledging a rejection). While waiting for the CONNECT ACKNOWLEDGE message, the program that made the ioctl() call is put to sleep.

Invoking this ioctl() command causes the ATM signaling software to generate an ATM UNI CONNECT message. (An ATMIOC_LISTEN ioctl() command must have completed successfully before the ATMIOC_ACCEPT command can be invoked.) If the application wants to open multiple SVCs simultaneously for the associated traffic contract, it forks the new file descriptor (new_fd_atm) as soon as the ATMIOC_ACCEPT command returns. At that point, the application can retrieve (using ATMIOC_LISTEN) and accept (using ATMIOC_ACCEPT) the next item on the queue. The application can receive (read()) data from all its open SVCs.

When the application wants to close a receiving SVC (accept no more requests), it simply closes the file descriptor. If one or more child processes have been forked, and they are still running, they must be killed or must also close their file descriptors. When the original file descriptor is closed, the ATM signaling software generates an ATM UNI RELEASE message to the calling party.

open (new_fd_atm, O_RDWR);
ioctl (new_fd_atm, ATMIOC_ACCEPT, &accept);
<wait for return, proceed as described in the next paragraph>

typedef struct {
      int userHandle;
      int callHandle;
} atm_accept_t;

The ATMIOC_ADDPARTY ioctl() command is invoked by a calling party to cause the ATM signaling software to add another party to an already existing point-to-multipoint connection. The ATM signaling software issues an ATM UNI ADDPARTY message. No backward channel is created for this SVC.

ioctl (mp_fd_atm, ATMIOC_ADDPARTY, &addparty);

typedef struct {
      addpartyparams_t addparams;
      reject_reason_t reject;
} atm_addparty_t;

typedef struct {
      atm_address_t calledNumber;
      int partyHandle;
} addpartyparams_t;

The ATMIOC_DROPPARTY ioctl() command is invoked by a calling party to cause the ATM signaling software to drop a called party from an existing point-to-multipoint connection. This ioctl() command causes the ATM signaling software to issue an ATM UNI DROPPARTY message.

ioctl (mp_fd_atm, ATMIOC_DROPPARTY, &dropparty);

typedef struct {
      int partyHandle;
} atm_dropparty_t;

The ATMIOC_GETVCCTABLEINFO ioctl() command retrieves the entire virtual channel table (both transmit and receive VCs) from any IRIS ATM port. The port must be in the up state.

ioctl (fd_atm, ATMIOC_GETVCCTABLEINFO, &sioc);

typedef struct atmsioc {
      void *ptr;
      u_int len;
} atmsioc_t;

typedef struct {
      int         vpi;
      int         vci;
      cellrate_t  xmit_cellrate;
      cellrate_t  recv_cellrate;
      int         xmitQOS;
      int         recvQOS;
} atm_vcce_t;

The ATMIOC_LISTEN ioctl() command retrieves connection setup requests from the input queue created by the ATMIOC_REGISTER call. The program calling this ioctl() must block until the ATM software replies, which it does whenever there is a request on the queue. If there are currently no requests waiting, the caller of the ioctl() is put to sleep and awakened when a request becomes available.

Each invocation of this ioctl() retrieves the topmost (longest awaiting) item on the queue. Each retrieval provides identification tags (handles) and the negotiated traffic contract for the SVC, which may be different from the parameters specified in the ATMIOC_REGISTER call. The request is not actually removed from the queue until the request has been completely processed by an ATMIOC_ACCEPT or ATMIOC_REJECT.

---

Note: An ATMIOC_REGISTER ioctl() command must have completed successfully before ATMIOC_LISTEN can be invoked.

---

ioctl (registered_fd_atm, ATMIOC_LISTEN, &listen);

typedef struct {
      int userHandle;
      int callHandle;
      u_short fwdMaxCSDU;
      u_short bwdMaxCSDU;
      char blli;
      atm_address_t caller;
      cellrate_t xmitcellrate;
} atm_listen_t;

The ATMIOC_MPSETUP ioctl() command is invoked by a calling party to cause the ATM signaling software to initiate an ATM UNI SETUP request message for the first party on a point-to-multipoint channel. No backward channel is created, so the device must be write-only. The application must block until the ATM driver replies, which it does when the SVC is either ready to use or has been refused. The driver puts the calling process to sleep until the call is complete or has been rejected. To maximize throughput, set the size for the VC's user protocol data units (CSPDUs) to MAX_CS_PDU.

When the remote endpoint accepts the connection request, the driver wakes the caller up and returns the negotiated traffic contract, which can be different (smaller) than what was specified in the call. Once open, the SVC is accessed by write() calls to the specified file descriptor. The file descriptor opened for the ATM device (fd_atm) should be writable only.

To add additional parties and drop individual parties on this SVC, use the ATMIOC_ADDPARTY and ATMIOC_DROPPARTY commands.

To tear down this SVC, the application uses the ATMIOC_DROPPARTY command for each party that has been added to the SVC. This causes the ATM signaling software to generate an ATM UNI DROPPARTY message for each party, until only one party remains, at which point a RELEASE message is generated. After the final party is dropped, the application can close the file descriptor.

---

Note: If the application closes the file descriptor without calling ATMIOC_DROPPARTY for each party, the software still smoothly releases and tears down the SVC.

---

ioctl (fd_atm, ATMIOC_MPSETUP, &mpsetup);

typedef struct {
      mpcallparams_t callparams;
      reject_reason_t reject;
} atm_mpsetup_t;

typedef struct {
      atm_address_t calledNumber;
      atm_address_t callingNumber;
      u_short fwdMaxCSDU;
      cellrate_t fwdCellRate;
      char fwdQOS;
      char blliCount;
      char blli[3];
      char bearerClass;
      char sscsType; /* reserved*/
      char bhli; /* reserved*/
      int partyHandle;
} mpcallparams_t;

The ATMIOC_REGISTER ioctl() command is invoked by an application to inform the IRIS ATM signaling software that it is present and ready as a called party. The file descriptor must be open for read-write access. The application must block until the ATM driver replies, which it does when the SVC is either ready to use or has been refused. The driver puts the calling process to sleep until the software has completed the SVC registration. When the ATM subsystem replies to this ioctl(), the application should immediately call ATMIOC_LISTEN to retrieve the first queued connection request.

Each ATMIOC_REGISTER call defines a traffic contract. For each registered traffic contract, the ATM subsystem maintains a queue of incoming connection (SVC) setup requests. The ATM signaling software compares the registered traffic contracts to incoming connection setup request parameters. When the incoming values are higher than the registered values, the software negotiates down to the traffic contract. When the incoming values are equal to or smaller than the traffic contract, the software accepts the setup request and places it on the queue. This ioctl() fails if the specified traffic contract is currently registered.

When this ioctl() returns successfully, the ATM signaling software has created a queue of the length specified by the application and has started queuing incoming connection (ATM UNI SETUP) requests. As long as the file descriptor remains open, the ATM signaling software continues to queue requests.

When the application no longer accepts connection requests for this traffic contract, it simply closes the file descriptor. The ATM signaling software generates ATM UNI RELEASE messages for the unretrieved requests remaining in the queue, and stops accepting requests for the associated traffic contract. Once the file descriptor is closed, the application cannot retrieve any more of the queued connection requests.

ioctl (fd_atm, ATMIOC_REGISTER, &register);

typedef struct {
      u_short fwdMaxCSDU;
      u_short bwdMaxCSDU;
      short listenQlength; /* Nmbr of outstndng reqs to queue */
      char blli;
      char sscsType; /* reserved for future use */
      int cause;  /* if ioctl fails with EIO, cause contains */
              /* a value from Table C-2 */
} atm_register_t;

The ATMIOC_REJECT ioctl() command refuses a connection setup request (that has already been retrieved by ATMIOC_LISTEN) and indicates the reason for the rejection. (An ATMIOC_LISTEN ioctl() must have completed successfully before ATMIOC_REJECT can be invoked.) ATMIOC_REJECT is invoked on the same file descriptor as the ATMIOC_LISTEN call. This ioctl() causes the ATM signaling software to issue an ATM UNI RELEASE message.

The explanation for the rejection is given in the call's argument and can be any of the ATM UNI cause codes, summarized in Table C-2.

The program calling this ioctl() can retrieve the next request from the queue immediately.

---

Note: This ioctl() cannot be used to release an existing SVC or to stop queuing SVC requests onto a registered queue. To stop accepting SVC setup requests, an application must close the file descriptor associated with the ATMIOC_REGISTER. To clear an active SVC, the calling application closes the file descriptor associated with ATMIOC_SETUP.

---

ioctl (listen_fd_atm, ATMIOC_REJECT, &reject);

typedef struct {
      int callHandle;
      int cause;
} atm_reject_t;

The ATMIOC_SETUP ioctl() command is invoked by a calling party to set up a point-to-point SVC with traffic contract parameters specified in the call's argument. The application must block until the ATM driver replies, which it does when the SVC is either ready to use or has been refused. The driver puts the calling process to sleep until the call is complete or has been rejected.

This ioctl() causes the ATM signaling software to initiate an ATM UNI SETUP request message for creation of both a forward and a backward channel. To maximize throughput, set the size for the forward VC's user protocol data units (CSPDUs) to MAX_CS_PDU. When the remote endpoint accepts the connection request, the driver wakes the caller up and returns the negotiated traffic contract, which can be different (smaller) than what was specified in the call. Once open, the SVC is accessed by read() operations from and write() operations to the specified file descriptor. The file descriptor opened for the ATM device (fd_atm) should be readable and writable.^[9]

To tear down this SVC, the application simply closes the file descriptor. This causes the ATM signaling software to generate an ATM UNI RELEASE message.

ioctl (fd_atm, ATMIOC_SETUP, &setup);

typedef struct {
      ppcallparams_t callparams;
      reject_reason_t reject;
} atm_setup_t;

typedef struct {
      atm_address_t calledNumber;
      atm_address_t callingNumber;
      u_short fwdMaxCSDU, bwdMaxCSDU;
      cellrate_t fwdCellRate,bwdCellRate;
      char fwdQOS, bwdQOS;
      char blliCount;
      char blli[3];
      char bearerClass;
      char sscsType; /* reserved for future use */
      char bhli; /* reserved for future use */
} ppcallparams_t;