HARP Native ATM Sockets API =========================== ATM sockets are an extension to the traditional BSD sockets API to allow direct user-level access to native ATM protocol services. The ATM sockets extensions are implemented via the addition of a new protocol family (PF_ATM) and a new socket address structure (struct sockaddr_atm). The HARP implementation of native ATM sockets capabilities is intended to be conformant with The Open Group specifications (with known differences listed below) as defined in the following document: The Open Group: Networking Services (XNS) Issue 5 ISBN 1-85912-165-9 http://www.rdg.opengroup.org/public/pubs/catalog/c523.htm And in particular, it is based on the following ATM-specific sections in the above document: ATM Transport Protocol Information for Sockets ATM Transport Protocol Information for XTI ATM Transport Headers The ATM sockets API is an implementation based on the definitions and descriptions set forth in the following document: The ATM Forum: Native ATM Services: Semantic Description, Version 1.0 af-saa-0048.000 http://www.atmforum.com/atmforum/specs/approved.html Using the HARP Implementation ----------------------------- This document only provides the HARP-specific information necessary for using the ATM sockets API. Please refer to the XNS document described above for all of the general interface specifications. There is also sample source code for an ATM sockets application included at the end of this document. All user definitions for the HARP ATM sockets implementation are contained in the file /usr/include/netatm/atm.h. This file must be included in the user's C program source file. In this file, all HARP extensions to the base XNS specifications are denoted with a comment string of "XNS_EXT". HARP Extensions to XNS Issue 5 ------------------------------ o Socket address structure for ATM addresses An ATM socket address structure was not specifically defined by XNS, although the t_atm_sap structure was defined to be used as an ATM protocol address. Thus, HARP has defined an ATM socket address (using address family AF_ATM) as a 'struct sockaddr_atm', which contains 'struct t_atm_sap' as the protocol address. This structure (properly cast) must be used on all ATM socket system calls requiring a 'struct sockaddr' parameter. o Network Interface Selection socket option (T_ATM_NET_INTF) This option is used to specify the name of the network interface to be used to route an outgoing ATM call using a socket connection. This option is only needed when there are multiple ATM network interfaces defined on a system. If this option is not set, then the first network interface on the first physical ATM interface defined will be used. See the sample application below for an example of the use of this option. o LLC Multiplexing socket option (T_ATM_LLC) For LLC encapsulated VCCs (BLLI Layer 2 Protocol == T_ATM_BLLI2_I8802), HARP has implemented an LLC multiplexing facility. In order to use this multiplexing facility, a user must issue a setsockopt() call specifying the T_ATM_LLC option before the connect() or listen() system call is invoked. If using the LLC multiplexor, the user will only receive PDUs which match the LLC header information specified in the socket option. The kernel multiplexing software will strip the LLC header from all inbound PDUs and add the specified LLC header to all outgoing PDUs - the user will never see the LLC header. For listening sockets, the listener will be notified for all incoming LLC calls (which also meet the other incoming call distribution selection criteria), since the LLC header information is only carried in the data PDUs, not in the signalling protocol. The T_ATM_LLC_SHARING flag is used to denote whether this user wishes to share the VCC with other LLC users requesting similar connection attributes to the same destination. o Application Name socket option (T_ATM_APP_NAME) This option is used to associate an identifier string (typically, the application's name) with an open ATM socket. Currently, it is only used for the "Owner" field in the output of the 'atm show vcc' command. If this option is not set, then the "Owner" field will default to "(AAL5)". See the sample application below for an example of the use of this option. o PVC support The XNS document specifically does not provide support for ATM PVCs. However, due in part to internal HARP requirements (the ILMI daemon), PVC sockets are supported under the HARP implementation. To support PVC sockets, there is a new address format (T_ATM_PVC_ADDR) and address definition (Atm_addr_pvc). Since there is no actual signalling involved in setting up a PVC, a PVC socket connection only defines the local socket-to-pvc connection - the remainder of the virtual circuit through the ATM network to the remote endpoint must be defined independent of the local socket creation. PVC socket connections are only allowed via the connect() system call - listen()/accept() sockets cannot be supported. Also, since there are no circuit parameters signalled, most of the setsockopt() options are silently ignored. o SPANS support HARP has added ATM socket support for the FORE-proprietary SPANS address format (T_ATM_SPANS_ADDR). A SPANS socket can only be established over an ATM physical interface which is using the SPANS signalling manager. There is limited ATM socket option support - the socket options can be set, but most are silently ignored, since they are not applicable to the SPANS protocols. The SPANS socket address support has not been thoroughly tested. o Miscellaneous user convenience typedefs, macros and defines XNS Issue 5 Features Not Supported in HARP ------------------------------------------ o ATM_PROTO_SSCOP The socket protocol for reliable data transport (ATM_PROTO_SSCOP) is not supported in this HARP release. There is some initial skeleton code for SSCOP support, but it was not completed. o Multipoint connections The core HARP code does not provide support for multipoint connections, so, obviously, multipoint socket connections are also not supported. The non-supported socket options are: o T_ATM_ADD_LEAF o T_ATM_DROP_LEAF o T_ATM_LEAF_IND The non-supported socket option values are: o For the T_ATM_BEARER_CAP socket option: o connection_configuration == T_ATM_1_TO_MANY Example ATM Socket Application ------------------------------ The following are simple example client and server applications using the ATM socket API. /* * ATM API sample client application * * This application will open an ATM socket to a server, send a text string * in a PDU and then read one PDU from the socket and print its contents. * */ #include #include #include #include #include #include #define MAX_LEN 4096 /* Maximum PDU length */ #define MY_ID 11 /* BLLI Layer 2 protocol */ #define MY_APPL "Client" Atm_addr_nsap dst_addr = { 0x47, #error FIX ME: Replace the 2 lines below with your nsap prefix and esi address {0x00,0x05,0x80,0xff,0xdc,0x00,0x00,0x00,0x00,0x02,0xff,0xff}, {0x11,0x22,0x33,0x44,0x55,0x66}, 0x00 }; static char message[] = "A message from the client"; void print_cause(int s) { struct t_atm_cause cause; int optlen; optlen = sizeof(cause); if (getsockopt(s, T_ATM_SIGNALING, T_ATM_CAUSE, &cause, &optlen) < 0) { perror("getsockopt(cause)"); return; } fprintf(stderr, "Cause: coding=%d loc=%d cause=%d diag=(%d,%d,%d,%d)\n", cause.coding_standard, cause.location, cause.cause_value, cause.diagnostics[0], cause.diagnostics[1], cause.diagnostics[2], cause.diagnostics[3]); } main(argc, argv) int argc; char **argv; { struct sockaddr_atm satm; struct t_atm_aal5 aal5; struct t_atm_traffic traffic; struct t_atm_bearer bearer; struct t_atm_qos qos; struct t_atm_net_intf netintf; struct t_atm_app_name appname; char buffer[MAX_LEN+1]; int s, n, optlen; /* * Create socket */ s = socket(AF_ATM, SOCK_SEQPACKET, ATM_PROTO_AAL5); if (s < 0) { perror("socket"); exit(1); } /* * Set up destination SAP */ bzero((caddr_t) &satm, sizeof(satm)); satm.satm_family = AF_ATM; #if (defined(BSD) && (BSD >= 199103)) satm.satm_len = sizeof(satm); #endif /* Destination ATM address */ satm.satm_addr.t_atm_sap_addr.SVE_tag_addr = T_ATM_PRESENT; satm.satm_addr.t_atm_sap_addr.SVE_tag_selector = T_ATM_PRESENT; satm.satm_addr.t_atm_sap_addr.address_format = T_ATM_ENDSYS_ADDR; satm.satm_addr.t_atm_sap_addr.address_length = sizeof(Atm_addr_nsap); bcopy((caddr_t)&dst_addr, (caddr_t)satm.satm_addr.t_atm_sap_addr.address, sizeof(dst_addr)); /* BLLI Layer-2 protocol */ satm.satm_addr.t_atm_sap_layer2.SVE_tag = T_ATM_PRESENT; satm.satm_addr.t_atm_sap_layer2.ID_type = T_ATM_USER_ID; satm.satm_addr.t_atm_sap_layer2.ID.user_defined_ID = MY_ID; /* BLLI Layer-3 protocol */ satm.satm_addr.t_atm_sap_layer3.SVE_tag = T_ATM_ABSENT; /* BHLI protocol */ satm.satm_addr.t_atm_sap_appl.SVE_tag = T_ATM_ABSENT; /* * Set up connection parameters */ aal5.forward_max_SDU_size = MAX_LEN; aal5.backward_max_SDU_size = MAX_LEN; aal5.SSCS_type = T_ATM_NULL; optlen = sizeof(aal5); if (setsockopt(s, T_ATM_SIGNALING, T_ATM_AAL5, (caddr_t)&aal5, optlen) < 0) { perror("setsockopt(aal5)"); exit(1); } traffic.forward.PCR_high_priority = T_ATM_ABSENT; traffic.forward.PCR_all_traffic = 100000; traffic.forward.SCR_high_priority = T_ATM_ABSENT; traffic.forward.SCR_all_traffic = T_ATM_ABSENT; traffic.forward.MBS_high_priority = T_ATM_ABSENT; traffic.forward.MBS_all_traffic = T_ATM_ABSENT; traffic.forward.tagging = T_NO; traffic.backward.PCR_high_priority = T_ATM_ABSENT; traffic.backward.PCR_all_traffic = 100000; traffic.backward.SCR_high_priority = T_ATM_ABSENT; traffic.backward.SCR_all_traffic = T_ATM_ABSENT; traffic.backward.MBS_high_priority = T_ATM_ABSENT; traffic.backward.MBS_all_traffic = T_ATM_ABSENT; traffic.backward.tagging = T_NO; traffic.best_effort = T_YES; optlen = sizeof(traffic); if (setsockopt(s, T_ATM_SIGNALING, T_ATM_TRAFFIC, (caddr_t)&traffic, optlen) < 0) { perror("setsockopt(traffic)"); exit(1); } bearer.bearer_class = T_ATM_CLASS_X; bearer.traffic_type = T_ATM_NULL; bearer.timing_requirements = T_ATM_NULL; bearer.clipping_susceptibility = T_NO; bearer.connection_configuration = T_ATM_1_TO_1; optlen = sizeof(bearer); if (setsockopt(s, T_ATM_SIGNALING, T_ATM_BEARER_CAP, (caddr_t)&bearer, optlen) < 0) { perror("setsockopt(bearer)"); exit(1); } qos.coding_standard = T_ATM_NETWORK_CODING; qos.forward.qos_class = T_ATM_QOS_CLASS_0; qos.backward.qos_class = T_ATM_QOS_CLASS_0; optlen = sizeof(qos); if (setsockopt(s, T_ATM_SIGNALING, T_ATM_QOS, (caddr_t)&qos, optlen) < 0) { perror("setsockopt(qos)"); exit(1); } #ifdef REMOVE_TO_USE_NET_INTF #error FIX ME: Replace the ni0 below with the local atm network interface name strncpy(netintf.net_intf, "ni0", IFNAMSIZ); optlen = sizeof(netintf); if (setsockopt(s, T_ATM_SIGNALING, T_ATM_NET_INTF, (caddr_t)&netintf, optlen) < 0) { perror("setsockopt(net_intf)"); exit(1); } #endif strncpy(appname.app_name, MY_APPL, T_ATM_APP_NAME_LEN); optlen = sizeof(appname); if (setsockopt(s, T_ATM_SIGNALING, T_ATM_APP_NAME, (caddr_t)&appname, optlen) < 0) { perror("setsockopt(app_name)"); exit(1); } /* * Now try to connect to destination */ if (connect(s, (struct sockaddr *) &satm, sizeof(satm)) < 0) { perror("connect"); print_cause(s); exit(1); } /* * Exchange message with peer */ if (write(s, message, sizeof(message)) != sizeof(message)) { perror("write"); exit(1); } if ((n = read(s, buffer, MAX_LEN)) < 0) { perror("read"); exit(1); } buffer[n] = '\0'; printf("received %d bytes: <%s>\n", n, buffer); /* * Finish up */ if (close(s) < 0) { perror("close"); exit(1); } exit(0); } /* * ATM API sample server application * * This application will loop forever listening for connections on an ATM * socket. When a new connection arrives, it will send a string in a PDU, * read one PDU from the socket and print its contents. * */ #include #include #include #include #include #include #define MAX_LEN 4096 /* Maximum PDU length */ #define MY_ID 11 /* BLLI Layer 2 protocol */ #define MY_APPL "Server" static char message[] = "A message from the server"; void print_cause(int s) { struct t_atm_cause cause; int optlen; optlen = sizeof(cause); if (getsockopt(s, T_ATM_SIGNALING, T_ATM_CAUSE, &cause, &optlen) < 0) { perror("getsockopt(cause)"); return; } fprintf(stderr, "Cause: coding=%d loc=%d cause=%d diag=(%d,%d,%d,%d)\n", cause.coding_standard, cause.location, cause.cause_value, cause.diagnostics[0], cause.diagnostics[1], cause.diagnostics[2], cause.diagnostics[3]); } main(argc, argv) int argc; char **argv; { struct sockaddr_atm satm; struct t_atm_aal5 aal5; struct t_atm_traffic traffic; struct t_atm_bearer bearer; struct t_atm_qos qos; struct t_atm_net_intf netintf; struct t_atm_app_name appname; char buffer[MAX_LEN+1]; int s, n, optlen; /* * Create socket */ s = socket(AF_ATM, SOCK_SEQPACKET, ATM_PROTO_AAL5); if (s < 0) { perror("socket"); exit(1); } /* * Set up destination SAP */ bzero((caddr_t) &satm, sizeof(satm)); satm.satm_family = AF_ATM; #if (defined(BSD) && (BSD >= 199103)) satm.satm_len = sizeof(satm); #endif /* Destination ATM address */ satm.satm_addr.t_atm_sap_addr.SVE_tag_addr = T_ATM_ANY; satm.satm_addr.t_atm_sap_addr.SVE_tag_selector = T_ATM_ANY; /* BLLI Layer-2 protocol */ satm.satm_addr.t_atm_sap_layer2.SVE_tag = T_ATM_PRESENT; satm.satm_addr.t_atm_sap_layer2.ID_type = T_ATM_USER_ID; satm.satm_addr.t_atm_sap_layer2.ID.user_defined_ID = MY_ID; /* BLLI Layer-3 protocol */ satm.satm_addr.t_atm_sap_layer3.SVE_tag = T_ATM_ABSENT; /* BHLI protocol */ satm.satm_addr.t_atm_sap_appl.SVE_tag = T_ATM_ABSENT; /* * Set up connection parameters */ aal5.forward_max_SDU_size = MAX_LEN; aal5.backward_max_SDU_size = MAX_LEN; aal5.SSCS_type = T_ATM_NULL; optlen = sizeof(aal5); if (setsockopt(s, T_ATM_SIGNALING, T_ATM_AAL5, (caddr_t)&aal5, optlen) < 0) { perror("setsockopt(aal5)"); exit(1); } traffic.forward.PCR_high_priority = T_ATM_ABSENT; traffic.forward.PCR_all_traffic = 100000; traffic.forward.SCR_high_priority = T_ATM_ABSENT; traffic.forward.SCR_all_traffic = T_ATM_ABSENT; traffic.forward.MBS_high_priority = T_ATM_ABSENT; traffic.forward.MBS_all_traffic = T_ATM_ABSENT; traffic.forward.tagging = T_NO; traffic.backward.PCR_high_priority = T_ATM_ABSENT; traffic.backward.PCR_all_traffic = 100000; traffic.backward.SCR_high_priority = T_ATM_ABSENT; traffic.backward.SCR_all_traffic = T_ATM_ABSENT; traffic.backward.MBS_high_priority = T_ATM_ABSENT; traffic.backward.MBS_all_traffic = T_ATM_ABSENT; traffic.backward.tagging = T_NO; traffic.best_effort = T_YES; optlen = sizeof(traffic); if (setsockopt(s, T_ATM_SIGNALING, T_ATM_TRAFFIC, (caddr_t)&traffic, optlen) < 0) { perror("setsockopt(traffic)"); exit(1); } bearer.bearer_class = T_ATM_CLASS_X; bearer.traffic_type = T_ATM_NULL; bearer.timing_requirements = T_ATM_NULL; bearer.clipping_susceptibility = T_NO; bearer.connection_configuration = T_ATM_1_TO_1; optlen = sizeof(bearer); if (setsockopt(s, T_ATM_SIGNALING, T_ATM_BEARER_CAP, (caddr_t)&bearer, optlen) < 0) { perror("setsockopt(bearer)"); exit(1); } qos.coding_standard = T_ATM_NETWORK_CODING; qos.forward.qos_class = T_ATM_QOS_CLASS_0; qos.backward.qos_class = T_ATM_QOS_CLASS_0; optlen = sizeof(qos); if (setsockopt(s, T_ATM_SIGNALING, T_ATM_QOS, (caddr_t)&qos, optlen) < 0) { perror("setsockopt(qos)"); exit(1); } strncpy(appname.app_name, MY_APPL, T_ATM_APP_NAME_LEN); optlen = sizeof(appname); if (setsockopt(s, T_ATM_SIGNALING, T_ATM_APP_NAME, (caddr_t)&appname, optlen) < 0) { perror("setsockopt(app_name)"); exit(1); } /* * Now try to bind/listen */ if (bind(s, (struct sockaddr *) &satm, sizeof(satm)) < 0) { perror("bind"); exit(1); } if (listen(s, 4) < 0) { perror("listen"); exit(1); } for (; ; ) { struct sockaddr_atm claddr; int clsock, cllen; /* Wait for incoming call */ cllen = sizeof(claddr); clsock = accept(s, (struct sockaddr *) &claddr, &cllen); if (clsock < 0) { perror("accept"); exit(1); } printf("Server: new connection\n"); /* * Exchange message with peer */ if (write(clsock, message, sizeof(message)) != sizeof(message)) { perror("write"); exit(1); } if ((n = read(clsock, buffer, MAX_LEN)) < 0) { perror("read"); exit(1); } buffer[n] = '\0'; printf("received %d bytes: <%s>\n", n, buffer); sleep(1); /* * Finish up */ if (close(clsock) < 0) { perror("close"); exit(1); } } close(s); exit(0); } @(#) $FreeBSD: src/share/examples/atm/atm-sockets.txt,v 1.3 1999/08/28 00:19:07 peter Exp $