ChangeLogTag: Thu Apr 24 13:55:00 UTC 2003 Gautam Thaker <gthaker@atl.lmco.com>

4 files changed, 402 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index fc8583ee528..c50305d61aa 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+Thu Apr 24 13:55:00 UTC 2003  Gautam Thaker  <gthaker@atl.lmco.com>
+
+        * README.SCTP 
+          Edited for content. This file provides SCTP network level 
+          information.
+        * README.OpenSS7
+          Added. This file provides OpenSS7 implementation
+          specific information.
+        * README.SCIOP
+          Added. This file provides TAO SCIOP level related 
+          README information. Ideally it might be put some place
+          under TAO/ but it is kept here with other SCTP related
+          README files.
+
 Thu Apr 24 08:14:42 2003  Chad Elliott  <elliott_c@ociweb.com>
 
         * bin/MakeProjectCreator/modules/Parser.pm:
diff --git a/performance-tests/SCTP/README.OpenSS7 b/performance-tests/SCTP/README.OpenSS7
new file mode 100644
index 00000000000..33b7f124a5f
--- /dev/null
+++ b/performance-tests/SCTP/README.OpenSS7
@@ -0,0 +1,253 @@
+// $Id$
+
+This document describes the OpenSS7 API in detail.
+
+Introduction
+=============
+ 
+OpenSS7 defines two types of services, UDP style and TCP style.  How OpenSS7 
+distinguishes the two styles is by the way in which the data is presented to 
+the application.  In OpenSS7, data is presented as byte streams or datagrams.  
+The stream style is considered the TCP style socket, and the datagram is 
+considered the UDP style socket.  The UDP style socket does not represent a one
+to many mapping of file descriptors to associations as the IETF compatible 
+sockets does.
+
+Instead of adding new system calls, OpenSS7 decided to modify some of the
+existing system calls to play nicely with multi-homing.  So, to bind to 
+multiple addresses, you pass in an array of struct sockaddr* structures and the
+total length in bytes of the array.  Also, when accepting connections from a
+peer, you would pass in a pointer to an array of struct sockaddr* and the 
+length of the array in bytes.
+
+Common Calls
+============
+
+There are a few common calls which have the same semantics no matter which
+interface you are using (UDP style or TCP style).  So, the usual calls used in 
+a client are:
+
+  1) socket()
+  2) bind()
+  3) setsockopt()
+  4) connect()
+  5) send/recv()
+  6) close()
+
+while the usual calls for a server are as follows:
+
+  1) socket()
+  2) bind()
+  3) setsockopt()
+  4) listen()
+  5) accept()
+  6) close()
+
+The previous example mimics the way in which the TCP protocol is used.  
+There are some exceptions to the above sequence which we will get into a little
+later. So, let's talk about the system calls above.
+
+Socket()
+--------
+The socket() call creates a file descriptor for the application to use to
+communicate with the SCTP stack.  The signature of socket() is as follows:
+
+  int socket(int network, int service, int proto)
+  Where:
+    network - AF_INET or AF_INET6 (AF_INET6 is not currently supported)
+    service - SOCK_SEQPACKET which gives us the UDP style interface
+              SOCK_STREAM which gives us the TCP style interface
+    proto   - IPPROTO_SCTP which is the SCTP protocol number(132)
+
+Bind()
+------
+The bind() call is used to attach the socket descriptor to the given array of
+addresses.  bind() may only be called once.  The address structures sent in as
+arguments to bind must have the same port number.  That is, you may have
+multiple addresses, but only 1 port number.  The signature of bind() is as
+follows:
+
+  int bind(int fd, struct sockaddr* addrs, socklen_t addrs_len)
+  Where:
+    fd        - A SCTP socket descriptor
+    addrs     - An array of struct sockaddr* which have the same port number
+    addrs_len - The total length in bytes of the addrs array
+
+If an address structure is sent in with the address of INADDR_ANY, then SCTP
+will bind to all the addresses on the host and either pick an ephemeral port or
+use the one specified in the address structure.
+
+Setsockopt()
+------------
+The setsockopt() call is used to adjust many different parameters to the SCTP
+protocol.  Please see the sctp(7) man page for more details.
+
+Connect()
+---------
+The connect() call can be used to initialize a connection with a peer SCTP
+machine.  A connection can be initialized in 2 ways.  The first is this
+call(connect()).  The second way is to allow implicit initialization when the
+application calls sendmsg or sendto with the address of the remote host
+specified.  To allow data to be piggybacked with the COOKIE_ECHO chunk, you 
+must use the second initialization technique.  The signature of connect is as
+follows:
+
+  int connect(int fd, struct sockaddr* r_addr, socklen_t r_addr_len)
+  Where:
+    fd         - An SCTP socket descriptor
+    r_addr     - A single address structure with the address of the remote host
+    r_addr_len - Length in bytes of the the address structure
+
+Note that only one address is sent into the connect call.  The SCTP protocol
+will negotiate the valid IP addresses to use with multi-homing.
+
+Listen()
+--------
+The listen() call prepares the SCTP socket to accept new associations.  The
+signature is as follows:
+
+  int listen(int fd, int backlog)
+  Where:
+    fd    - An SCTP socket descriptor
+    backlog - The maximum number of unaccepted connections
+
+Accept()
+--------
+The accept() call allows the application to explicitly accept an incoming
+association initialization attempt.  accept() returns a new file descriptor
+which can be used to send data to the client.  accept() has a slightly 
+different semantic which allows it to take an array of address structures.  
+This gives the application the chance to get a specified number of addresses 
+from the peer on initialization.  The signature of accept() is as follows:
+
+  int accept(int fd, struct sockaddr* r_addr, socklen_t *r_addr_len)
+  Where:
+    fd         - A SCTP socket descriptor
+    r_addr     - An array of address structures which will be filled with the
+                 addresses of the remote host
+    r_addr_len - The length of the array of address structures passed in.
+
+accept() will only put as many addresses in the address array as is specified
+by the r_addr_len argument.
+
+Close()
+-------
+Start the association shutdown sequence.  The signature is as follows:
+
+  int close(int fd)
+  Where:
+    fd - A SCTP socket descriptor
+
+Data Interfaces
+===============
+This section describes the sending and receiving of data on an SCTP socket.
+This is where the differences between the TCP style and UDP style sockets 
+shows.  SCTP uses the standard pairs of calls:
+
+  1) send()/recv()
+  2) sendmsg()/recvmsg()
+  3) sendto()/readfrom()
+  4) write()/read()
+  5) writev()/readv()
+
+When the SCTP socket is opened as a UDP style socket, data is presented to the
+application as datagrams.  This means that calls to the receive class of system
+calls returns only datagrams.  For example, assume a sender sends 2 100 byte
+datagrams.  Now assume that the receiver calls one of the receive routines with
+a max buffer size of 120 bytes.  Assuming no errors are encountered, only 100
+bytes are returned to the receiver (only 1 datagram), leaving the last 20 bytes
+empty in the receivers buffer.  When the last of a datagram is read, the 
+MSG_EOR flag is returned, and if the datagram is too big to fit into the 
+specified buffer, the MSG_TRUNC flag is returned.  
+
+With TCP styles sockets, the data is presented to the application as a stream
+of bytes (like TCP).  For example, assume the sender sends 2 100 byte 
+datagrams.  Now assume that the receiver calls one of the receive routines with 
+a max buffer size of 120.  Assuming no errors are encountered, 120 bytes are 
+returned (100 from the first datagram and 20 from the next datagram), leaving 
+80 bytes in the second datagram.  MSG_EOR and MSG_TRUNC are never returned.
+
+Send()/Recv()
+-------------
+The send/recv interface is one of the easiest ways of sending data back and
+forth between peers.  When send/recv is called, data is sent/read from the
+default stream.  The signature of send/recv is as follows:
+
+  int send(int fd, void *data, size_t d_len, int flags)
+  Where:
+    fd    - A SCTP socket descriptor
+    data  - Data to be sent to the peer
+    d_len - The length of the data in bytes
+    flags - Possible flags to be sent to be passed to the SCTP stack
+            (see send(3))
+
+Sendmsg()/Recvmsg()
+-------------------
+The sendmsg/recvmsg interface is the most powerful and hard to use interface
+in the SCTP stack.  This interface allows the specification of which stream to
+send data out or receive data from.  It also allows the sending of data with a
+specified protocol payload identifier.  The signature is as follows:
+
+  int sendmsg(int fd, struct msghdr *msg, int flags)
+  Where:
+    fd    - A SCTP socket descriptor
+    msg   - A struct msghdr structure which holds miscellaneous information
+    flags - Possible flags to be passed to the SCTP stack
+            (see sendmsg(3))
+
+The msg argument holds the data to be sent to the peer.  It also can take an
+address to send the data to.  So, for example, if you had an association with 2
+addresses for the peer and the default path used the first address, and you
+wanted to send data to the other address, you could specify that address in the
+msg structure.  If this address field is NULL, then data is sent out the       
+default address.  
+
+This interface also allows other functions by using the ancillary data field 
+in the msg structure.  By using the ancillary data field, you may send data out
+a different stream by using the SCTP_SID control message.  This type of control
+message would take an integer representing the stream to send data out as it's
+data.  Another option is to use the SCTP_PPI control message which allows the
+setting of the protocol payload identifier to the specified integer argument.
+Both of these options only set their values for the current data being sent out.
+
+Sendto()/Recvfrom()
+-------------------
+The sendto/recvfrom interface allows the specification of which remote address
+to send data.  The signature of sendto/recvfrom is as follows:
+
+  int sendto(int fd, void *data, size_t d_len, int flags, 
+             struct sockaddr* r_addr, socklen_t r_addr_len)
+  Where:
+    fd         - A SCTP socket descriptor
+    data       - Data to send to peer
+    d_len      - Length of the data to be sent
+    flags      - Possible flags to be passed to the SCTP stack
+    r_addr     - Address of peer to send data to
+    r_addr_len - Length of peer address
+
+Write()/Read()
+--------------
+This interface is the simplest way of sending data to a peer.  When this
+interface is used, data is sent/received through the default stream (as set by
+SCTP_SID).  The signature is as follows:
+
+  int write(int fd, void *data, size_t d_len)
+  Where:
+    fd    - A SCTP socket descriptor
+    data  - Data to be sent to peer
+    d_len - Length of data
+
+Writev()/Readv()
+----------------
+This interface allows the sending of multiple buffers of data in one system
+call.  This call places all the buffers into one SCTP data chunk.  The          signature is as follows:
+
+  int writev(int fd, struct iovec *iov, int ct)
+  Where:
+    fd  - A SCTP socket descriptor
+    iov - An array of iovec structures.  The order they are in the array is the
+          order they are placed in the data chunk
+    ct  - The number of iovec structures to send
+
+--
+
diff --git a/performance-tests/SCTP/README.SCIOP b/performance-tests/SCTP/README.SCIOP
new file mode 100644
index 00000000000..503b81f7eaf
--- /dev/null
+++ b/performance-tests/SCTP/README.SCIOP
@@ -0,0 +1,63 @@
+README.SCIOP
+------------
+
+Author: Jason Cohen
+Lockheed Martin, Advanced Technology Labs
+
+
+The SCIOP pluggable protocol for TAO uses the SCTP transport protocol through
+the use of the SOCK_SEQPACK ACE wrappers for sequence based transport.  The
+current implementation supported is the OpenSS7 SCTP protocol layer, tested
+under Linux 2.4.18.
+
+For more information on SOCK_SEQPACK and OpenSS7 SCTP see
+ACE_wrappers/performance-tests/SCTP/README*
+
+Features Currently Supported:
+-----------------------------
+
+o) Sequenced delivery via SOCK_SEQPACK
+Currently, only one stream is supported as there are no available bindings to
+provide a user with stream designation for messages.
+
+o) SCIOR compliance to OMG GIOP SCTP Protocol Mapping submission mars/2002-09-01.  
+
+o) Multiple address SCIOR profiles
+When multiple addresses are included in a SCIOR profile, each address is
+handled separately during the connection process.  Specifying multiple
+addresses for a single connection attempt remains as work to be done.
+However, multiple path discovery during connection time in OpenSS7's
+SCTP implementation has been tested to work properly with SCIOP.
+
+The catior utility under ACE_wrappers/TAO/utils/catior has also modified
+to display SCIOR profile information.
+
+To test SCIOP after installing an SCTP implementation supported by
+SOCK_SEQPACK, try using a performance test specifying an sciop address as the
+ORBEndpoint.  One way to do this is with the test found under:
+ACE_wrappers/TAO/performance-tests/Pluggable/
+
+Make sure to build the pluggable protocols into the executable:
+gmake LIBS+=-lTAO_Strategies
+
+Run the server with an sciop endpoint specified:
+./server -ORBEndpoint sciop://${HOSTNAME} -o test.ior &
+
+Finally, run the client on the same machine or another that has file
+access to your IOR file:
+./client -f test.ior
+
+TO-DO:
+------
+
+o) Multiple association connection using Multihomed_INET_Addr
+Currently, only one address connection is attempted at a time, even when a
+profile contains multiple address.  Later, we hope to allow this
+implementation of SCIOP to exploit the multiple address connection
+capabilities of STCP.
+
+o) SCTP ProtocolManagement/SCTPProtocolProperties
+
+o) Support for max_streams > 1
+
+o) SCIOR Profile Components
diff --git a/performance-tests/SCTP/README.SCTP b/performance-tests/SCTP/README.SCTP
index e69de29bb2d..d4bb163c8dc 100644
--- a/performance-tests/SCTP/README.SCTP
+++ b/performance-tests/SCTP/README.SCTP
@@ -0,0 +1,72 @@
+#	$Id$	
+
+This document provides general information about the SCTP protocol.  
+
+
+Introduction
+=============
+SCTP (Stream Control Transmission Protocol) is a new transport layer protocol 
+developed by the IETF and defined by RFC2960.  Originally designed for the 
+transmission of message-oriented applications such as the transportation of 
+signaling data for PSTNs (Public Switched Telephone Networks), SCTP can be used
+in any application that uses TCP.  
+
+	Major Features
+	--------------
+
+	- Direct support for multi-homing
+	- Support for multiple streams per connection (known as associations) 
+	  to reduce "head of line" blocking problems.   
+    	- Four way handshake reducing the possibility for blind denial of
+      	  service attacks.
+    	- Adjustment of congestion control parameters
+    	- Cookie mechanism to protect against "SYN" attacks
+
+API's
+========
+
+The SCTP drafts have defined several different API's.  The first reference 
+implementation was a user level library.  This allowed an application to use 
+SCTP through several functions and callbacks.  As of this writing a 
+transition from the user level libraries to the kernel is underway.
+
+The IETF TSVWG (Transport Area Working Group) has published a draft 
+(draft-ietf-tsvwg-sctpsocket-06.txt) that defines a mapping between SCTP and 
+the BSD sockets interface.  This interface has made porting TCP applications to
+SCTP as simple as changing one socket call.
+
+	OpenSS7
+	--------
+	OpenSS7 has defined, a similar BSD style sockets interface.  It is 
+	slightly different from the one defined by the IETF, however, at the
+ 	time of our evaluation it was the most stable implementation.  
+
+	Please see README.OpenSS7 for more details.   
+
+
+Resources
+===========
+
+	RFCs
+	-----
+	RFC2960: Stream Control Transmission Protocol
+	RFC3309: Stream Control Transmission Protocol Checksum Change
+
+	Internet-Drafts
+	----------------
+	
+	draft-ietf-tsvwg-sctpsocket-06.txt: 
+		Sockets API Extensions for Stream Control Transmission Protocol
+
+	draft-ietf-tsvwg-sctpimpguide-08.txt
+		Stream Control Transmission Protocol Implementer's Guide
+
+	Internet Links
+	---------------
+	IETF: Transport Area Working Group (tsvwg):
+		http://www.ietf.org/html.charters/tsvwg-charter.html
+
+	The OpenSS7 Project: http://www.openss7.org/sctp.html
+
+--
+