Update TCP manual chapter
authorTom Henderson <tomh@tomh.org>
Mon, 03 Jan 2011 15:48:42 -0800
changeset 6767415711451cc6
parent 6766 4caf532b12c3
child 6768 805f5fc7f670
Update TCP manual chapter
doc/manual/source/tcp.rst
     1.1 --- a/doc/manual/source/tcp.rst	Mon Jan 03 14:35:44 2011 -0800
     1.2 +++ b/doc/manual/source/tcp.rst	Mon Jan 03 15:48:42 2011 -0800
     1.3 @@ -17,51 +17,54 @@
     1.4  * class :cpp:class:`TcpSocket`:  This is defined in
     1.5    ``src/node/tcp-socket.{cc,h}``. This class exists for hosting TcpSocket
     1.6    attributes that can be reused across different implementations. For instance,
     1.7 -  ``TcpSocket::SetInitialCwnd()`` can be used for any of the implementations
     1.8 +  the attribute ``InitialCwnd`` can be used for any of the implementations
     1.9    that derive from class :cpp:class:`TcpSocket`.
    1.10 -* class :cpp:class:`TcpSocketFactory`:  This is used by applications to create
    1.11 -  TCP sockets.  A typical usage can be seen in this snippet:::
    1.12 +* class :cpp:class:`TcpSocketFactory`:  This is used by the layer-4 protocol
    1.13 +  instance to create TCP sockets of the right type.
    1.14  
    1.15 -      // Create the socket if not already created
    1.16 -      if (!m_socket)
    1.17 -        {
    1.18 -          m_socket = Socket::CreateSocket (GetNode(), m_tid);
    1.19 -          m_socket->Bind (m_local);
    1.20 -          ...
    1.21 -        }
    1.22 +There are presently two implementations of TCP available for |ns3|.
    1.23  
    1.24 -The parameter ``m_tid`` controls the TypeId of the actual TCP Socket
    1.25 -implementation that is instantiated. This way, the application can be written
    1.26 -generically and different socket implementations can be swapped out by
    1.27 -specifying the TypeId.
    1.28 +* a natively implemented TCP for ns-3
    1.29 +* support for the `Network Simulation Cradle (NSC) <http://www.wand.net.nz/~stj2/nsc/>`_
    1.30 +
    1.31 +It should also be mentioned that various ways of combining virtual machines
    1.32 +with |ns3| makes available also some additional TCP implementations, but
    1.33 +those are out of scope for this chapter.
    1.34  
    1.35  ns-3 TCP
    1.36  ********
    1.37  
    1.38 -|ns3| contains a port of the TCP model from `GTNetS
    1.39 -<http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/index.html>`_.  This
    1.40 -model is a full TCP, in that it is bidirectional and attempts to model the
    1.41 -connection setup and close logic. In fact, it is a more complete implementation
    1.42 -of the TCP state machine than ns-2's "FullTcp" model. This TCP model was
    1.43 -originally written by George Riley as part of GTNetS and ported to |ns3| by Raj
    1.44 -Bhattacharjea.
    1.45 +Until ns-3.10 release, |ns3| contained a port of the TCP model from `GTNetS
    1.46 +<http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/index.html>`_. 
    1.47 +This implementation was substantially rewritten by Adriam Tam for ns-3.10.
    1.48 +The model is a full TCP, in that it is bidirectional and attempts to model the
    1.49 +connection setup and close logic. 
    1.50  
    1.51  The implementation of TCP is contained in the following files:::
    1.52  
    1.53      src/internet-stack/tcp-header.{cc,h}
    1.54      src/internet-stack/tcp-l4-protocol.{cc,h}
    1.55      src/internet-stack/tcp-socket-factory-impl.{cc,h}
    1.56 -    src/internet-stack/tcp-socket-impl.{cc,h}
    1.57 -    src/internet-stack/tcp-typedefs.h
    1.58 +    src/internet-stack/tcp-socket-base.{cc,h}
    1.59 +    src/internet-stack/tcp-tx-buffer.{cc,h}
    1.60 +    src/internet-stack/tcp-rx-buffer.{cc,h}
    1.61 +    src/internet-stack/tcp-rfc793.{cc,h}
    1.62 +    src/internet-stack/tcp-tahoe.{cc,h}
    1.63 +    src/internet-stack/tcp-reno.{cc,h}
    1.64 +    src/internet-stack/tcp-newreno.{cc,h}
    1.65      src/internet-stack/rtt-estimator.{cc,h}
    1.66 -    src/internet-stack/sequence-number.{cc,h}
    1.67 +    src/common/sequence-number.{cc,h}
    1.68 +
    1.69 +Different variants of TCP congestion control are supported by subclassing
    1.70 +the common base class :cpp:class:`TcpSocketBase`.  Several variants
    1.71 +are supported, including RFC 793 (no congestion control), Tahoe, Reno,
    1.72 +and NewReno.  NewReno is used by default.
    1.73  
    1.74  Usage
    1.75  +++++
    1.76  
    1.77 -The file ``examples/tcp-star-server.cc`` contains an example that
    1.78 -makes use of ``ns3::OnOffApplication`` and ``ns3::PacketSink`` 
    1.79 -applications.
    1.80 +In many cases, usage of TCP is set at the application layer by telling
    1.81 +the |ns3| application which kind of socket factory to use.
    1.82  
    1.83  Using the helper functions defined in ``src/helper``, here is how
    1.84  one would create a TCP receiver:::
    1.85 @@ -74,14 +77,12 @@
    1.86    sinkApp.Start (Seconds (1.0));
    1.87    sinkApp.Stop (Seconds (10.0));
    1.88  
    1.89 -
    1.90  Similarly, the below snippet configures OnOffApplication traffic source to use
    1.91  TCP:::
    1.92  
    1.93    // Create the OnOff applications to send TCP to the server
    1.94    OnOffHelper clientHelper ("ns3::TcpSocketFactory", Address ());
    1.95  
    1.96 -
    1.97  The careful reader will note above that we have specified the TypeId of an
    1.98  abstract base class :cpp:class:`TcpSocketFactory`. How does the script tell
    1.99  |ns3| that it wants the native |ns3| TCP vs. some other one?  Well, when
   1.100 @@ -91,21 +92,44 @@
   1.101  helper API, the TCP that is aggregated to nodes with an Internet stack is the
   1.102  native |ns3| TCP.
   1.103  
   1.104 -Once a TCP socket is created, you will want to follow conventional socket logic
   1.105 +To configure behavior of TCP, a number of parameters are exported through the
   1.106 +:ref:`Attributes <ns-3 attribute system>`. These are documented in the `Doxygen
   1.107 +<http://www.nsnam.org/doxygen/classns3_1_1_tcp_socket.html>` for class
   1.108 +:cpp:class:`TcpSocket`.  For example, the maximum segment size is a
   1.109 +settable attribute.
   1.110 +
   1.111 +For users who wish to have a pointer to the actual socket (so that
   1.112 +socket operations like Bind(), setting socket options, etc. can be
   1.113 +done on a per-socket basis), Tcp sockets can be created by using the 
   1.114 +``Socket::CreateSocket()`` method and passing in the TypeId 
   1.115 +corresponding to the type of socket desired; e.g.::: 
   1.116 +
   1.117 +      // Create the socket if not already created
   1.118 +      TypeId tid = TypeId::LookupByName ("ns3::TcpTahoe");
   1.119 +      Ptr<Socket> localSocket = Socket::CreateSocket (node, tid);
   1.120 +
   1.121 +The parameter ``tid`` controls the TypeId of the actual TCP Socket
   1.122 +implementation that is instantiated. This way, the application can be written
   1.123 +generically and different socket implementations can be swapped out by
   1.124 +specifying the TypeId.
   1.125 +
   1.126 +Once a TCP socket is created, one will want to follow conventional socket logic
   1.127  and either connect() and send() (for a TCP client) or bind(), listen(), and
   1.128  accept() (for a TCP server). :ref:`Sockets API <Sockets APIs>` for a review of
   1.129  how sockets are used in |ns3|.
   1.130  
   1.131 -To configure behavior of TCP, a number of parameters are exported through the
   1.132 -:ref:`Attributes <ns-3 attribute system>`. These are documented in the `Doxygen
   1.133 -<http://www.nsnam.org/doxygen/classns3_1_1_tcp_socket.html>` for class
   1.134 -:cpp:class:`TcpSocket`.
   1.135 +Validation
   1.136 +++++++++++
   1.137 +
   1.138 +Several TCP validation test results can be found in the
   1.139 +`wiki page <http://www.nsnam.org/wiki/index.php/New_TCP_Socket_Architecture>`_ 
   1.140 +describing this implementation.
   1.141  
   1.142  Current limitations
   1.143  +++++++++++++++++++
   1.144  
   1.145 -* Only Tahoe congestion control is presently supported.
   1.146  * Only IPv4 is supported
   1.147 +* Neither the Nagle algorithm nor SACK are supported
   1.148  
   1.149  Network Simulation Cradle
   1.150  *************************
   1.151 @@ -285,7 +309,6 @@
   1.152  and from the Receive path (to ensure that possibly queued data is scheduled for
   1.153  sending).
   1.154  
   1.155 -
   1.156  ``src/internet-stack/nsc-tcp-socket-impl`` implements the nsc socket interface.
   1.157  Each instance has its own nscTcpSocket. Data that is Send() will be handed to
   1.158  the nsc stack via m_nscTcpSocket->send_data(). (and not to nsc-tcp-l4, this is
   1.159 @@ -305,10 +328,8 @@
   1.160  Limitations
   1.161  +++++++++++
   1.162  
   1.163 -
   1.164  * NSC only works on single-interface nodes; attempting to run it on a
   1.165 -  multi-interface node will cause a program error.  This limitation should be
   1.166 -  fixed by ns-3.7.
   1.167 +  multi-interface node will cause a program error.  
   1.168  * Cygwin and OS X PPC are not supported
   1.169  * The non-Linux stacks of NSC are not supported in |ns3|
   1.170  * Not all socket API callbacks are supported