Release 1.1 - June 2003

Overview of SCTP sockets
------------------------

In order to support multiple implementations of SCTP, we had to standardize 
on a set of semantics.  

The IETF sockets draft states that service type SOCK_SEQPACKET indicates a UDP
style socket (i.e. connection-less), while service type SOCK_STREAM indicates
a TCP style socket.  However, this conflicts with the POSIX definition for 
SOCK_SEQPACKET as connection-oriented. 

In ACE we choose to support the standard POSIX definition. In doing so, certain 
socket semantics will be guaranteed regardless of implementation.   
 
	[1] SOCK_SEQPACKET sockets will always be message-based, 
            connection-oriented, and reliable.

	[2] SOCK_STREAM sockets will be message-based or byte-stream based,
            connection-oriented, and reliable.  
	

SCTP Features Accessible Within ACE
-----------------------------------

 * SOCK_STREAM (byte stream oriented or msg oriented) data transport service

 * SOCK_SEQPACKET (message oriented) data transport service (this is
   the service used by TAO's SCIOP pluggable protocol)

 * Explicit control of binding network interfaces (all, one, or any
   subset) to server-side passive- and active- mode sockets on
   multi-homed machines. (for SOCK_SEQPACKET service only.  The
   SOCK_STREAM service may only bind one or all interfaces because we
   avoided changing the interface of ACE_SOCK_Acceptor.)

 * Setting and getting of all parameters exposed by SCTP 
   (e.g. retransmission timeout (RTO)) via ACE_SOCK::set_option(...)
   and ACE_SOCK::get_option(...) for both SOCK_STREAM and
   SOCK_SEQPACKET sockets.  You must set the socket level appropriately.  

 * Multiplexing of lightweight "SCTP Streams" (over the SOCK_STREAM
   and SOCK_SEQPACKET services) via ACE_SOCK::set_option(...)

 * Network path multiplexing (provided opaquely by the protocol---no
   explicit support required in ACE other than the ability to
   configure various parameters and the set of interfaces as described
   above)


Supported SCTP Implementations
------------------------------

 * OpenSS7's Linux Implementation (Berkeley UNIX Network API) 
   Linux 2.4.18 patch available at: http://www.openss7.org/linux-sctp-0.2.14.tgz
   (as of April 2003)

 * The LKSCTP Linux Kernel Implementation (IETF Sockets Draft API compliant)
   Available in the Linux 2.5 kernels (http://www.kernel.org/)
   Tools/Libs available at http://lksctp.sourceforge.net/
     (All socket interfaces are message-based -- please see README.LKSCTP)


BUGS
----

 * OpenSS7 BUGS 

    - protocol crashes when transmitting message sizes greater than
      PATH MTU in the presence of network failures (message size
      includes SCTP and IP headers and data.)

 * LKSCTP BUGS

    - certain combinations of SCTP parameters will cause a kernel panic
      (ie. setting rto_initial, rto_max, or rto_min to 0)


TO-DO
----

 * Provide explicit control of binding network interfaces to
   client-side active-mode sockets on multi-homed machines. Current
   implementation supports all interfaces but not restriction to one
   or to an arbitrary subset. (This will be done for SOCK_SEQPACKET
   service only. We want to avoid changing the existing interfaces for
   the SOCK_STREAM service).

 * Integrate management and use of "SCTP Streams" into the
   ACE_SOCK_SEQPACK_* wrapper-facade. (currently they can only be
   accessed indirectly through ACE_SOCK::set_option(...))

 * Support SOCK_RDM service (connection-less) within ACE for OpenSS7.

 * Convert ATL's histogram utility (located under
   performance-tests/SCTP) into a ACE utility and integrate with other
   ACE provided statistics classes.

 * Support Draft API msg notifications via sendmsg() and recvmsg().  


USAGE
-----

 SOCK_STREAM - Use the ACE_SOCK_Connector, ACE_SOCK_Stream and
               ACE_SOCK_Acceptor classes. In ACE_SOCK_Connector pass
               the value IPPROTO_SCTP for the protocol parameter in
               either the constructor or the connect(...) method
               as shown in SOCK_STREAM_clt.cpp. In ACE_SOCK_Acceptor
               pass the value IPPROTO_SCTP for the protocol parameter
               in either the constructor or the open(...) method
               as shown in SOCK_STREAM_srv.cpp.

               You must include the file sctp.h in order for
               IPPROTO_SCTP to be defined.  This file should be under
               /usr/include/netinet

               Aside from these changes, the classes can be used as
               they are under TCP (the protocol they use by
               default). Be cautious to use SCTP protocol options when
               setting socket options on SCTP sockets (e.g., use
               SCTP_NODELAY, not TCP_NODELAY, to disable Nagle's
               algorithm on an SCTP socket.)

 SOCK_SEQPACKET - Use the ACE_SOCK_SEQPACK_Connector,
                  ACE_SOCK_SEQPACK_Association, and
                  ACE_SOCK_SEQPACK_Acceptor classes, which parallel
                  the familiar ACE_SOCK_Connector, ACE_SOCK_Stream,
                  and ACE_SOCK_Acceptor classes, respectively.  Please
                  see SOCK_SEQPACK_clt.cpp and SOCK_SEQPACK_srv.cpp for
                  more details.

                  In the special case where you want to specify a set
                  of interfaces---other than one or all
                  interfaces---for an ACE_SOCK_SEQPACK_Acceptor, use
                  an ACE_Multihomed_INET_Addr in place of the familiar
                  ACE_INET_Addr.  (See SOCK_SEQPACK_srv.cpp for an
                  example.)

                  SCTP associations may have more than one local and
                  more than one remote address bound to them.
                  Accordingly, ACE_SOCK_SEQPACK_Association provides
                  methods get_local_addrs(...) and
                  get_remote_addrs(...). These methods return the list
                  of local and remote addresses bound to an active
                  mode SCTP socket. Alternately, the familiar
                  ACE_SOCK::get_local_addr(...)  and
                  ACE_SOCK::get_remote_addr(...) methods will work
                  properly with an active mode SCTP socket, but each
                  will only return a single address. These functions
                  are only NOT available on ACE_SOCK_SEQPACK_Acceptor
                  even though that is an SCTP socket as well. This is
                  because the functions getpeername() and
                  getsockname() called on a passive SCTP acceptor
                  socket returns the same values as a TCP socket. As
                  such, the current ACE methods get_local_addr() and
                  get_remote_addr() defined in ACE_SOCK are sufficient.


DESIGN
------

SCTP supports two types of network service: SOCK_STREAM and
SOCK_SEQPACKET.  To integrate SCTP's SOCK_STREAM service into ACE we
had to make a small modification to the current SOCK_STREAM wrapper
facade. We had to add a protocol parameter to one constructor and one
connect method of the ACE_SOCK_Connector class. After this
modification the ACE SOCK_STREAM wrapper facade worked properly over
both TCP and SCTP.

To integrate SCTP's SOCK_SEQPACKET service into ACE we had to create a
new wrapper facade, which we refer to as SOCK_SEQPACK. We closely
emulated the current SOCK_STREAM wrapper facade to develop our new
SOCK_SEQPACK wrapper facade. SOCK_SEQPACK_wrapper_facade.jpg depicts
the classes that implement this new wrapper facade. Also indicated are
those methods that have a substantial change from their SOCK_STREAM
wrapper façade counterparts. Not depicted in the figure but noteworthy
is the removal of the QoS enabled constructor and accept method that
were imported to SOCK_SEQPACK_Acceptor from SOCK_Acceptor and the
removal of the QoS enabled constructor and connect method that were
imported into SOCK_SEQPACK_Connector from SOCK_Connector. SOCK_SEQPACK
association provides two methods to get the list of secondary
addresses associated with the local and remote socket (explained in
more detail in the usage section above).


To enable the user to fully exploit the network path multiplexing
features of SCTP we created a new subclass of ACE_INET_Addr called
ACE_INET_Multihomed_Addr. This class enables applications to specify
restricted subsets of network interfaces for inclusion on SCTP
associations on the client and server side. Multihomed_INET_Addr
provides a subset of the ACE_INET_Addr API with the addition of
optional parameters for lists of secondary addresses or hostnames.  If
just a primary address or hostname is provided
ACE_Multihomed_INET_Addr behaves as an ACE_INET_Addr (in fact it just
populates the base ACE_INET_Addr) This is also depicted in
SOCK_SEQPACK_wrapper_facade.jpg. Multihomed_INET_Addr is only used by
the SOCK_SEQPACK wrapper facade.


All SCTP socket options can be read and written from the current
socket options methods provided by ACE_SOCK. 

Finally, our SOCK_SEQPACK wrapper facade does not yet support SCTP
stream multiplexing.

Here are the files under $(ACE_ROOT) that were either modified or
added. NO files were removed.

$(ACE_ROOT)/ace/ace_dll.dsp                                MODIFIED
$(ACE_ROOT)/ace/OS.h                                       MODIFIED
$(ACE_ROOT)/ace/Makefile.ace                               MODIFIED
$(ACE_ROOT)/ace/SOCK_Connector.h                           MODIFIED
$(ACE_ROOT)/ace/SOCK_Connector.cpp                         MODIFIED

$(ACE_ROOT)/ace/SOCK_SEQPACK_Acceptor.h                    ADDED
$(ACE_ROOT)/ace/SOCK_SEQPACK_Acceptor.i                    ADDED
$(ACE_ROOT)/ace/SOCK_SEQPACK_Acceptor.cpp                  ADDED

$(ACE_ROOT)/ace/SOCK_SEQPACK_Connector.h                   ADDED
$(ACE_ROOT)/ace/SOCK_SEQPACK_Connector.i                   ADDED
$(ACE_ROOT)/ace/SOCK_SEQPACK_Connector.cpp                 ADDED

$(ACE_ROOT)/ace/SOCK_SEQPACK_Association.h                 ADDED
$(ACE_ROOT)/ace/SOCK_SEQPACK_Association.i                 ADDED
$(ACE_ROOT)/ace/SOCK_SEQPACK_Association.cpp               ADDED

$(ACE_ROOT)/ace/Multihomed_INET_Addr.h                     ADDED
$(ACE_ROOT)/ace/Multihomed_INET_Addr.i                     ADDED
$(ACE_ROOT)/ace/Multihomed_INET_Addr.cpp                   ADDED

$(ACE_ROOT)/bin/PerlACE/Process_Unix.pm                    MODIFIED
$(ACE_ROOT)/bin/PerlACE/Process_Win32.pm                   MODIFIED

$(ACE_ROOT)/include/makeinclude/wrapper_macros.GNU         MODIFIED
$(ACE_ROOT)/include/makeinclude/platform_linux.GNU         MODIFIED

$(ACE_ROOT)/tests/Makefile                                 MODIFIED
$(ACE_ROOT)/tests/Multihomed_INET_Addr_Test.cpp            ADDED
$(ACE_ROOT)/tests/Multihomed_INET_Addr_Test.dsp            ADDED
$(ACE_ROOT)/tests/SOCK_SEQPACK_Association_Test.cpp        ADDED
$(ACE_ROOT)/tests/SOCK_SEQPACK_Association_Test.dsp        ADDED
$(ACE_ROOT)/tests/run_test.lst                             MODIFIED
$(ACE_ROOT)/tests/run_tests.bat                            MODIFIED
$(ACE_ROOT)/tests/tests.dsw                                MODIFIED

$(ACE_ROOT)/performance-tests/SCTP/THANKS                  ADDED
$(ACE_ROOT)/performance-tests/SCTP/README                  ADDED
$(ACE_ROOT)/performance-tests/SCTP/README.SCTP             ADDED
$(ACE_ROOT)/performance-tests/SCTP/README.SCTP_in_ACE      ADDED
$(ACE_ROOT)/performance-tests/SCTP/README.SCTP_PERF_TEST   ADDED
$(ACE_ROOT)/performance-tests/SCTP/README.OpenSS7          ADDED
$(ACE_ROOT)/performance-tests/SCTP/README.LKSCTP           ADDED

$(ACE_ROOT)/performance-tests/SCTP/Makefile                ADDED
$(ACE_ROOT)/performance-tests/SCTP/run_spectrum.pl         ADDED

$(ACE_ROOT)/performance-tests/SCTP/hist.h                  ADDED
$(ACE_ROOT)/performance-tests/SCTP/hist.cpp                ADDED

$(ACE_ROOT)/performance-tests/SCTP/Options_Manager.h       ADDED
$(ACE_ROOT)/performance-tests/SCTP/Options_Manager.cpp     ADDED

$(ACE_ROOT)/performance-tests/SCTP/SOCK_STREAM_clt.cpp     ADDED
$(ACE_ROOT)/performance-tests/SCTP/SOCK_STREAM_srv.cpp     ADDED

$(ACE_ROOT)/performance-tests/SCTP/SOCK_SEQPACK_clt.cpp    ADDED
$(ACE_ROOT)/performance-tests/SCTP/SOCK_SEQPACK_srv.cpp    ADDED
