freebsd-dev/share/examples/atm/atm-sockets.txt

	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 is a simple example application using the ATM socket API.

/*
 * ATM API sample application
 *
 * This application will open an ATM socket, send a text string in a PDU
 * and then read one PDU from the socket and print its contents.
 *
 */
#include <sys/param.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <net/if.h>
#include <netatm/atm.h>

#define	MAX_LEN		4096	/* Maximum PDU length */
#define	MY_ID		11	/* BLLI Layer 2 protocol */
#define MY_APPL		"SAMPLE"

Atm_addr_nsap	dst_addr = {
	0x47,
	{0x00,0x05,0x80,0xff,0xdc,0x00,0x00,0x00,0x00,0x02,0xff,0xff},
	{0x11,0x22,0x33,0x44,0x55,0x66},
	0x00
};

static char	message[] = "Test message to send on connection";


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);
	}

	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);
	}

	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");
		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);
}

	@(#) $Id: atm_sockets,v 1.1 1998/08/26 21:52:01 mks Exp $