Merge from vendor branch HEIMDAL:
[dragonfly.git] / share / examples / atm / atm-sockets.txt
1
2         HARP Native ATM Sockets API
3         ===========================
4
5 ATM sockets are an extension to the traditional BSD sockets API to allow
6 direct user-level access to native ATM protocol services.  The ATM sockets
7 extensions are implemented via the addition of a new protocol family (PF_ATM)
8 and a new socket address structure (struct sockaddr_atm).  
9
10 The HARP implementation of native ATM sockets capabilities is intended to be
11 conformant with The Open Group specifications (with known differences listed 
12 below) as defined in the following document:
13
14         The Open Group: Networking Services (XNS) Issue 5 
15                 ISBN 1-85912-165-9
16                 http://www.rdg.opengroup.org/public/pubs/catalog/c523.htm
17
18 And in particular, it is based on the following ATM-specific sections in the
19 above document:
20
21         ATM Transport Protocol Information for Sockets
22         ATM Transport Protocol Information for XTI
23         ATM Transport Headers
24
25 The ATM sockets API is an implementation based on the definitions and
26 descriptions set forth in the following document:
27
28         The ATM Forum: Native ATM Services: Semantic Description, Version 1.0
29                 af-saa-0048.000
30                 http://www.atmforum.com/atmforum/specs/approved.html
31
32
33 Using the HARP Implementation
34 -----------------------------
35 This document only provides the HARP-specific information necessary for using 
36 the ATM sockets API.  Please refer to the XNS document described above for
37 all of the general interface specifications.  There is also sample source
38 code for an ATM sockets application included at the end of this document.
39
40 All user definitions for the HARP ATM sockets implementation are contained
41 in the file /usr/include/netatm/atm.h.  This file must be included in the
42 user's C program source file.  In this file, all HARP extensions to the base 
43 XNS specifications are denoted with a comment string of "XNS_EXT".
44
45
46 HARP Extensions to XNS Issue 5
47 ------------------------------
48 o Socket address structure for ATM addresses
49
50   An ATM socket address structure was not specifically defined by XNS,
51   although the t_atm_sap structure was defined to be used as an ATM protocol
52   address.  Thus, HARP has defined an ATM socket address (using address
53   family AF_ATM) as a 'struct sockaddr_atm', which contains 'struct t_atm_sap'
54   as the protocol address.  This structure (properly cast) must be used on
55   all ATM socket system calls requiring a 'struct sockaddr' parameter.
56
57 o Network Interface Selection socket option (T_ATM_NET_INTF)
58
59   This option is used to specify the name of the network interface to be
60   used to route an outgoing ATM call using a socket connection.  This option
61   is only needed when there are multiple ATM network interfaces defined on a
62   system.  If this option is not set, then the first network interface on
63   the first physical ATM interface defined will be used.
64
65   See the sample application below for an example of the use of this option.
66
67 o LLC Multiplexing socket option (T_ATM_LLC)
68
69   For LLC encapsulated VCCs (BLLI Layer 2 Protocol == T_ATM_BLLI2_I8802),
70   HARP has implemented an LLC multiplexing facility.  In order to use this
71   multiplexing facility, a user must issue a setsockopt() call specifying the 
72   T_ATM_LLC option before the connect() or listen() system call is invoked.
73
74   If using the LLC multiplexor, the user will only receive PDUs which match
75   the LLC header information specified in the socket option.  The kernel 
76   multiplexing software will strip the LLC header from all inbound PDUs and 
77   add the specified LLC header to all outgoing PDUs - the user will never see 
78   the LLC header.  
79
80   For listening sockets, the listener will be notified for all incoming LLC 
81   calls (which also meet the other incoming call distribution selection 
82   criteria), since the LLC header information is only carried in the data 
83   PDUs, not in the signalling protocol.
84
85   The T_ATM_LLC_SHARING flag is used to denote whether this user wishes to
86   share the VCC with other LLC users requesting similar connection attributes 
87   to the same destination.
88
89 o Application Name socket option (T_ATM_APP_NAME)
90
91   This option is used to associate an identifier string (typically, the
92   application's name) with an open ATM socket.  Currently, it is only used 
93   for the "Owner" field in the output of the 'atm show vcc' command.  If this 
94   option is not set, then the "Owner" field will default to "(AAL5)". 
95
96   See the sample application below for an example of the use of this option.
97
98 o PVC support
99
100   The XNS document specifically does not provide support for ATM PVCs.
101   However, due in part to internal HARP requirements (the ILMI daemon), PVC
102   sockets are supported under the HARP implementation. 
103
104   To support PVC sockets, there is a new address format (T_ATM_PVC_ADDR) and
105   address definition (Atm_addr_pvc).   Since there is no actual signalling
106   involved in setting up a PVC, a PVC socket connection only defines the
107   local socket-to-pvc connection - the remainder of the virtual circuit through
108   the ATM network to the remote endpoint must be defined independent of the
109   local socket creation.  PVC socket connections are only allowed via the
110   connect() system call - listen()/accept() sockets cannot be supported.
111   Also, since there are no circuit parameters signalled, most of the 
112   setsockopt() options are silently ignored.
113
114 o SPANS support
115
116   HARP has added ATM socket support for the FORE-proprietary SPANS address 
117   format (T_ATM_SPANS_ADDR).  A SPANS socket can only be established over 
118   an ATM physical interface which is using the SPANS signalling manager.
119   There is limited ATM socket option support - the socket options can be set, 
120   but most are silently ignored, since they are not applicable to the SPANS 
121   protocols.  The SPANS socket address support has not been thoroughly tested.
122
123 o Miscellaneous user convenience typedefs, macros and defines
124
125
126 XNS Issue 5 Features Not Supported in HARP
127 ------------------------------------------
128 o ATM_PROTO_SSCOP
129
130   The socket protocol for reliable data transport (ATM_PROTO_SSCOP) is not
131   supported in this HARP release.  There is some initial skeleton code for
132   SSCOP support, but it was not completed.
133
134 o Multipoint connections
135
136   The core HARP code does not provide support for multipoint connections, so,
137   obviously, multipoint socket connections are also not supported.  
138
139   The non-supported socket options are:
140         o T_ATM_ADD_LEAF
141         o T_ATM_DROP_LEAF
142         o T_ATM_LEAF_IND
143
144   The non-supported socket option values are:
145         o For the T_ATM_BEARER_CAP socket option:
146                 o connection_configuration == T_ATM_1_TO_MANY
147
148
149 Example ATM Socket Application
150 ------------------------------
151 The following are simple example client and server applications using the ATM 
152 socket API.
153
154 /*
155  * ATM API sample client application
156  *
157  * This application will open an ATM socket to a server, send a text string 
158  * in a PDU and then read one PDU from the socket and print its contents.
159  *
160  */
161 #include <stdio.h>
162 #include <sys/param.h>
163 #include <sys/types.h>
164 #include <sys/socket.h>
165 #include <net/if.h>
166 #include <netatm/atm.h>
167
168 #define MAX_LEN         4096    /* Maximum PDU length */
169 #define MY_ID           11      /* BLLI Layer 2 protocol */
170 #define MY_APPL         "Client"
171
172 Atm_addr_nsap   dst_addr = {
173         0x47,
174 #error FIX ME: Replace the 2 lines below with your nsap prefix and esi address
175         {0x00,0x05,0x80,0xff,0xdc,0x00,0x00,0x00,0x00,0x02,0xff,0xff},
176         {0x11,0x22,0x33,0x44,0x55,0x66},
177         0x00
178 };
179
180 static char     message[] = "A message from the client";
181
182 void
183 print_cause(int s)
184 {
185         struct  t_atm_cause     cause;
186         int     optlen;
187
188         optlen = sizeof(cause);
189         if (getsockopt(s, T_ATM_SIGNALING, T_ATM_CAUSE, &cause, &optlen) < 0) {
190                 perror("getsockopt(cause)");
191                 return;
192         }
193         
194         fprintf(stderr, "Cause: coding=%d loc=%d cause=%d diag=(%d,%d,%d,%d)\n",
195                 cause.coding_standard, cause.location, cause.cause_value,
196                 cause.diagnostics[0], cause.diagnostics[1], 
197                 cause.diagnostics[2], cause.diagnostics[3]);
198 }
199
200 main(argc, argv)
201         int     argc;
202         char    **argv;
203 {
204         struct sockaddr_atm     satm;
205         struct t_atm_aal5       aal5;
206         struct t_atm_traffic    traffic;
207         struct t_atm_bearer     bearer;
208         struct t_atm_qos        qos;
209         struct t_atm_net_intf   netintf;
210         struct t_atm_app_name   appname;
211         char    buffer[MAX_LEN+1];
212         int     s, n, optlen;
213
214         /*
215          * Create socket
216          */
217         s = socket(AF_ATM, SOCK_SEQPACKET, ATM_PROTO_AAL5);
218         if (s < 0) {
219                 perror("socket");
220                 exit(1);
221         }
222
223         /*
224          * Set up destination SAP
225          */
226         bzero((caddr_t) &satm, sizeof(satm));
227         satm.satm_family = AF_ATM;
228 #if (defined(BSD) && (BSD >= 199103))
229         satm.satm_len = sizeof(satm);
230 #endif
231         /* Destination ATM address */
232         satm.satm_addr.t_atm_sap_addr.SVE_tag_addr = T_ATM_PRESENT;
233         satm.satm_addr.t_atm_sap_addr.SVE_tag_selector = T_ATM_PRESENT;
234         satm.satm_addr.t_atm_sap_addr.address_format = T_ATM_ENDSYS_ADDR;
235         satm.satm_addr.t_atm_sap_addr.address_length = sizeof(Atm_addr_nsap);
236         bcopy((caddr_t)&dst_addr,
237                 (caddr_t)satm.satm_addr.t_atm_sap_addr.address,
238                 sizeof(dst_addr));
239
240         /* BLLI Layer-2 protocol */
241         satm.satm_addr.t_atm_sap_layer2.SVE_tag = T_ATM_PRESENT;
242         satm.satm_addr.t_atm_sap_layer2.ID_type = T_ATM_USER_ID; 
243         satm.satm_addr.t_atm_sap_layer2.ID.user_defined_ID = MY_ID; 
244
245         /* BLLI Layer-3 protocol */
246         satm.satm_addr.t_atm_sap_layer3.SVE_tag = T_ATM_ABSENT;
247
248         /* BHLI protocol */
249         satm.satm_addr.t_atm_sap_appl.SVE_tag = T_ATM_ABSENT;
250
251         /*
252          * Set up connection parameters
253          */
254         aal5.forward_max_SDU_size = MAX_LEN;
255         aal5.backward_max_SDU_size = MAX_LEN;
256         aal5.SSCS_type = T_ATM_NULL;
257         optlen = sizeof(aal5);
258         if (setsockopt(s, T_ATM_SIGNALING, T_ATM_AAL5, (caddr_t)&aal5,
259                         optlen) < 0) {
260                 perror("setsockopt(aal5)");
261                 exit(1);
262         }
263
264         traffic.forward.PCR_high_priority = T_ATM_ABSENT;
265         traffic.forward.PCR_all_traffic = 100000;
266         traffic.forward.SCR_high_priority = T_ATM_ABSENT;
267         traffic.forward.SCR_all_traffic = T_ATM_ABSENT;
268         traffic.forward.MBS_high_priority = T_ATM_ABSENT;
269         traffic.forward.MBS_all_traffic = T_ATM_ABSENT;
270         traffic.forward.tagging = T_NO;
271         traffic.backward.PCR_high_priority = T_ATM_ABSENT;
272         traffic.backward.PCR_all_traffic = 100000;
273         traffic.backward.SCR_high_priority = T_ATM_ABSENT;
274         traffic.backward.SCR_all_traffic = T_ATM_ABSENT;
275         traffic.backward.MBS_high_priority = T_ATM_ABSENT;
276         traffic.backward.MBS_all_traffic = T_ATM_ABSENT;
277         traffic.backward.tagging = T_NO;
278         traffic.best_effort = T_YES;
279         optlen = sizeof(traffic);
280         if (setsockopt(s, T_ATM_SIGNALING, T_ATM_TRAFFIC, (caddr_t)&traffic,
281                         optlen) < 0) {
282                 perror("setsockopt(traffic)");
283                 exit(1);
284         }
285
286         bearer.bearer_class = T_ATM_CLASS_X;
287         bearer.traffic_type = T_ATM_NULL;
288         bearer.timing_requirements = T_ATM_NULL;
289         bearer.clipping_susceptibility = T_NO;
290         bearer.connection_configuration = T_ATM_1_TO_1;
291         optlen = sizeof(bearer);
292         if (setsockopt(s, T_ATM_SIGNALING, T_ATM_BEARER_CAP, (caddr_t)&bearer,
293                         optlen) < 0) {
294                 perror("setsockopt(bearer)");
295                 exit(1);
296         }
297
298         qos.coding_standard = T_ATM_NETWORK_CODING;
299         qos.forward.qos_class = T_ATM_QOS_CLASS_0;
300         qos.backward.qos_class = T_ATM_QOS_CLASS_0;
301         optlen = sizeof(qos);
302         if (setsockopt(s, T_ATM_SIGNALING, T_ATM_QOS, (caddr_t)&qos,
303                         optlen) < 0) {
304                 perror("setsockopt(qos)");
305                 exit(1);
306         }
307
308 #ifdef REMOVE_TO_USE_NET_INTF
309 #error FIX ME: Replace the ni0 below with the local atm network interface name
310         strncpy(netintf.net_intf, "ni0", IFNAMSIZ);
311         optlen = sizeof(netintf);
312         if (setsockopt(s, T_ATM_SIGNALING, T_ATM_NET_INTF, (caddr_t)&netintf,
313                         optlen) < 0) {
314                 perror("setsockopt(net_intf)");
315                 exit(1);
316         }
317 #endif
318
319         strncpy(appname.app_name, MY_APPL, T_ATM_APP_NAME_LEN);
320         optlen = sizeof(appname);
321         if (setsockopt(s, T_ATM_SIGNALING, T_ATM_APP_NAME, (caddr_t)&appname,
322                         optlen) < 0) {
323                 perror("setsockopt(app_name)");
324                 exit(1);
325         }
326
327         /*
328          * Now try to connect to destination
329          */
330         if (connect(s, (struct sockaddr *) &satm, sizeof(satm)) < 0) {
331                 perror("connect");
332                 print_cause(s);
333                 exit(1);
334         }
335
336         /*
337          * Exchange message with peer
338          */
339         if (write(s, message, sizeof(message)) != sizeof(message)) {
340                 perror("write");
341                 exit(1);
342         }
343
344         if ((n = read(s, buffer, MAX_LEN)) < 0) {
345                 perror("read");
346                 exit(1);
347         }
348
349         buffer[n] = '\0';
350         printf("received %d bytes: <%s>\n", n, buffer);
351
352         /*
353          * Finish up
354          */
355         if (close(s) < 0) {
356                 perror("close");
357                 exit(1);
358         }
359
360         exit(0);
361 }
362
363
364
365 /*
366  * ATM API sample server application
367  *
368  * This application will loop forever listening for connections on an ATM 
369  * socket.  When a new connection arrives, it will send a string in a PDU,
370  * read one PDU from the socket and print its contents.
371  *
372  */
373 #include <stdio.h>
374 #include <sys/param.h>
375 #include <sys/types.h>
376 #include <sys/socket.h>
377 #include <net/if.h>
378 #include <netatm/atm.h>
379
380 #define MAX_LEN         4096    /* Maximum PDU length */
381 #define MY_ID           11      /* BLLI Layer 2 protocol */
382 #define MY_APPL         "Server"
383
384 static char     message[] = "A message from the server";
385
386 void
387 print_cause(int s)
388 {
389         struct  t_atm_cause     cause;
390         int     optlen;
391
392         optlen = sizeof(cause);
393         if (getsockopt(s, T_ATM_SIGNALING, T_ATM_CAUSE, &cause, &optlen) < 0) {
394                 perror("getsockopt(cause)");
395                 return;
396         }
397         
398         fprintf(stderr, "Cause: coding=%d loc=%d cause=%d diag=(%d,%d,%d,%d)\n",
399                 cause.coding_standard, cause.location, cause.cause_value,
400                 cause.diagnostics[0], cause.diagnostics[1], 
401                 cause.diagnostics[2], cause.diagnostics[3]);
402 }
403
404 main(argc, argv)
405         int     argc;
406         char    **argv;
407 {
408         struct sockaddr_atm     satm;
409         struct t_atm_aal5       aal5;
410         struct t_atm_traffic    traffic;
411         struct t_atm_bearer     bearer;
412         struct t_atm_qos        qos;
413         struct t_atm_net_intf   netintf;
414         struct t_atm_app_name   appname;
415         char    buffer[MAX_LEN+1];
416         int     s, n, optlen;
417
418         /*
419          * Create socket
420          */
421         s = socket(AF_ATM, SOCK_SEQPACKET, ATM_PROTO_AAL5);
422         if (s < 0) {
423                 perror("socket");
424                 exit(1);
425         }
426
427         /*
428          * Set up destination SAP
429          */
430         bzero((caddr_t) &satm, sizeof(satm));
431         satm.satm_family = AF_ATM;
432 #if (defined(BSD) && (BSD >= 199103))
433         satm.satm_len = sizeof(satm);
434 #endif
435         /* Destination ATM address */
436         satm.satm_addr.t_atm_sap_addr.SVE_tag_addr = T_ATM_ANY;
437         satm.satm_addr.t_atm_sap_addr.SVE_tag_selector = T_ATM_ANY;
438
439         /* BLLI Layer-2 protocol */
440         satm.satm_addr.t_atm_sap_layer2.SVE_tag = T_ATM_PRESENT;
441         satm.satm_addr.t_atm_sap_layer2.ID_type = T_ATM_USER_ID; 
442         satm.satm_addr.t_atm_sap_layer2.ID.user_defined_ID = MY_ID; 
443
444         /* BLLI Layer-3 protocol */
445         satm.satm_addr.t_atm_sap_layer3.SVE_tag = T_ATM_ABSENT;
446
447         /* BHLI protocol */
448         satm.satm_addr.t_atm_sap_appl.SVE_tag = T_ATM_ABSENT;
449
450         /*
451          * Set up connection parameters
452          */
453         aal5.forward_max_SDU_size = MAX_LEN;
454         aal5.backward_max_SDU_size = MAX_LEN;
455         aal5.SSCS_type = T_ATM_NULL;
456         optlen = sizeof(aal5);
457         if (setsockopt(s, T_ATM_SIGNALING, T_ATM_AAL5, (caddr_t)&aal5,
458                         optlen) < 0) {
459                 perror("setsockopt(aal5)");
460                 exit(1);
461         }
462
463         traffic.forward.PCR_high_priority = T_ATM_ABSENT;
464         traffic.forward.PCR_all_traffic = 100000;
465         traffic.forward.SCR_high_priority = T_ATM_ABSENT;
466         traffic.forward.SCR_all_traffic = T_ATM_ABSENT;
467         traffic.forward.MBS_high_priority = T_ATM_ABSENT;
468         traffic.forward.MBS_all_traffic = T_ATM_ABSENT;
469         traffic.forward.tagging = T_NO;
470         traffic.backward.PCR_high_priority = T_ATM_ABSENT;
471         traffic.backward.PCR_all_traffic = 100000;
472         traffic.backward.SCR_high_priority = T_ATM_ABSENT;
473         traffic.backward.SCR_all_traffic = T_ATM_ABSENT;
474         traffic.backward.MBS_high_priority = T_ATM_ABSENT;
475         traffic.backward.MBS_all_traffic = T_ATM_ABSENT;
476         traffic.backward.tagging = T_NO;
477         traffic.best_effort = T_YES;
478         optlen = sizeof(traffic);
479         if (setsockopt(s, T_ATM_SIGNALING, T_ATM_TRAFFIC, (caddr_t)&traffic,
480                         optlen) < 0) {
481                 perror("setsockopt(traffic)");
482                 exit(1);
483         }
484
485         bearer.bearer_class = T_ATM_CLASS_X;
486         bearer.traffic_type = T_ATM_NULL;
487         bearer.timing_requirements = T_ATM_NULL;
488         bearer.clipping_susceptibility = T_NO;
489         bearer.connection_configuration = T_ATM_1_TO_1;
490         optlen = sizeof(bearer);
491         if (setsockopt(s, T_ATM_SIGNALING, T_ATM_BEARER_CAP, (caddr_t)&bearer,
492                         optlen) < 0) {
493                 perror("setsockopt(bearer)");
494                 exit(1);
495         }
496
497         qos.coding_standard = T_ATM_NETWORK_CODING;
498         qos.forward.qos_class = T_ATM_QOS_CLASS_0;
499         qos.backward.qos_class = T_ATM_QOS_CLASS_0;
500         optlen = sizeof(qos);
501         if (setsockopt(s, T_ATM_SIGNALING, T_ATM_QOS, (caddr_t)&qos,
502                         optlen) < 0) {
503                 perror("setsockopt(qos)");
504                 exit(1);
505         }
506
507         strncpy(appname.app_name, MY_APPL, T_ATM_APP_NAME_LEN);
508         optlen = sizeof(appname);
509         if (setsockopt(s, T_ATM_SIGNALING, T_ATM_APP_NAME, (caddr_t)&appname,
510                         optlen) < 0) {
511                 perror("setsockopt(app_name)");
512                 exit(1);
513         }
514
515         /*
516          * Now try to bind/listen
517          */
518         if (bind(s, (struct sockaddr *) &satm, sizeof(satm)) < 0) {
519                 perror("bind");
520                 exit(1);
521         }
522         if (listen(s, 4) < 0) {
523                 perror("listen");
524                 exit(1);
525         }
526
527         for (; ; ) {
528                 struct sockaddr_atm     claddr;
529                 int     clsock, cllen;
530
531                 /* Wait for incoming call */
532                 cllen = sizeof(claddr);
533                 clsock = accept(s, (struct sockaddr *) &claddr, &cllen);
534                 if (clsock < 0) {
535                         perror("accept");
536                         exit(1);
537                 }
538                 printf("Server: new connection\n");
539                 
540                 /*
541                  * Exchange message with peer
542                  */
543                 if (write(clsock, message, sizeof(message)) != sizeof(message)) {
544                         perror("write");
545                         exit(1);
546                 }
547
548                 if ((n = read(clsock, buffer, MAX_LEN)) < 0) {
549                         perror("read");
550                         exit(1);
551                 }
552
553                 buffer[n] = '\0';
554                 printf("received %d bytes: <%s>\n", n, buffer);
555
556                 sleep(1);
557
558                 /*
559                  * Finish up
560                  */
561                 if (close(clsock) < 0) {
562                         perror("close");
563                         exit(1);
564                 }
565         }
566
567         close(s);
568         exit(0);
569 }
570
571         @(#) $FreeBSD: src/share/examples/atm/atm-sockets.txt,v 1.3 1999/08/28 00:19:07 peter Exp $
572