Add chapter on realtime scheduler to manual

- fix segfault when nodes argument <=3
- reduce data rate and run time to get smaller pcap files
- add rng seed to make output stable

.hgtags

@@ -17,3 +17,7 @@ ea16c44eb90db579c83d3434fc8a960be506a7f5 ns-3.1-RC3
 42504fb1f7be7817b8be513cdcd3d9bc8f3660e8 ns-3.1
 5768685f9fdba9fbf2e9561a840f085142c73575 ns-3.1
 dfd634417b8d1896d981b6f44d8f71030611596a ns-3.2-RC1
+319eb29611b18998abbad01548825643a8017bcb ns-3.2-RC2
+d783a951f8f5e64b33bc518f0415f76cae1ca6f3 ns-3.2-RC2-bis
+fa1c7b813873cfa251be7d1b7cea38373fe82fa1 ns-3.2-RC3
+68218c266a844f9fbda34a0ffddb1ae2adebd4b0 ns-3.2-RC4

CHANGES.html

@@ -47,6 +47,7 @@ us a note on ns-developers mailing list.  </p>
 <h1>changes from ns-3.1 to ns-3.2</h1>
 
 <h2>new API:</h2>
+<ul>
 
 <li>26-08-2008; changeset 
 <a href="http://code.nsnam.org/ns-3-dev/rev/5aa65b1ea001">5aa65b1ea001</a></li>
@@ -57,7 +58,6 @@ net devices running in threads other than the main simulation thread to schedule
 events.  Allows for pacing the simulation clock at 1x real-time.
 </li>
 </ul>
-</li>
 
 
 <li>26-08-2008; changeset 
@@ -68,11 +68,11 @@ Add threading and synchronization primitives.  Enabling technology for
 multithreaded simulator implementation.
 </li>
 </ul>
-</li>
 
+</ul>
 <h2>new API in existing classes:</h2>
-
 <ul>
+
 <li>01-08-2008; changeset 
 <a href="http://code.nsnam.org/ns-3-dev/rev/a18520551cdf">a18520551cdf</a></li>
 <ul>
@@ -81,9 +81,10 @@ and a Drop trace.  It also has some new public methods but these are
 mostly for internal use.
 </ul>
 </li>
-</ul>
 
+</ul>
 <h2>changes to existing API:</h2>
+<ul>
 
 <li>05-09-2008; changeset 
 <a href="http://code.nsnam.org/ns-3-dev/rev/aa1fb0f43571">aa1fb0f43571</a></li>
@@ -97,9 +98,7 @@ of interest.  See the Doxygen of CsmaNetDevice::SetFrameSize and
 PointToPointNetDevice::SetFrameSize for a detailed description.
 </li>
 </ul>
-</li>
 
-<ul>
 <li>25-08-2008; changeset 
 <a href="http://code.nsnam.org/ns-3-dev/rev/e5ab96db540e">e5ab96db540e</a></li>
 <ul>
@@ -124,7 +123,6 @@ Users who implement a subclass of the NetDevice base class need to change the si
 of their SetReceiveCallback and SetPromiscReceiveCallback methods.
 </li>
 </ul>
-</li>
 
 
 <li>04-08-2008; changeset 
@@ -144,8 +142,6 @@ Doxygen of CsmaNetDevice::SetMaxPayloadLength for a detailed description of the
 issues and solution.
 </li>
 </ul>
-</li>
-
 
 <li>21-07-2008; changeset 
 <a href="
@@ -174,7 +170,6 @@ To implement this properly, consult the CsmaNetDevice for examples of
 when the m_promiscRxCallback is called.
 </li>
 </ul>
-</li>
 
 
 <li>03-07-2008; changeset 
@@ -205,8 +200,6 @@ ApplicationContainer Install (NodeContainer c);
 </pre>
 </li>
 </ul>
-</li>
-
 
 <li>03-07-2008; changeset 
 <a href="
@@ -227,14 +220,15 @@ Rename all instances method names using "Set..Parameter" to "Set..Attribute"
 </li>
 </ul>
 </li>
-</ul>
 
+</ul>
 <h2>changed behavior:</h2>
 <ul>
 
 <li>07-09-2008; changeset 
 <a href="http://code.nsnam.org/ns-3-dev/rev/5d836ab1523b">5d836ab1523b</a></li>
 <ul>
+
 <li>
 Implement a finite receive buffer for TCP<br>
 The native TCP model in TcpSocketImpl did not support a finite receive buffer.
@@ -264,13 +258,11 @@ When the receiver window clears up due to an application read, the TCP
 will finally ACK the probe byte, and update its advertised window appropriately.
 </li>
 </ul>
- 
 See 
 <a href="http://www.nsnam.org/bugzilla/show_bug.cgi?id=239"> bug 239 </a> for
 more.
 </li>
 </ul>
-</li>
 
 <li>07-09-2008; changeset 
 <a href="http://code.nsnam.org/ns-3-dev/rev/7afa66c2b291">7afa66c2b291</a></li>
@@ -286,7 +278,6 @@ addressed by this changeset.  See
 more.
 </li>
 </ul>
-</li>
 
 <li> 28-07-2008; changeset 
 <a href="http://code.nsnam.org/ns-3-dev/rev/6f68f1044df1">6f68f1044df1</a>
@@ -298,8 +289,8 @@ hold time == refresh time was never intentional, as it leads to
 instability in neighbor detection.
 </ul>
 </li>
-</ul>
 
+</ul>
 
 </body>
 </html>

RELEASE_NOTES

@@ -3,27 +3,30 @@
 
 This file contains ns-3 release notes (most recent releases first).
 
+All of the ns-3 documentation is accessible from the ns-3 website: 
+http://www.nsnam.org
+including tutorials:
+http://www.nsnam.org/tutorials.html
+
 Release 3.2 (pending)
 =====================
 
 Availability
 ------------
-
 This release is immediately available from:
 http://www.nsnam.org/releases/ns-3.2.tar.bz2
 
-What is ns-3 ?
---------------
+Supported platforms
+-------------------
+ns-3.2 has been tested on the following platforms:
+  - linux x86 gcc 4.2, 4.1, and, 3.4.6.
+  - linux x86_64 gcc 4.3.2, 4.2.3, 4.2.1, 4.1.3, 3.4.6
+  - MacOS X ppc and x86
+  - cygwin gcc 3.4.4 (debug only)
 
-ns-3 is a new discrete-event network simulator designed for supporting network
-research and education. ns-3 features a solid, well documented C++ core and 
-models for TCP/IP (IPv4), several link types including WiFi, and mobility 
-models.
-
-ns-3 is an open source project released under the GNU GPLv2 license which 
-allows anyone to use ns-3 without having to pay any license fee or royalties. 
-ns-3 is actively seeking new contributors to extend the range of supported 
-models and/or to maintain existing models.
+Not all ns-3 options are available on all platforms; consult the
+wiki for more information:
+http://www.nsnam.org/wiki/index.php/Installation
 
 New user-visible features
 -------------------------
@@ -40,8 +43,8 @@ New user-visible features
     It is now possible to run simulations synchronized on the real-world
     wall-clock time (contributed by Craig Dowell).
 
-  d) Network Simulation Craddle
-    It is now possible to use the Network Simulation Craddle 
+  d) Network Simulation Cradle
+    It is now possible to use the Network Simulation Cradle 
     (http://www.wand.net.nz/~stj2/nsc/) in ns-3 and run simulations 
     using various versions of kernel TCP network stacks. (contributed
     by Florian Westphal as part of his Google Summer of Code work)
@@ -53,40 +56,24 @@ New user-visible features
     More information on the wiki:
     http://www.nsnam.org/wiki/index.php/Statistical_Framework_for_Network_Simulation
 
-Where to get more information about ns-3
-----------------------------------------
-
-All the ns-3 documentation, is accessible from the ns-3 website: 
-http://www.nsnam.org
-
-Including, tutorials:
-http://www.nsnam.org/tutorials.html
-
-Supported platforms
--------------------
-
-ns-3 is regularly tested on the following platforms:
-  - linux x86 gcc 4.2, 4.1, and, 3.4.6.
-  - linux x86_64 gcc 4.1.3, 4.2.1, 3.4.6
-  - MacOS X ppc and x86
-  - cygwin gcc 3.4.4 (debug only)
+API changes from ns-3.1
+-----------------------
+API changes for this release are documented in the file CHANGES.html
 
 Known issues
 ------------
-
-ns-3 is known to fail on the following platforms:
+ns-3 build is known to fail on the following platforms:
   - gcc 3.3 and earlier
   - optimized builds on gcc 3.4.4 and 3.4.5
   - optimized builds on linux x86 gcc 4.0.x
+  - optimized builds on Ubuntu 8.10 alpha 5 x86 gcc4.3.2
+  - MinGW
 
 The IPv4 API defined in src/node/ipv4.h is expected to undergo major changes 
 in preparation of the merge of the IPv6 API and implementation.
 
-API changes for this release are documented in CHANGES.html
-
 Future releases
 ---------------
-
 Our next release, which is expected to happen in 2 to 4 months from now, will
 feature the merging of some of our projects currently in development: IPv6, 
 emulation, and synchronous posix sockets.

bindings/python/ns3module_helpers.cc

@@ -33,6 +33,9 @@ public:
     }
     virtual void Notify ()
     {
+        PyGILState_STATE __py_gil_state;
+        __py_gil_state = (PyEval_ThreadsInitialized() ? PyGILState_Ensure() : (PyGILState_STATE) 0);
+        
         PyObject *retval = PyObject_CallObject(m_callback, m_args);
         if (retval) {
             if (retval != Py_None) {
@@ -43,6 +46,9 @@ public:
         } else {
              PyErr_Print();
         }
+
+        if (PyEval_ThreadsInitialized())
+            PyGILState_Release(__py_gil_state);
     }
 };
 

doc/build.txt

@@ -1,6 +1,10 @@
 The Waf build system is used to build ns-3.  Waf is a Python-based
 build system (http://www.freehackers.org/~tnagy/waf.html)
 
+Note:  We've added a wiki page with more complete build instructions
+than the quick ones you find below:
+http://www.nsnam.org/wiki/index.php/Installation
+
 === Installing Waf ===
 
 The top-level ns-3 directory should contain a current waf script.
@@ -63,7 +67,6 @@ with --enable-gcov)
     It includes all files in the source directory, except some particular
     extensions that are blacklisted, such as back files (ending in ~).
 
-
 === Extending ns-3 ===
 
 To add new modules:

doc/manual/attributes.texi

@@ -2,6 +2,15 @@
 @chapter Attributes 
 @anchor{chap:Attributes}
 
+@menu
+* Object Overview::
+* Attribute Overview::
+* Extending attributes::
+* Adding new class type::
+* ConfigStore::
+@end menu
+
+
 In ns-3 simulations, there are two main aspects to configuration:
 @itemize @bullet
 @item the simulation topology and how objects are connected 
@@ -48,8 +57,7 @@ Let's review a couple of properties of these objects.
 @node Smart pointers
 @subsection Smart pointers
 
-As introduced above in @ref{Smart Pointers 101}, ns-3 objects 
-are memory managed by a 
+As introduced in the ns-3 tutorial, ns-3 objects are memory managed by a 
 @uref{http://en.wikipedia.org/wiki/Smart_pointer,,reference counting smart pointer implementation}, @code{class ns3::Ptr}. 
 
 Smart pointers are used extensively in the ns-3 APIs, to avoid passing
@@ -496,6 +504,7 @@ None of these mistakes can be detected by the ns-3 codebase so, users
 are advised to check carefully multiple times that they got these right.
 
 
+@node Adding new class type
 @section Adding new class type to the attribute system
 
 From the perspective of the user who writes a new class in the system and
@@ -557,3 +566,158 @@ Rectangle ("xMin|xMax|yMin|yMax") to the underlying Rectangle, and the
 modeler must specify these operators and the string syntactical representation 
 of an instance of the new class.
 
+@node ConfigStore
+@section ConfigStore
+
+@strong{Feedback requested:}  This is an experimental feature of ns-3.
+It is not in the main tree.  If you like this feature and would like
+to provide feedback on it, please email us.
+
+Values for ns-3 attributes can be stored in an ascii text file and
+loaded into a future simulation.  This feature is known as the
+ns-3 ConfigStore.  
+The ConfigStore code is in @code{src/contrib/}.  It is not yet main-tree
+code, because we are seeking some user feedback. 
+
+We can explore this system by using an example.  Copy the @code{csma-bridge.cc}
+file to the scratch directory:
+@verbatim
+  cp examples/csma-bridge.cc scratch/
+  ./waf
+@end verbatim
+
+Let's edit it to add the ConfigStore feature.  First, add an include statement,
+and then add these lines:
+
+@verbatim
+#include "contrib-module.h"
+...
+int main (...)
+{
+  // setup topology
+
+  // Invoke just before entering Simulator::Run ()
+  ConfigStore config;
+  config.Configure ();
+
+  Simulator::Run ();
+}
+@end verbatim
+
+There is an attribute that governs whether the Configure() call either
+stores a simulation configuration in a file and exits, or whether
+it loads a simulation configuration file annd proceeds.  First,
+the @code{LoadFilename} attribute is checked, and if non-empty,
+the program loads the configuration from the filename provided.
+If LoadFilename is empty, and if the @code{StoreFilename} attribute is 
+populated, the configuration will be written to the output filename
+specified.
+
+While it is possible to generate a sample config file and lightly
+edit it to change a couple of values, there are cases where this
+process will not work because the same value on the same object
+can appear multiple times in the same automatically-generated 
+configuration file under different configuration paths.
+
+As such, the best way to use this class is to use it to generate
+an initial configuration file, extract from that configuration
+file only the strictly necessary elements, and move these minimal
+elements to a new configuration file which can then safely
+be edited and loaded in a subsequent simulation run. 
+
+So, let's do that as an example.  We'lll run the program once
+to create a configure file, and look at it. 
+If you are running bash shell, the below command should work (which illustrates
+how to set an attribute from the command line):
+@verbatim
+./build/debug/scratch/csma-bridge --ns3::ConfigStore::StoreFilename=test.config
+@end verbatim
+or, if the above does not work (the above requires rpath support), try this:
+@verbatim
+./waf --command-template="%s --ns3::ConfigStore::StoreFilename=test.config" --run scratch/csma-bridge
+@end verbatim
+
+Running the program should yield a "test.config" output configuration file 
+that looks like this:
+@verbatim
+/$ns3::NodeListPriv/NodeList/0/$ns3::Node/DeviceList/0/$ns3::CsmaNetDevice/Addre
+ss 00:00:00:00:00:01
+/$ns3::NodeListPriv/NodeList/0/$ns3::Node/DeviceList/0/$ns3::CsmaNetDevice/Frame
+Size 1518
+/$ns3::NodeListPriv/NodeList/0/$ns3::Node/DeviceList/0/$ns3::CsmaNetDevice/SendE
+nable true
+/$ns3::NodeListPriv/NodeList/0/$ns3::Node/DeviceList/0/$ns3::CsmaNetDevice/Recei
+veEnable true
+/$ns3::NodeListPriv/NodeList/0/$ns3::Node/DeviceList/0/$ns3::CsmaNetDevice/TxQue
+ue/$ns3::DropTailQueue/MaxPackets 100
+/$ns3::NodeListPriv/NodeList/0/$ns3::Node/DeviceList/0/$ns3::CsmaNetDevice/Mtu 1
+500
+...
+@end verbatim
+
+The above lists, for each object in the script topology, the value of each 
+registered attribute.  The syntax of this file is that the unique name
+of the attribute (in the attribute namespace) is specified on each line,
+followed by a value.  
+
+This file is intended to be a convenient record of the parameters that were 
+used in a given simulation run, and can be stored with simulation
+output files.  Additionally, 
+this file can also be used to parameterize a simulation, instead of
+editing the script or passing in command line arguments.   For instance,
+a person wanting to run the simulation can examine and tweak the values
+in a pre-existing configuration file, and pass the file to the
+program.   In this case, the relevant commands are:
+@verbatim
+./build/debug/scratch/csma-bridge --ns3::ConfigStore::LoadFilename=test.config
+@end verbatim
+or, if the above does not work (the above requires rpath support), try this:
+@verbatim
+./waf --command-template="%s --ns3::ConfigStore::LoadFilename=test.config" --run scratch/csma-bridge
+@end verbatim
+
+@subsection GTK-based ConfigStore
+
+There is a GTK-based front end for the ConfigStore.  This allows users
+to use a GUI to access and change variables.  Screenshots of this
+feature are available in the 
+@uref{http://www.nsnam.org/docs/ns-3-overview.pdf,,ns-3 Overview} presentation.
+
+To use this feature, one must install libgtk and libgtk-dev; an example
+Ubuntu installation command is:
+@verbatim
+sudo apt-get install libgtk2.0-0 libgtk2.0-dev
+@end verbatim
+To check whether it is configured or not, check the output of the
+./waf configure step:
+@verbatim
+---- Summary of optional NS-3 features:
+Threading Primitives          : enabled
+Real Time Simulator           : enabled
+GtkConfigStore                : not enabled (library 'gtk+-2.0 >= 2.12' not found)
+@end verbatim
+
+In the above example, it was not enabled, so it cannot be used until a
+suitable version is installed and ./waf configure; ./waf is rerun.
+
+Usage is almost the same as the non-GTK-based version:
+@verbatim
+  // Invoke just before entering Simulator::Run ()
+  GtkConfigStore config;
+  config.Configure ();
+@end verbatim
+
+Now, when you run the script, a GUI should pop up, allowing you to open
+menus of attributes on different nodes/objects, and then launch the
+simulation execution when you are done.  
+
+@subsection Future work
+There are a couple of possible improvements:
+@itemize bullet
+@item save a unique version number with date and time at start of file
+@item save rng initial seed somewhere.
+@item make each RandomVariable serialize its own initial seed and re-read
+it later
+@item add the default values
+@end itemize
+

doc/manual/manual.texi

@@ -81,9 +81,11 @@ see @uref{http://www.nsnam.org/docs/manual.pdf}.
 * Random variables::
 * Callbacks::
 * Attributes::
+* RealTime::
 * Packets::
 * Sockets APIs::
 * Node and Internet Stack::
+* TCP::
 * Routing overview::
 * Troubleshooting
 @end menu
@@ -91,10 +93,12 @@ see @uref{http://www.nsnam.org/docs/manual.pdf}.
 @include random.texi
 @include callbacks.texi
 @include attributes.texi
+@include realtime.texi
 @include packets.texi
 @include sockets.texi
 @include node.texi
 @c @include output.texi
+@include tcp.texi
 @include routing.texi
 @c @include other.texi
 @include troubleshoot.texi

doc/manual/realtime.texi

@@ -0,0 +1,100 @@
+@node RealTime
+@chapter Real-Time Scheduler
+@anchor{chap:RealTime}
+
+ns-3 has been designed for integration into testbed and virtual machine
+environments.  To integrate with real network stacks and emit/consume
+packets, a real-time scheduler is needed to try to lock the simulation
+clock with the hardware clock.  We describe here a component of this:
+the RealTime scheduler. 
+
+The purpose of the realtime scheduler is to cause the progression of 
+the simulation clock to occur synchronously with respect to some 
+external time base. Without the presence of an external time base 
+(wall clock), simulation time jumps instantly from one simulated time to 
+the next.
+
+@section Behavior
+
+When using a non-realtime scheduler (the default in ns-3), the simulator
+advances the simulation time to the next scheduled event.  During event
+execution, simulation time is frozen.  With the realtime scheduler, the 
+behavior is similar from the perspective of simulation models (i.e.,
+simulation time is frozen during event execution), but between events,
+the simulator will attempt to keep the simulation clock aligned with
+the machine clock.
+
+When an event is finished executing, and the scheduler moves to the next
+event, the scheduler compares the next event execution time with the
+machine clock.  If the next event is scheduled for a future time,
+the simulator sleeps until that realtime is reached and then executes
+the next event.
+
+It may happen that, due to the processing inherent in the execution
+of simulation events, that the simulator cannot keep up with realtime.
+In such a case, it is up to the user configuration what to do.  There
+are two ns-3 attributes that govern the behavior.  The first is
+@code{ns3::RealTimeSimulatorImpl::SynchronizationMode}.  The two
+entries possible for this attribute are @code{BestEffort} (the default)
+or @code{HardLimit}.  In "BestEffort" mode, the simulator will just
+try to catch up to realtime by executing events until it reaches
+a point where the next event is in the (realtime) future, or else
+the simulation ends.  In BestEffort mode, then, it is possible for
+the simulation to consume more time than the wall clock time.  The
+other option "HardLimit" will cause the simulation to abort if the tolerance
+threshold is exceeded.  This attribute is
+@code{ns3::RealTimeSimulatorImpl::HardLimit} and the default is 0.1 seconds.   
+
+A different mode of operation is one in which simulated time is @strong{not}
+frozen during an event execution.  This mode of realtime simulation was
+implemented but removed from the ns-3 tree because of questions of whether
+it would be useful.  If users are interested in a realtime simulator
+for which simulation time does not freeze during event execution (i.e.,
+every call to @code{Simulator::Now()} returns the current wall clock time,
+not the time at which the event started executing), please contact the
+ns-developers mailing list.
+
+@section Usage
+
+The usage of the realtime simulator is straightforward, from a scripting
+perspective.  Users just need to set the attribute 
+@code{SimulatorImplementationType} to the Realtime simulator, such as follows:
+@verbatim
+  GlobalValue::Bind ("SimulatorImplementationType",
+    StringValue ("ns3::RealtimeSimulatorImpl"));
+@end verbatim
+
+There is a script in @code{examples/realtime-udp-echo.cc} that has an
+example of how to configure the realtime behavior.  Try:
+@verbatim
+./waf --run realtime-udp-echo
+@end verbatim
+
+Whether the simulator will work in a best effort or hard limit policy
+fashion is governed by the attributes explained in the previous section.
+
+@section Implementation
+
+The implementation is contained in the following files:
+@itemize @bullet
+@item @code{src/simulator/realtime-simulator-impl.{cc,h}}
+@item @code{src/simulator/wall-clock-synchronizer.{cc,h}}
+@end itemize
+
+In order to create a realtime scheduler, to a first approximation you 
+just want to cause simulation time jumps to consume real time. We propose 
+doing this using a combination of sleep- and busy- waits. Sleep-waits cause 
+the calling process (thread) to yield the processor for some amount of time. 
+Even though this specified amount of time can be passed to nanosecond 
+resolution, it is actually converted to an OS-specific granularity. 
+In Linux, the granularity is called a Jiffy. Typically this resolution is 
+insufficient for our needs (on the order of a ten milliseconds), so we 
+round down and sleep for some smaller number of Jiffies. The process is 
+then awakened after the specified number of Jiffies has passed. At this 
+time, we have some residual time to wait. This time is generally smaller 
+than the minimum sleep time, so we busy-wait for the remainder of the time. 
+This means that the thread just sits in a for loop consuming cycles until 
+the desired time arrives. After the combination of sleep- and busy-waits, 
+the elapsed realtime (wall) clock should agree with the simulation time 
+of the next event and the simulation proceeds. 
+

doc/manual/tcp.texi

@@ -0,0 +1,342 @@
+@node TCP
+@chapter TCP models in ns-3
+@anchor{chap:TCP}
+
+This chapter describes the TCP models available in ns-3.
+
+@section Generic support for TCP
+
+ns-3 was written to support multiple TCP implementations.  The 
+implementations inherit from a few common header classes in the
+@code{src/node} directory, so that user code can swap out implementations
+with minimal changes to the scripts.
+
+There are two important abstract base classes:
+@itemize @bullet
+@item @code{class TcpSocket}:  This is defined in @code{src/node/tcp-socket.{cc,h}}.  This class exists for hosting TcpSocket attributes that can be
+reused across different implementations.  For instance, 
+@code{TcpSocket::SetInitialCwnd()} can be used for any of the implementations
+that derive from @code{class TcpSocket}.
+@item @code{class TcpSocketFactory}:  This is used by applications to
+create TCP sockets.  A typical usage can be seen in this snippet:
+@verbatim
+  // Create the socket if not already created
+  if (!m_socket)
+    {
+      m_socket = Socket::CreateSocket (GetNode(), m_tid);
+      m_socket->Bind (m_local);
+      ...
+    }
+@end verbatim
+The parameter @code{m_tid} controls the TypeId of the actual Tcp Socket
+implementation that is instantiated.  This way, the application can be
+written generically and different socket implementations can be swapped out
+by specifying the TypeId.
+@end itemize  
+
+@section ns-3 TCP
+
+ns-3 contains a port of the TCP model from 
+@uref{http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/index.html,,GTNetS}.  This model is a full TCP, in that it is 
+bidirectional and attempts to model the connection setup and
+close logic.  In fact, it is a more complete implementation of the TCP
+state machine than ns-2's "FullTcp" model.  This TCP model was originally 
+written by George Riley
+as part of GTNetS and ported to ns-3 by Raj Bhattacharjea.
+
+The implementation of TCP is contained in the following files:
+@verbatim
+src/internet-stack/tcp-header.{cc,h}
+src/internet-stack/tcp-l4-protocol.{cc,h}
+src/internet-stack/tcp-socket-factory-impl.{cc,h}
+src/internet-stack/tcp-socket-impl.{cc,h}
+src/internet-stack/tcp-typedefs.h
+src/internet-stack/rtt-estimator.{cc,h}
+src/internet-stack/sequence-number.{cc,h}
+@end verbatim
+
+@subsection Usage
+
+The file @code{examples/tcp-star-server.cc} contains an example that
+makes use of @code{ns3::OnOffApplication} and @code{ns3::PacketSink} 
+applications.
+
+Using the helper functions defined in @code{src/helper}, here is how
+one would create a TCP receiver:
+@verbatim
+  // Create a packet sink on the star "hub" to receive these packets
+  uint16_t port = 50000;
+  Address sinkLocalAddress(InetSocketAddress (Ipv4Address::GetAny (), port));
+  PacketSinkHelper sinkHelper ("ns3::TcpSocketFactory", sinkLocalAddress);
+  ApplicationContainer sinkApp = sinkHelper.Install (serverNode);
+  sinkApp.Start (Seconds (1.0));
+  sinkApp.Stop (Seconds (10.0));
+@end verbatim
+
+Similarly, the below snippet configures OnOffApplication traffic
+source to use
+TCP:
+@verbatim
+  // Create the OnOff applications to send TCP to the server
+  OnOffHelper clientHelper ("ns3::TcpSocketFactory", Address ());
+@end verbatim
+
+The careful reader will note above that we have specified the TypeId
+of an abstract base class @code{TcpSocketFactory}.  How does the
+script tell ns-3 that it wants the native ns-3 TCP vs. some other one?
+Well, when internet stacks are added to the node, the default
+TCP implementation that is aggregated to the node is the ns-3 TCP.
+This can be overridden as we show below when using Network
+Simulation Cradle.  So, by default, when using the ns-3 helper API,
+the TCP that is aggregated to nodes with an Internet stack is the
+native ns-3 TCP.
+
+Once a TCP socket is created, you will want to follow conventional
+socket logic and either connect() and send() (for a TCP client)
+or bind(), listen(), and accept() (for a TCP server).  
+@xref{Sockets APIs,,Sockets API} for a review of how sockets are used
+in ns-3.
+
+To configure behavior of TCP, a number of parameters are exported through
+the @ref{Attributes,,ns-3 attribute system}.  These are documented in the
+@uref{http://www.nsnam.org/doxygen/classns3_1_1_tcp_socket.html,,Doxygen} 
+for @code{class TcpSocket}.
+
+@subsection Current limitations
+@itemize @bullet
+@item Only Tahoe congestion control is presently supported.
+@item Only IPv4 is supported (IPv6 support will start to be added in ns-3.3).
+@item @uref{http://www.nsnam.org/bugzilla/show_bug.cgi?id=198,,Bug 198}:  TcpSocketImpl doesn't send acks with data packets in two-way transfers
+@item @uref{http://www.nsnam.org/bugzilla/show_bug.cgi?id=250,,Bug 250}:  Tcp breaks if you set the DelAckCount parameter to be greater than 2
+@item @uref{http://www.nsnam.org/bugzilla/show_bug.cgi?id=311,,Bug 311}:  Tcp socket close returns -1 but does not set errno.
+@end itemize
+
+@section Network Simulation Cradle
+
+The @uref{http://www.wand.net.nz/~stj2/nsc/,,Network Simulation Cradle (NSC)} 
+is a framework for wrapping real-world network
+code into simulators, allowing simulation of real-world behavior at little 
+extra cost.  This work has been validated by comparing situations using 
+a test network with the same situations in the simulator. To date, it has 
+been shown that the NSC is able to produce extremely accurate results.
+NSC supports four real world stacks: FreeBSD, OpenBSD, lwIP and Linux.
+Emphasis has been placed on not changing any of the network stacks by hand. 
+Not a single line of code has been changed in the network protocol 
+implementations of any of the above four stacks. However, a custom C 
+parser was built to programmatically change source code.
+
+NSC has previously been ported to ns-2 and OMNeT++, and recently 
+was added to ns-3.  This section describes the ns-3 port of NSC and
+how to use it.
+
+@subsection Prerequisites
+
+Presently, NSC has been tested and shown to work on these platforms:
+Linux i386 and Linux x86-64.  NSC does not support powerpc at the moment.
+
+NSC requires the packages mercurial, flex, and bison.  
+
+@subsection Configuring and Downloading
+
+NSC is disbled by default and must be explicitly configured in.  To try
+this, type
+@verbatim
+./waf configure --enable-nsc
+@end verbatim
+the output of the configuration will show something like:
+@verbatim
+Checking for NSC supported architecture x86_64                           : ok  
+Pulling nsc updates from https://secure.wand.net.nz/mercurial/nsc
+pulling from https://secure.wand.net.nz/mercurial/nsc
+searching for changes
+no changes found
+---- Summary of optional NS-3 features:
+...
+Network Simulation Cradle     : enabled
+...
+@end verbatim 
+if successful.  Note that the configure script pulls a recent copy of
+NSC from a mercurial repository.  This download will not work if you are not
+online.
+
+If everything went OK, you will see a directory called "nsc" in the top-level
+directory, with contents like this:
+@verbatim
+audit.sh            linux-2.6/          openbsd3/           scons-time.py*
+ChangeLog           linux-2.6.18/       README              SConstruct 
+config.log          linux-2.6.26/       sconsign.py*        sim/
+freebsd5/           lwip-1.3.0/         scons-LICENSE       test/
+globaliser/         lwip-HEAD/          scons-local-1.0.1/  
+INSTALL             ns/                 scons.py*           
+LICENSE             omnetpp/            scons-README        
+@end verbatim
+
+@subsection Building and validating
+
+Building ns-3 with nsc support is the same as building it without; no
+additional arguments are needed for waf.  Building nsc may take some time
+compared to ns-3; it is interleaved in the ns-3 building process.
+
+Try running the regression tests: @code{./waf --regression}.  If NSC has
+been successfully built, the following test should show up in the results:
+@verbatim
+PASS test-tcp-nsc-lfn
+@end verbatim
+
+This confirms that NSC is ready to use.
+
+@subsection Usage
+There are a few example files.  Try
+@verbatim
+./waf --run tcp-nsc-zoo
+./waf --run tcp-nsc-lfn
+@end verbatim
+These examples will deposit some @code{.pcap} files in your directory,
+which can be examined by tcpdump or wireshark.
+
+Let's look at the @code{examples/tcp-nsc-zoo.cc} file for some typical
+usage.  How does it differ from using native ns-3 TCP?  There is one
+main configuration line, when using NSC and the ns-3 helper API, that needs
+to be set:
+@verbatim
+  InternetStackHelper internetStack;
+
+  internetStack.SetNscStack ("liblinux2.6.26.so");
+  // this switches nodes 0 and 1 to NSCs Linux 2.6.26 stack.
+  internetStack.Install (n.Get(0));
+  internetStack.Install (n.Get(1));
+@end verbatim
+
+The key line is the @code{SetNscStack}.  This tells the InternetStack
+helper to aggregate instances of NSC TCP instead of native ns-3 TCP
+to the remaining nodes.  It is important that this function be called
+@strong{before} callling the @code{Install()} function, as shown above.
+
+Which stacks are available to use?  Presently, the focus has been on
+Linux 2.6.18 and Linux 2.6.26 stacks for ns-3.  To see which stacks
+were built, one can execute the following find command at the ns-3 top level
+directory:
+@verbatim
+~/ns-3.2> find nsc -name "*.so" -type f 
+nsc/linux-2.6.18/liblinux2.6.18.so
+nsc/linux-2.6.26/liblinux2.6.26.so
+@end verbatim
+This tells us that we may either pass the library name liblinux2.6.18.so or 
+liblinux2.6.26.so to the above configuration step.
+
+@subsection Stack configuration
+NSC TCP shares the same configuration attributes that are common
+across TCP sockets, as described above and documented in 
+@uref{http://www.nsnam.org/doxygen/classns3_1_1_tcp_socket.html,,Doxygen} 
+
+Additionally, NSC TCP exports a lot of configuration variables into the 
+ns-3 @ref{Attributes} system, via a @uref{http://en.wikipedia.org/wiki/Sysctl,,
+sysctl}-like interface.  In the @code{examples/tcp-nsc-zoo} example, you
+can see the following configuration:
+@verbatim
+  // this disables TCP SACK, wscale and timestamps on node 1 (the attributes represent sysctl-values).
+  Config::Set ("/NodeList/1/$ns3::Ns3NscStack<linux2.6.26>/net.ipv4.tcp_sack", StringValue ("0"));
+  Config::Set ("/NodeList/1/$ns3::Ns3NscStack<linux2.6.26>/net.ipv4.tcp_timestamps", StringValue ("0"));
+  Config::Set ("/NodeList/1/$ns3::Ns3NscStack<linux2.6.26>/net.ipv4.tcp_window_scaling", StringValue ("0"));
+@end verbatim
+These additional configuration variables are not available to native ns-3
+TCP.
+
+@subsection NSC API
+
+This subsection describes the API that NSC presents to ns-3 or any other
+simulator.  NSC provides its API in the form of a number of classes that
+are defined in @code{sim/sim_interface.h} in the nsc directory.
+
+@itemize @bullet
+@item @strong{INetStack}
+INetStack contains the 'low level' operations for the operating system 
+network stack, e.g. in and output functions from and to the network stack 
+(think of this as the 'network driver interface'. There are also functions 
+to create new TCP or UDP sockets.
+@item @strong{ISendCallback}
+This is called by NSC when a packet should be sent out to the network. 
+This simulator should use this callback to re-inject the packet into the 
+simulator so the actual data can be delivered/routed to its destination, 
+where it will eventually be handed into Receive() (and eventually back to the 
+receivers NSC instance via INetStack->if_receive() ).
+@item @strong{INetStreamSocket}
+This is the structure defining a particular connection endpoint (file 
+descriptor). It contains methods to operate on this endpoint, e.g. connect, 
+disconnect, accept, listen, send_data/read_data, ...
+@item @strong{IInterruptCallback}
+This contains the wakeup callback, which is called by NSC whenever 
+something of interest happens. Think of wakeup() as a replacement of the 
+operating systems wakeup function: Whenever the operating system would 
+wake up a process that has been waiting for an operation to complete (for 
+example the TCP handshake during connect()), NSC invokes the wakeup() callback 
+to allow the simulator to check for state changes in its connection endpoints. 
+@end itemize
+
+@subsection ns-3 implementation
+
+The ns-3 implementation makes use of the above NSC API, and is implemented
+as follows.
+
+The three main parts are:
+@itemize @bullet
+@item @code{ns3::NscTcpL4Protocol}:  a subclass of Ipv4L4Protocol (and two nsc classes: ISendCallback and IInterruptCallback)
+@item @code{ns3::NscTcpSocketImpl}: a subclass of TcpSocket 
+@item @code{ns3::NscTcpSocketFactoryImpl}:  a factory to create new NSC
+sockets
+@end itemize
+
+@code{src/internet-stack/nsc-tcp-l4-protocol} is the main class. Upon 
+Initialization, it loads an nsc network stack to use (via dlopen()). Each 
+instance of this class may use a different stack. The stack 
+(=shared library) to use is set using the SetNscLibrary() method (at 
+this time its called indirectly via the internet stack helper). The nsc 
+stack is then set up accordingly (timers etc). The 
+NscTcpL4Protocol::Receive() function hands the packet it receives (must be 
+a complete tcp/ip packet) to the nsc stack for further processing. 
+To be able to send packets, this class implements the nsc send_callback 
+method. This method is called by nsc whenever the nsc stack wishes to 
+send a packet out to the network. Its arguments are a raw buffer, 
+containing a complete TCP/IP packet, and a length value. This method 
+therefore has to convert the raw data to a Ptr<Packet> usable by ns-3. 
+In order to avoid various ipv4 header issues, the nsc ip header is not 
+included. Instead, the tcp header and the actual payload are put into the 
+Ptr<Packet>, after this the Packet is passed down to layer 3 for sending 
+the packet out (no further special treatment is needed in the send code 
+path).
+
+This class calls @code{ns3::NscTcpSocketImpl} both from the nsc wakeup() 
+callback and from the Receive path (to ensure that possibly queued data 
+is scheduled for sending).
+
+
+@code{src/internet-stack/nsc-tcp-socket-impl} implements the nsc socket 
+interface. Each instance has its own nscTcpSocket. Data that is Send() 
+will be handed to the nsc stack via m_nscTcpSocket->send_data(). (and not 
+to nsc-tcp-l4, this is the major difference compared to ns-3 TCP). The 
+class also queues up data that is Send() before the underlying 
+descriptor has entered an ESTABLISHED state. This class is called from 
+the nsc-tcp-l4 class, when the nsc-tcp-l4 wakeup() callback is invoked by 
+nsc. nsc-tcp-socket-impl then checks the current connection state 
+(SYN_SENT, ESTABLISHED, LISTEN...) and schedules appropriate callbacks as 
+needed, e.g. a LISTEN socket will schedule Accept to see if a new 
+connection must be accepted, an ESTABLISHED socket schedules any pending 
+data for writing, schedule a read callback, etc.
+
+Note that @code{ns3::NscTcpSocketImpl} does not interact with nsc-tcp 
+directly: instead, data is redirected to nsc. nsc-tcp calls the 
+nsc-tcp-sockets of a node when its wakeup callback is invoked by nsc. 
+
+@subsection Limitations
+@itemize @bullet
+@item NSC only works on single-interface nodes; attempting to run it on
+a multi-interface node will cause a program error.  This limitation should
+be fixed by ns-3.3.
+@item Cygwin and OS X PPC are not presently supported
+@item The non-Linux stacks of NSC are not supported
+@item NSC's integration into the build system presently requires on-line
+access and mercurial, and is a slow download.
+@end itemize
+
+For more information, see
+@uref{http://www.nsnam.org/wiki/index.php/Network_Simulation_Cradle_Integration,, this wiki page}.

doc/release_steps.txt

@@ -14,23 +14,23 @@ Steps in doing an ns-3 release
 4. test dev tarball on release platforms (waf check and maybe some other 
    scripts)
 5. once you are happy with the tarball, tag ns-3-dev and ns-3-dev-ref-traces
-   - hg tag "ns-3.1x"
+   - hg tag "ns-3.x"
    - hg push 
    - cd into regression/ns-3-dev-ref-traces
-   - hg tag "ns-3.1x"
+   - hg tag "ns-3.x"
    - hg push 
 6. clone the tagged ns-3-dev and place it on the repository
    - ssh code.nsnam.org; sudo tcsh; su code;
    - cp -r /home/code/repos/ns-3-dev /home/code/repos/ns-3.1x
-   - cd /home/code/repos/ns-3.1x/.hg and edit the hgrc appropriately:
-     "description = ns-3.1x release
-      name = ns-3.1x"
+   - cd /home/code/repos/ns-3.x/.hg and edit the hgrc appropriately:
+     "description = ns-3.x release
+      name = ns-3.x"
    - clone the ns-3-dev-ref-traces and place it on the repository as above
-     but use the name ns-3.1x-ref-traces and edit the hgrc appropriately
-7. check out a clean version of the new release (ns-3.1x) somewhere
+     but use the name ns-3.x-ref-traces and edit the hgrc appropriately
+7. check out a clean version of the new release (ns-3.x) somewhere
 8. Update the VERSION for this new release
    - change the string 3-dev in the VERSION file to the real version 
-     (e.g. 3.1)  This must agree with the version name you chose in the clone
+     (e.g. 3.2)  This must agree with the version name you chose in the clone
      for the regression tests to work.
    - hg commit
    - hg push
@@ -46,16 +46,17 @@ Steps in doing an ns-3 release
    - There should be no regression errors at this time
 10. Create final tarballs
    - ./waf configure; ./waf dist
-   - this will create an ns-3.1x.tar.bz2 tarball
-   - this will also create a ns-3.1x-ref-traces.tar.bz2 tarball
-11. upload "ns-3.1x.tar.bz2" to the /var/www/html/releases/ directory on 
+   - this will create an ns-3.x.tar.bz2 tarball
+   - this will also create a ns-3.x-ref-traces.tar.bz2 tarball
+11. upload "ns-3.x.tar.bz2" to the /var/www/html/releases/ directory on 
    the www.nsnam.org server
    - give it 644 file permissions, and user/group = apache
-12. upload "ns-3.1x-ref-traces.tar.bz2" to the /var/www/html/releases/ 
+12. upload "ns-3.x-ref-traces.tar.bz2" to the /var/www/html/releases/ 
    directory on the www.nsnam.org server
    - give it 644 file permissions, and user/group = apache
 13. update web pages on www.nsnam.org (source is in the www/ module)
    - clone the source repo (hg clone http://code.nsnam.org/www)
+   - update index.html
    - add link to news.html
    - update getting_started.html
    - update documents.html

doc/tutorial/building-topologies.texi

@@ -812,7 +812,7 @@ usual, you will find the documentation in the ``Classes'' tab of the Doxygen
 documentation.
 
 Now we will return to more familiar ground.  We next create a @code{WifiHelper}
-object and set two default atributes that it will use when creating the actual
+object and set two default attributes that it will use when creating the actual
 devices.
 
 @verbatim
@@ -1240,12 +1240,13 @@ they happen.
 @end verbatim
 
 If you are feeling brave, there is a list of all trace sources in the 
-@command{ns-3} Doxygen which you can find in the ``NS-3 Modules'' section.  
+@uref{http://www.nsnam.org/doxygen-release/index.html,,ns-3 Doxygen}
+which you can find in the ``Modules'' tab.
 Under the ``core'' section, you will find a link to ``The list of all trace 
 sources.''  You may find it interesting to try and hook some of these 
-traces yourself.  Additionally in the ``NS-3 Modules'' documentation, there is
+traces yourself.  Additionally in the ``Modules'' documentation, there is
 a link to ``The list of all attributes.''  You can set the default value of 
-any of these atributes via the command line as we have previously discussed.
+any of these attributes via the command line as we have previously discussed.
 
 We have just scratched the surface of @command{ns-3} in this tutorial, but we 
 hope we have covered enough to get you started doing useful work.

doc/tutorial/conceptual-overview.texi

@@ -731,10 +731,13 @@ and then build it using waf,
 @verbatim
   ~/repos/ns-3-dev > ./waf
   Entering directory `/home/craigdo/repos/ns-3-dev/build'
-  [432/477] cxx: scratch/first.cc -> build/debug/scratch/first_2.o
-  [475/477] cxx_link: build/debug/scratch/first_2.o ...
-  Compilation finished successfully
-~/repos/ns-3-dev >
+  [467/511] cxx: scratch/first.cc -> build/debug/scratch/first_1.o
+  [468/511] cxx: scratch/multiple-sources/simple-main.cc -> build/debug/scratch/multiple-sources/simple-main_2.o
+  [469/511] cxx: scratch/multiple-sources/simple-simulation.cc -> build/debug/scratch/multiple-sources/simple-simulation_2.o
+  [470/511] cxx: scratch/simple.cc -> build/debug/scratch/simple_3.o
+  [508/511] cxx_link: build/debug/scratch/first_1.o -> build/debug/scratch/first
+  Compilation finished successfully 
+  ~/repos/ns-3-dev >
 @end verbatim
 
 You can now run the example (note that if you build your program in the scratch

doc/tutorial/getting-started.texi

@@ -44,8 +44,9 @@ the Getting Started section of the  @command{ns-3} web site:
 
 @cindex tarball
 The @command{ns-3} code is available in Mercurial repositories on the server
-code.nsnam.org.  You can download a tarball, but we recommend working with
-Mercurial --- it will make your life easier in the long run.
+code.nsnam.org.  You can download a tarball release at
+@uref{http://www.nsnam.org/releases/}, or you can work with repositories
+using Mercurial.
 
 @cindex repository
 If you go to the following link: @uref{http://code.nsnam.org/},
@@ -62,11 +63,11 @@ The current development snapshot (unreleased) of @command{ns-3} may be found
 at:  @uref{http://code.nsnam.org/ns-3-dev/}.  The developers attempt to keep
 this repository in a consistent, working state but it is a development area 
 with unreleased code present, so you may want to consider staying with an 
-official release.
+official release if you do not need newly-introduced features.
 
 Since the release numbers are going to be changing, I will stick with 
 the more constant ns-3-dev here in the tutorial, but you can replace the 
-string ``ns-3-dev'' with your choice of release (e.g., ns-3.1) in the text 
+string ``ns-3-dev'' with your choice of release (e.g., ns-3.2) in the text 
 below.  You can find the latest version  of the code either by inspection of 
 the repository list or by going to the ``Getting Started'' web page and 
 looking for the latest release identifier.
@@ -108,6 +109,15 @@ look something like the following:
   doc/     ns3/       RELEASE_NOTES  src/      waf*
 @end verbatim
 
+Similarly, if working from a released version instead, you can simply
+@verbatim
+  cd
+  mkdir repos
+  wget http://www.nsnam.org/releases/ns-3.2.tar.bz2
+  bunzip2 ns-3.2.tar.bz2
+  tar xvf ns-3.2.tar
+@end verbatim 
+
 You are now ready to build the @command{ns-3} distribution.
 
 @c ========================================================================
@@ -137,34 +147,58 @@ for you).  As the build system checks for various dependencies you should see
 output that looks similar to the following,
 
 @verbatim
-  ~/repos/ns-3-dev >./waf -d debug configure
-  Checking for program g++                 : ok /usr/bin/g++
-  Checking for compiler version            : ok Version 4.1.2
-  Checking for program cpp                 : ok /usr/bin/cpp
-  Checking for program ar                  : ok /usr/bin/ar
-  Checking for program ranlib              : ok /usr/bin/ranlib
-  Checking for compiler could create programs : ok
-  Checking for compiler could create shared libs : ok
-  Checking for compiler could create static libs : ok
-  Checking for flags -O2 -DNDEBUG                : ok
-  Checking for flags -g -DDEBUG                  : ok
-  Checking for flags -g3 -O0 -DDEBUG             : ok
-  Checking for flags -Wall                       : ok
-  Checking for g++                               : ok
-  Checking for header stdlib.h                   : ok
-  Checking for header stdlib.h                   : ok
-  Checking for header signal.h                   : ok
-  Checking for high precision time implementation : 128-bit integer
-  Checking for header stdint.h                    : ok
-  Checking for header inttypes.h                  : ok
-  Checking for header sys/inttypes.h              : not found
-  Checking for package gtk+-2.0 >= 2.12           : not found
-  Checking for package goocanvas gthread-2.0      : not found
-  Checking for program diff                       : ok /usr/bin/diff
-  Configuration finished successfully; project is now ready to build.
-  ~/repos/ns-3-dev >
+Checking for program g++                 : ok /usr/bin/g++ 
+Checking for compiler version            : ok Version 4.0.1 
+Checking for program cpp                 : ok /usr/bin/cpp 
+Checking for program ar                  : ok /usr/bin/ar 
+Checking for program ranlib              : ok /usr/bin/ranlib 
+Checking for compiler could create programs : ok  
+Checking for compiler could create shared libs : ok  
+Checking for compiler could create static libs : ok  
+Checking for flags -O2 -DNDEBUG                : ok  
+Checking for flags -g -DDEBUG                  : ok  
+Checking for flags -g3 -O0 -DDEBUG             : ok  
+Checking for flags -Wall                       : ok  
+Checking for g++                               : ok  
+Checking for -Wno-error=deprecated-declarations compilation flag support : no 
+Checking for header stdlib.h                   : ok  
+Checking for header stdlib.h                   : ok  
+Checking for header signal.h                   : ok  
+Checking for library rt                        : not found 
+Checking for header pthread.h                  : ok  
+Checking for high precision time implementation: 128-bit integer 
+Checking for header stdint.h                   : ok  
+Checking for header inttypes.h                 : ok  
+Checking for header sys/inttypes.h             : not found 
+Checking for package gtk+-2.0 >= 2.12          : not found 
+Checking for library sqlite3                   : ok  
+Checking for package goocanvas gthread-2.0     : not found 
+Checking for program python                    : ok /usr/local/bin/python 
+Checking for Python version >= 2.3             : ok 2.4.3 
+Checking for library python2.4                 : not found 
+Checking for library python2.4                 : not found 
+Checking for library python24                  : not found 
+Checking for program python2.4-config          : not found 
+Checking for header Python.h                   : not found 
+Checking for program diff                      : ok /usr/bin/diff 
+Checking for program hg                        : ok /opt/local/bin/hg 
+---- Summary of optional NS-3 features:
+Threading Primitives        : enabled
+Real Time Simulator         : enabled
+GtkConfigStore              : not enabled (library 'gtk+-2.0 >= 2.12' not found)
+SQlite stats data output    : enabled
+Network Simulation Cradle   : not enabled (--enable-nsc configure option not given)
+Python Bindings             : not enabled (Python development headers not found.)
+Configuration finished successfully; project is now ready to build. 
 @end verbatim
 
+Note the trailing portion of the above output.  Some ns-3 options are
+not enabled by default or require support from the underlying system.
+For instance, to enable Python bindings, Python development headers must
+be installed on the host machine, and they were not found in the above
+example, so Python scripting will not be supported in the resulting build.
+For this tutorial, we will focus on the non-optional pieces of ns-3.
+
 The build system is now configured and you can build the debug versions of 
 the @command{ns-3} programs by simply typing,
 
@@ -172,8 +206,10 @@ the @command{ns-3} programs by simply typing,
   ./waf
 @end verbatim
 
+(Hint:  if you have a multicore machine, use the "-j JOBS" option to speed
+up your build, where JOBS is the number of cores)
 You will see many Waf status messages displayed as the system compiles.  The
-most important is the last one,
+most important is the last one:
 
 @verbatim
   Compilation finished successfully
@@ -187,8 +223,8 @@ most important is the last one,
 @section Testing ns-3
 
 @cindex unit tests
-You can run the unit tests of the @command{ns-3} distribution by running the ``check''
-command,
+You can run the unit tests of the @command{ns-3} distribution by running the 
+``check'' command,
 
 @verbatim
   ./waf check
@@ -213,10 +249,10 @@ test has passed.
   ~/repos/ns-3-dev >
 @end verbatim
 
-@cindex regression tests
 This command is typically run by @code{users} to quickly verify that an 
 @command{ns-3} distribution has built correctly.  
 
+@cindex regression tests
 You can also run our regression test suite to ensure that your distribution and
 tool chain have produced binaries that generate output that is identical to
 reference output files stored in a central location.  To run the regression 
@@ -234,7 +270,9 @@ Mercurial installed, the reference traces will be downloaded from a tarball
 located in the releases section of @code{www.nsnam.org}.  The particular name 
 of the reference trace location is built from the @command{ns-3} version 
 located in the VERSION file, so don't change that string yourself unless you 
-know what you are doing.
+know what you are doing.  (Warning:  The ns-3.2 release requires you
+to be online when you run regression tests because it synchronizes the
+trace directory with an online repository).
 
 Once the reference traces are downloaded to your local machine, Waf will run
 a number of tests that generate what we call trace files.  The content of 
@@ -245,27 +283,32 @@ regression tests pass, you should see something like,
 @verbatim
   ~/repos/ns-3-dev > ./waf --regression
   Entering directory `/home/craigdo/repos/ns-3-dev/build'
-  Compilation finished successfully
+  Compilation finished successfully 
   ========== Running Regression Tests ==========
   Synchronizing reference traces using Mercurial.
-  http://code.nsnam.org/ns-3-dev-ref-traces
-  Done.
+  Pulling http://code.nsnam.org/ns-3-dev-ref-traces from repo.
+  Skipping csma-bridge: Python bindings not available.
+  SKIP test-csma-bridge
   PASS test-csma-broadcast
   PASS test-csma-multicast
   PASS test-csma-one-subnet
   PASS test-csma-packet-socket
+  PASS test-realtime-udp-echo
   PASS test-simple-error-model
   PASS test-simple-global-routing
   PASS test-simple-point-to-point-olsr
   PASS test-tcp-large-transfer
   PASS test-udp-echo
+  PASS test-wifi-wired-bridging
+
   ~/repos/ns-3-dev >
 @end verbatim
 
 If a regression tests fails you will see a FAIL indication along with a
 pointer to the offending trace file and its associated reference trace file
 along with a suggestion on diff parameters and options in order to see what 
-has gone awry.
+has gone awry.  Python regression tests will be SKIPped if Python bindings
+are not built.
 
 @c ========================================================================
 @c Running a Script

doc/tutorial/introduction.texi

@@ -63,19 +63,37 @@ open  environment for researchers to contribute and share their software.
 @section For ns-2 Users
 
 For those familiar with ns-2, the most visible outward change when moving to 
-@command{ns-3} is the choice of scripting language.  Ns-2 is typically 
-scripted in Tcl and results of simulations can be visualized using the 
-Network Animator @command{nam}.  In @command{ns-3} there is currently no
-visualization module, and Python bindings have been developed (Tcl bindings
-have been prototyped using @uref{http://www.swig.org,,SWIG}, but are not 
-currently supported).  In this tutorial, we will concentrate on scripting 
-directly in C++ and interpreting results via trace files.  
+ns-3 is the choice of scripting language.  Ns-2 is 
+scripted in OTcl and results of simulations can be visualized using the 
+Network Animator @command{nam}.  It is not possible to run a simulation
+in ns-2 purely from C++ (i.e., as a main() program without any OTcl).
+Moreover, some components of ns-2 are written in C++ and others in OTcl.
+In ns-3, the simulator is written entirely in C++, with optional
+Python bindings.  Simulation scripts can therefore be written in C++
+or in Python.  The results of some simulations can be visualized by
+@command{nam}, but new animators are under development.  Since ns-3
+generates pcap packet trace files, other utilities can be used to
+analyze traces as well.
+In this tutorial, we will first concentrate on scripting 
+directly in C++ and interpreting results via ascii trace files.  
 
 But there are similarities as well (both, for example, are based on C++ 
-objects, and some code from ns-2 has already been ported to @command{ns-3}). 
-We will try to highlight differences between ns-2 and @command{ns-3}
+objects, and some code from ns-2 has already been ported to ns-3).
+We will try to highlight differences between ns-2 and ns-3
 as we proceed in this tutorial.
 
+A question that we often hear is "Should I still use ns-2 or move to
+ns-3?"  The answer is that it depends.  ns-3 does not have all of the
+models that ns-2 currently has, but on the other hand, ns-3 does have
+new capabilities (such as handling multiple interfaces on nodes 
+correctly, use of IP addressing and more alignment with Internet
+protocols and designs, more detailed 802.11 models, etc.).  ns-2
+models can usually be ported to ns-3 (a porting guide is under
+development).  There is active development on multiple fronts for ns-3.
+The ns-3 developers believe (and certain early users have proven) that
+ns-3 is ready for active use, and should be an attractive alternative
+for users looking to start new simulation projects.  
+
 @node Contributing
 @section Contributing
 
@@ -97,8 +115,12 @@ page;
 started with the simulator (please contact @uref{http://www.nsnam.org/people.html,,one of us}).
 @end itemize  
 
-If you are an ns-3 user, please consider providing your feedback, bug fixes, or
-code to the project.  
+We realize that if you are reading this document, contributing back to 
+the project is probably not your foremost concern at this point, but
+we want you to be aware that contributing is in the spirit of the project and
+that even the act of dropping us a note about your early experience 
+with ns-3 (e.g. "this tutorial section was not clear..."), 
+reports of stale documentation, etc. are much appreciated. 
 
 @node Tutorial Organization
 @section Tutorial Organization
@@ -210,7 +232,10 @@ found at @uref{http://freehackers.org/~tnagy/waf.html}.
 @section Development Environment
 
 @cindex C++
-As mentioned above, scripting in ns-3 is done in C++.  A working 
+@cindex Python
+As mentioned above, scripting in ns-3 is done in C++ or Python.
+As of ns-3.2, most of the ns-3 API is available in Python, but the models
+are written in C++ in either case.  A working 
 knowledge of C++ and object-oriented concepts is assumed in this document.
 We will take some time to review some of the more advanced concepts or 
 possibly unfamiliar language features, idioms and design patterns as they 
@@ -221,23 +246,27 @@ in print.
 
 If you are new to C++, you may want to find a tutorial- or cookbook-based
 book or web site and work through at least the basic features of the language
-before proceeding.
+before proceeding.  For instance, 
+@uref{http://www.cplusplus.com/doc/tutorial/,,this tutorial}.
 
 @cindex toolchain
 @cindex GNU
-The @command{ns-3} system uses the GNU ``toolchain'' for development.  A 
+The @command{ns-3} system uses several components of the GNU ``toolchain'' 
+for development.  A 
 software toolchain is the set of programming tools available in the given 
 environment. For a quick review of what is included in the GNU toolchain see,
-@uref{http://en.wikipedia.org/wiki/GNU_toolchain}.
+@uref{http://en.wikipedia.org/wiki/GNU_toolchain}.  ns-3 uses gcc, 
+GNU binutils, and gdb.  However, we do not use the GNU build system,
+either make or autotools, using Waf instead.
 
 @cindex Linux
 Typically an @command{ns-3} author will work in Linux or a Linux-like
 environment.  For those running under Windows, there do exist environments 
 which simulate the Linux environment to various degrees.  The @command{ns-3} 
-project supports development in the Cygwin and the MinGW environments for 
-these users.  See @uref{http://www.cygwin.com/} and 
-@uref{http://www.mingw.org/} for details on downloading and using these
-systems.  Cygwin provides many of the popular Linux system commands.
+project supports development in the Cygwin environment for 
+these users.  See @uref{http://www.cygwin.com/} 
+for details on downloading (MinGW is presently not supported).
+Cygwin provides many of the popular Linux system commands.
 It can, however, sometimes be problematic due to the way it actually does its 
 emulation, and sometimes interactions with other Windows software can cause 
 problems.
@@ -254,7 +283,10 @@ crash creating a sh.exe.stackdump file when I try to compile my source code.''
 Believe it or not, the @code{Logitech Process Monitor} insinuates itself into
 every DLL in the system when it is running.  It can cause your Cygwin or
 MinGW DLLs to die in mysterious ways and often prevents debuggers from 
-running.  Beware of Logitech software.
+running.  Beware of Logitech software when using Cygwin.
+
+Another alternative to Cygwin is to install a virtual machine environment
+such as VMware server and install a Linux virtual machine.
 
 @node Socket Programming
 @section Socket Programming

examples/csma-bridge.py

@@ -47,14 +47,14 @@ def main(argv):
     #
     # Explicitly create the nodes required by the topology(shown above).
     #
-    print "Create nodes."
+    #print "Create nodes."
     terminals = ns3.NodeContainer()
     terminals.Create(4)
 
     csmaSwitch = ns3.NodeContainer()
     csmaSwitch.Create(1)
 
-    print "Build Topology"
+    #print "Build Topology"
     csma = ns3.CsmaHelper()
     csma.SetChannelAttribute("DataRate", ns3.DataRateValue(ns3.DataRate(5000000)))
     csma.SetChannelAttribute("Delay", ns3.TimeValue(ns3.MilliSeconds(2)))
@@ -83,7 +83,7 @@ def main(argv):
 
     # We've got the "hardware" in place.  Now we need to add IP addresses.
     #
-    print "Assign IP Addresses."
+    #print "Assign IP Addresses."
     ipv4 = ns3.Ipv4AddressHelper()
     ipv4.SetBase(ns3.Ipv4Address("10.1.1.0"), ns3.Ipv4Mask("255.255.255.0"))
     ipv4.Assign(terminalDevices)
@@ -91,7 +91,7 @@ def main(argv):
     #
     # Create an OnOff application to send UDP datagrams from node zero to node 1.
     #
-    print "Create Applications."
+    #print "Create Applications."
     port = 9   # Discard port(RFC 863)
 
     onoff = ns3.OnOffHelper("ns3::UdpSocketFactory", 
@@ -142,10 +142,10 @@ def main(argv):
     #
     # Now, do the actual simulation.
     #
-    print "Run Simulation."
+    #print "Run Simulation."
     ns3.Simulator.Run()
     ns3.Simulator.Destroy()
-    print "Done."
+    #print "Done."
 
 
 

examples/tcp-nsc-zoo.cc

@@ -25,7 +25,7 @@
 //
 // - Pcap traces are saved as tcp-nsc-zoo-$n-0.pcap, where $n represents the node number
 // - TCP flows from n0 to n1, n2, n3, from n1 to n0, n2, n3, etc.
-//  Usage (e.g.): ./waf --run 'tcp-nsc-zoo --Nodes=5'
+//  Usage (e.g.): ./waf --run 'tcp-nsc-zoo --nodes=5'
 
 #include <iostream>
 #include <string>
@@ -45,14 +45,23 @@ int main(int argc, char *argv[])
 {
   CsmaHelper csma;
   unsigned int MaxNodes = 4;
+  unsigned int runtime = 3;
 
-  Config::SetDefault ("ns3::OnOffApplication::PacketSize", UintegerValue (4096));
-  Config::SetDefault ("ns3::OnOffApplication::DataRate", StringValue ("1Mb/s"));
+  RandomVariable::UseGlobalSeed (1, 1, 2, 3, 5, 8);
+
+  Config::SetDefault ("ns3::OnOffApplication::PacketSize", UintegerValue (2048));
+  Config::SetDefault ("ns3::OnOffApplication::DataRate", StringValue ("8kbps"));
   CommandLine cmd;
-  // this allows the user to raise the number of nodes using --Nodes=X command-line argument.
-  cmd.AddValue("Nodes", "Number of nodes in the network", MaxNodes);
+  // this allows the user to raise the number of nodes using --nodes=X command-line argument.
+  cmd.AddValue("nodes", "Number of nodes in the network (must be > 1)", MaxNodes);
+  cmd.AddValue("runtime", "How long the applications should send data (default 3 seconds)", runtime);
   cmd.Parse (argc, argv);
 
+  if (MaxNodes < 2)
+    {
+       std::cerr << "--nodes: must be >= 2" << std::endl;
+       return 1;
+    }
   csma.SetChannelAttribute ("DataRate", DataRateValue (DataRate(100 * 1000 * 1000)));
   csma.SetChannelAttribute ("Delay", TimeValue (MicroSeconds (200)));
 
@@ -70,16 +79,24 @@ int main(int argc, char *argv[])
   Config::Set ("/NodeList/1/$ns3::Ns3NscStack<linux2.6.26>/net.ipv4.tcp_sack", StringValue ("0"));
   Config::Set ("/NodeList/1/$ns3::Ns3NscStack<linux2.6.26>/net.ipv4.tcp_timestamps", StringValue ("0"));
   Config::Set ("/NodeList/1/$ns3::Ns3NscStack<linux2.6.26>/net.ipv4.tcp_window_scaling", StringValue ("0"));
-  internetStack.Install (n.Get(2));
-  // the next statement doesn't change anything for the nodes 0, 1, and 2; since they
-  // already have a stack assigned.
-  internetStack.SetNscStack ("liblinux2.6.18.so");
-  // this switches node 3 to NSCs Linux 2.6.18 stack.
-  internetStack.Install (n.Get(3));
-  // and then agains disables sack/timestamps/wscale on node 3.
-  Config::Set ("/NodeList/3/$ns3::Ns3NscStack<linux2.6.18>/net.ipv4.tcp_sack", StringValue ("0"));
-  Config::Set ("/NodeList/3/$ns3::Ns3NscStack<linux2.6.18>/net.ipv4.tcp_timestamps", StringValue ("0"));
-  Config::Set ("/NodeList/3/$ns3::Ns3NscStack<linux2.6.18>/net.ipv4.tcp_window_scaling", StringValue ("0"));
+
+  if (MaxNodes > 2)
+    {
+      internetStack.Install (n.Get(2));
+    }
+
+  if (MaxNodes > 3)
+    {
+      // the next statement doesn't change anything for the nodes 0, 1, and 2; since they
+      // already have a stack assigned.
+      internetStack.SetNscStack ("liblinux2.6.18.so");
+      // this switches node 3 to NSCs Linux 2.6.18 stack.
+      internetStack.Install (n.Get(3));
+      // and then agains disables sack/timestamps/wscale on node 3.
+      Config::Set ("/NodeList/3/$ns3::Ns3NscStack<linux2.6.18>/net.ipv4.tcp_sack", StringValue ("0"));
+      Config::Set ("/NodeList/3/$ns3::Ns3NscStack<linux2.6.18>/net.ipv4.tcp_timestamps", StringValue ("0"));
+      Config::Set ("/NodeList/3/$ns3::Ns3NscStack<linux2.6.18>/net.ipv4.tcp_window_scaling", StringValue ("0"));
+    }
   // the freebsd stack is not yet built by default, so its commented out for now.
   // internetStack.SetNscStack ("libfreebsd5.so");
   for (unsigned int i =4; i < MaxNodes; i++)
@@ -97,7 +114,7 @@ int main(int argc, char *argv[])
   PacketSinkHelper sinkHelper ("ns3::TcpSocketFactory", InetSocketAddress (Ipv4Address::GetAny (), servPort));
   // start a sink client on all nodes
   ApplicationContainer sinkApp = sinkHelper.Install (n);
-  sinkApp.Start (Seconds (1.0));
+  sinkApp.Start (Seconds (0));
   sinkApp.Stop (Seconds (30.0));
 
   // This tells every node on the network to start a flow to all other nodes on the network ...
@@ -116,14 +133,14 @@ int main(int argc, char *argv[])
           clientHelper.SetAttribute 
             ("OffTime", RandomVariableValue (ConstantVariable (0)));
           ApplicationContainer clientApp = clientHelper.Install(n.Get(i));
-          clientApp.Start (Seconds (j + 1.0)); /* delay startup depending on node number */
-          clientApp.Stop (Seconds (j + 10.0));
+          clientApp.Start (Seconds (j)); /* delay startup depending on node number */
+          clientApp.Stop (Seconds (j + runtime));
 	}
     }
 
   CsmaHelper::EnablePcapAll ("tcp-nsc-zoo");
 
-  Simulator::Stop (Seconds(1000));
+  Simulator::Stop (Seconds(100));
   Simulator::Run ();
   Simulator::Destroy ();
 

regression/tests/test-csma-bridge.py

@@ -0,0 +1,16 @@
+#! /usr/bin/env python
+
+"""Generic trace-comparison-type regression test."""
+
+import os
+import sys
+import tracediff
+
+def run(verbose, generate, refDirName):
+    """Execute a test."""
+    if tracediff.env['ENABLE_PYTHON_BINDINGS']:
+        return tracediff.run_test(verbose, generate, refDirName,
+                                  "csma-bridge", pyscript=os.path.join('examples', 'csma-bridge.py'))
+    else:
+        print >> sys.stderr, "Skipping csma-bridge: Python bindings not available."
+        raise NotImplementedError

regression/tests/test-tcp-nsc-lfn.py

@@ -0,0 +1,33 @@
+#! /usr/bin/env python
+
+"""Trace-comparison-type regression test for the Network Simulation Cradle."""
+
+import os
+import shutil
+import sys
+import tracediff
+import platform
+
+
+def run(verbose, generate, refDirName):
+    """Run a Network Simulation Cradle test involving two TCP streams."""
+
+    if not tracediff.env['ENABLE_NSC']:
+        print >>sys.stderr, "Skipping tcp-nsc-lfn: NSC not available."
+        raise NotImplementedError
+
+    testName = "tcp-nsc-lfn"
+    arguments = ["--ns3::OnOffApplication::DataRate=40000", "--runtime=20"]
+    platform_bits = platform.architecture()[0]
+    
+    if platform_bits == "64bit":
+        traceDirName = testName + "_64bit.ref"
+    elif platform_bits == "32bit":
+        traceDirName = testName + "_32bit.ref"
+    else:
+        # Something unexpected. How should we signal an error here? Rasing a
+        # string might not be the best idea?
+        raise "Unknown architecture, not 64 or 32 bit?"
+
+    return tracediff.run_test(verbose, generate, refDirName,
+        testName, arguments=arguments, refTestName=traceDirName)

regression/tests/test-udp-echo.py

@@ -8,5 +8,5 @@ import tracediff
 
 def run(verbose, generate, refDirName):
     """Execute a test."""
-
+    #print tracediff.env
     return tracediff.run_test(verbose, generate, refDirName, "udp-echo")

regression/tests/test-wifi-wired-bridging.py

@@ -9,4 +9,4 @@ import tracediff
 def run(verbose, generate, refDirName):
     """Execute a test."""
 
-    return tracediff.run_test(verbose, generate, refDirName, "wifi-wired-bridging", "--SendIp=0")
+    return tracediff.run_test(verbose, generate, refDirName, "wifi-wired-bridging", ["--SendIp=0"])

samples/main-propagation-loss.cc

@@ -51,8 +51,8 @@ PrintOne (double minTxpower, double maxTxpower, double stepTxpower, double min,
 int main (int argc, char *argv[])
 {
 
-  Config::SetGlobal ("LogDistancePropagationLossModel::ReferenceDistance", StringValue ("1.0"));
-  Config::SetGlobal ("LogDistancePropagationLossModel::Exponent", StringValue ("4"));
+  Config::SetDefault ("ns3::LogDistancePropagationLossModel::ReferenceDistance", StringValue ("1.0"));
+  Config::SetDefault ("ns3::LogDistancePropagationLossModel::Exponent", StringValue ("4"));
 
   PrintOne (-10, 20, 5, 0, 10000, 2);
 

src/contrib/contrib.h

@@ -1,5 +1,18 @@
 /**
  * \addtogroup contrib Contrib
  *
+ * The src/contrib directory is for contributed code that is being maintained
+ * by the authors, but is not yet part of the main tree.
+ * For instance, the developers may be requesting feedback on whether anyone
+ * thinks the contributed model is generally useful to maintain in the main
+ * tree, or may want feedback on the API or features.  If you find the
+ * code in this directory useful, please let the ns-3 developers know.
+ * Code may migrate from this directory to the main tree, or may be 
+ * removed due to lack of interest, for a later release.
+ *
  * - A class to generate graphs with gnuplot: ns3::Gnuplot and ns3::GnuplotDataset
+ * - A class to hold configuration data:  ns3::ConfigStore and methods to allow the configuration to be read from and written to a file
+ * - A graphical editor of the config store:  ns3::GtkConfigStore
+ * - An object that garbage collects events:  ns3::EventGarbageCollector
+ * - An object that provides "quick and dirty" delay and jitter estimation:  ns3::DelayJitterEstimation
  */

src/contrib/gtk-config-store.h

@@ -3,6 +3,9 @@
 
 namespace ns3 {
 
+/**
+ * \brief A class that provides a GTK-based front end to ns3::ConfigStore 
+ */
 class GtkConfigStore
 {
 public:

src/core/random-variable.cc

@@ -196,7 +196,12 @@ void RandomVariableBase::GetRandomSeeds(uint32_t seeds[6])
         {
           for (int i = 0; i < 6; ++i)
             {
-              read(RandomVariableBase::devRandom, &seeds[i], sizeof(seeds[i]));
+              ssize_t bytes_read = read (RandomVariableBase::devRandom,
+                                         &seeds[i], sizeof (seeds[i]));
+              if (bytes_read != sizeof (seeds[i]))
+                {
+                  NS_FATAL_ERROR ("Read from /dev/random failed");
+                }
             }
           if (RngStream::CheckSeed(seeds)) break; // Got a valid one
         }

src/devices/csma/csma-net-device.cc

@@ -128,58 +128,64 @@ CsmaNetDevice::DoDispose ()
   NetDevice::DoDispose ();
 }
 
-  uint16_t
-CsmaNetDevice::MtuFromFrameSize (uint16_t frameSize)
+  uint32_t
+CsmaNetDevice::MtuFromFrameSize (uint32_t frameSize)
 {
   NS_LOG_FUNCTION (frameSize);
 
+  NS_ASSERT_MSG (frameSize <= std::numeric_limits<uint16_t>::max (), 
+                 "CsmaNetDevice::MtuFromFrameSize(): Frame size should be derived from 16-bit quantity: " << frameSize);
+
+  uint32_t newSize;
+
   switch (m_encapMode) 
     {
     case DIX:
-      return frameSize - ETHERNET_OVERHEAD;
+      newSize = frameSize - ETHERNET_OVERHEAD;
+      break;
     case LLC: 
       {
         LlcSnapHeader llc;
 
         NS_ASSERT_MSG ((uint32_t)(frameSize - ETHERNET_OVERHEAD) >= llc.GetSerializedSize (), 
                        "CsmaNetDevice::MtuFromFrameSize(): Given frame size too small to support LLC mode");
-        return frameSize - ETHERNET_OVERHEAD - llc.GetSerializedSize ();
+        newSize = frameSize - ETHERNET_OVERHEAD - llc.GetSerializedSize ();
       }
+      break;
     case ILLEGAL:
     default:
       NS_FATAL_ERROR ("CsmaNetDevice::MtuFromFrameSize(): Unknown packet encapsulation mode");
       return 0;
     }
-  //
-  // Prevent compiler from complaining
-  //
-  return 0;
+
+  return newSize;
 }
   
-  uint16_t
-CsmaNetDevice::FrameSizeFromMtu (uint16_t mtu)
+  uint32_t
+CsmaNetDevice::FrameSizeFromMtu (uint32_t mtu)
 {
   NS_LOG_FUNCTION (mtu);
 
+  uint32_t newSize;
+
   switch (m_encapMode) 
     {
     case DIX:
-      return mtu + ETHERNET_OVERHEAD;
+      newSize = mtu + ETHERNET_OVERHEAD;
+      break;
     case LLC: 
       {
         LlcSnapHeader llc;
-        return mtu + ETHERNET_OVERHEAD + llc.GetSerializedSize ();
+        newSize = mtu + ETHERNET_OVERHEAD + llc.GetSerializedSize ();
       }
+      break;
     case ILLEGAL:
     default:
       NS_FATAL_ERROR ("CsmaNetDevice::FrameSizeFromMtu(): Unknown packet encapsulation mode");
       return 0;
     }
 
-  //
-  // Prevent compiler from complaining
-  //
-  return 0;
+  return newSize;
 }
 
   void 
@@ -207,7 +213,15 @@ CsmaNetDevice::SetMtu (uint16_t mtu)
 {
   NS_LOG_FUNCTION (mtu);
 
-  m_frameSize = FrameSizeFromMtu (mtu);
+  uint32_t newFrameSize = FrameSizeFromMtu (mtu);
+
+  if (newFrameSize > std::numeric_limits<uint16_t>::max ())
+    {
+      NS_LOG_WARN ("CsmaNetDevice::SetMtu(): Frame size overflow, MTU not set.");
+      return false;
+    }
+
+  m_frameSize = newFrameSize;
   m_mtu = mtu;
 
   NS_LOG_LOGIC ("m_encapMode = " << m_encapMode);

src/devices/csma/csma-net-device.h

@@ -419,6 +419,7 @@ protected:
    * respect the packet type
    *
    * \param p Packet to which header should be added
+   * \param source MAC source address from which packet should be sent
    * \param dest MAC destination address to which packet should be sent
    * \param protocolNumber In some protocols, identifies the type of
    * payload contained in this packet.
@@ -461,13 +462,13 @@ private:
    * Calculate the value for the MTU that would result from 
    * setting the frame size to the given value.
    */
-  uint16_t MtuFromFrameSize (uint16_t frameSize);
+  uint32_t MtuFromFrameSize (uint32_t frameSize);
 
   /**
    * Calculate the value for the frame size that would be required
    * to be able to set the MTU to the given value.
    */
-  uint16_t FrameSizeFromMtu (uint16_t mtu);
+  uint32_t FrameSizeFromMtu (uint32_t mtu);
 
   /**
    * Start Sending a Packet Down the Wire.

src/devices/point-to-point/point-to-point-net-device.cc

@@ -504,20 +504,21 @@ PointToPointNetDevice::GetRemote (void) const
   return Address ();
 }
 
-  uint16_t
-PointToPointNetDevice::MtuFromFrameSize (uint16_t frameSize)
+  uint32_t
+PointToPointNetDevice::MtuFromFrameSize (uint32_t frameSize)
 {
   NS_LOG_FUNCTION (frameSize);
-
+  NS_ASSERT_MSG (frameSize <= std::numeric_limits<uint16_t>::max (), 
+                 "PointToPointNetDevice::MtuFromFrameSize(): Frame size should be derived from 16-bit quantity: " << 
+                 frameSize);
   PppHeader ppp;
-
   NS_ASSERT_MSG ((uint32_t)frameSize >= ppp.GetSerializedSize (), 
                  "PointToPointNetDevice::MtuFromFrameSize(): Given frame size too small to support PPP");
   return frameSize - ppp.GetSerializedSize ();
 }
   
-  uint16_t
-PointToPointNetDevice::FrameSizeFromMtu (uint16_t mtu)
+  uint32_t
+PointToPointNetDevice::FrameSizeFromMtu (uint32_t mtu)
 {
   NS_LOG_FUNCTION (mtu);
 
@@ -548,7 +549,15 @@ PointToPointNetDevice::SetMtu (uint16_t mtu)
 {
   NS_LOG_FUNCTION (mtu);
 
-  m_frameSize = FrameSizeFromMtu (mtu);
+  uint32_t newFrameSize = FrameSizeFromMtu (mtu);
+
+  if (newFrameSize > std::numeric_limits<uint16_t>::max ())
+    {
+      NS_LOG_WARN ("PointToPointNetDevice::SetMtu(): Frame size overflow, MTU not set.");
+      return false;
+    }
+
+  m_frameSize = newFrameSize;
   m_mtu = mtu;
 
   NS_LOG_LOGIC ("m_frameSize = " << m_frameSize);

src/devices/point-to-point/point-to-point-net-device.h

@@ -286,13 +286,13 @@ private:
    * Calculate the value for the MTU that would result from 
    * setting the frame size to the given value.
    */
-  uint16_t MtuFromFrameSize (uint16_t frameSize);
+  uint32_t MtuFromFrameSize (uint32_t frameSize);
 
   /**
    * Calculate the value for the frame size that would be required
    * to be able to set the MTU to the given value.
    */
-  uint16_t FrameSizeFromMtu (uint16_t mtu);
+  uint32_t FrameSizeFromMtu (uint32_t mtu);
 
   /**
    * \returns the address of the remote device connected to this device

src/devices/wifi/propagation-loss-model.cc

@@ -277,12 +277,10 @@ LogDistancePropagationLossModel::GetLoss (Ptr<MobilityModel> a,
    *      
    * rx = rx0(tx) - 10 * n * log (d/d0)
    */
-  static Ptr<StaticMobilityModel> zero = 
-    CreateObject<StaticMobilityModel> ("Position", 
-                                       VectorValue (Vector (0.0, 0.0, 0.0)));
-  static Ptr<StaticMobilityModel> reference = 
-    CreateObject<StaticMobilityModel> ("Position", 
-                                       VectorValue (Vector (m_referenceDistance, 0.0, 0.0)));
+  static Ptr<StaticMobilityModel> zero = CreateObject<StaticMobilityModel> ();
+  static Ptr<StaticMobilityModel> reference = CreateObject<StaticMobilityModel> ();
+  zero->SetPosition (Vector (0.0, 0.0, 0.0));
+  reference->SetPosition (Vector (m_referenceDistance, 0.0, 0.0));
   double ref = m_reference->GetLoss (zero, reference);
   double pathLossDb = 10 * m_exponent * log10 (distance / m_referenceDistance);
   double rxc = ref - pathLossDb;

src/devices/wifi/wifi-mac.h

@@ -132,6 +132,18 @@ public:
 
 private:
   friend class WifiNetDevice;
+  /**
+   * \param packet the packet to send.
+   * \param to the address to which the packet should be sent.
+   * \param from the address from which the packet should be sent.
+   *
+   * The packet should be enqueued in a tx queue, and should be
+   * dequeued as soon as the DCF function determines that
+   * access it granted to this MAC.  The extra parameter "from" allows
+   * this device to operate in a bridged mode, forwarding received
+   * frames without altering the source addresss.
+   */
+  virtual void Enqueue (Ptr<const Packet> packet, Mac48Address to, Mac48Address from) = 0;
   /**
    * \param packet the packet to send.
    * \param to the address to which the packet should be sent.
@@ -140,7 +152,6 @@ private:
    * dequeued as soon as the DCF function determines that
    * access it granted to this MAC.
    */
-  virtual void Enqueue (Ptr<const Packet> packet, Mac48Address to, Mac48Address from) = 0;
   virtual void Enqueue (Ptr<const Packet> packet, Mac48Address to) = 0;
   virtual bool SupportsSendFrom (void) const = 0;
   /**

src/internet-stack/arp-cache.h

@@ -40,6 +40,7 @@ class NetDevice;
 class Ipv4Interface;
 
 /**
+ * \ingroup arp
  * \brief An ARP cache
  *
  * A cached lookup table for translating layer 3 addresses to layer 2.
@@ -155,7 +156,7 @@ public:
      */
     Ipv4Address GetIpv4Address (void) const;
     /**
-     * \param The Ipv4Address for this entry
+     * \param destination The Ipv4Address for this entry
      */
     void SetIpv4Address (Ipv4Address destination);
     /**

src/internet-stack/arp-header.h

@@ -28,6 +28,7 @@
 
 namespace ns3 {
 /**
+ * \ingroup arp
  * \brief The packet header for an ARP packet
  */
 class ArpHeader : public Header 

src/internet-stack/arp-ipv4-interface.h

@@ -30,6 +30,7 @@ class Node;
 class ArpCache;
 
 /**
+ * \ingroup arp
  * \brief an Ipv4 Interface which uses ARP
  *
  * If you need to use ARP on top of a specific NetDevice, you

src/internet-stack/arp-l3-protocol.h

@@ -36,6 +36,13 @@ class Node;
 class Packet;
 
 /**
+ * \ingroup internetStack
+ * \defgroup arp Arp
+ *
+ * This is an overview of Arp capabilities (write me).
+ */
+/**
+ * \ingroup arp
  * \brief An implementation of the ARP protocol
  */
 class ArpL3Protocol : public Object

src/internet-stack/nsc-tcp-l4-protocol.h

@@ -38,7 +38,9 @@ class Node;
 class Socket;
 class TcpHeader;
 /**
- * \brief Nsc wrapper glue.
+ * \ingroup nsctcp
+ * 
+ * \brief Nsc wrapper glue, to interface with the Ipv4 protocol underneath.
  */
 class NscTcpL4Protocol : public Ipv4L4Protocol, ISendCallback, IInterruptCallback {
 public:

src/internet-stack/nsc-tcp-socket-factory-impl.h

@@ -23,6 +23,24 @@ namespace ns3 {
 
 class NscTcpL4Protocol;
 
+/**
+ * \ingroup internetStack
+ * \defgroup nsctcp NscTcp
+ *
+ * An alternate implementation of TCP for ns-3 is provided by the
+ * Network Simulation Cradle (NSC) project. NSC is a separately linked
+ * library that provides ported TCP stacks from popular operating systems
+ * such as Linux and FreeBSD.  Glue code such as the ns-3 NSC code
+ * allows users to delegate Internet stack processing to the logic
+ * from these operating systems.  This allows a user to reproduce
+ * with high fidelity the behavior of a real TCP stack.
+ */
+
+/**
+ * \ingroup nsctcp
+ *
+ * \brief socket factory implementation for creating instances of NSC TCP
+ */
 class NscTcpSocketFactoryImpl : public TcpSocketFactory
 {
 public:

src/internet-stack/nsc-tcp-socket-impl.h

@@ -40,6 +40,16 @@ class Packet;
 class NscTcpL4Protocol;
 class TcpHeader;
 
+/**
+ * \ingroup socket
+ * \ingroup nsctcp
+ *
+ * \brief Socket logic for the NSC TCP sockets.  
+ * 
+ * Most of the TCP internal
+ * logic is handled by the NSC tcp library itself; this class maps ns3::Socket
+ * calls to the NSC TCP library.
+ */
 class NscTcpSocketImpl : public TcpSocket
 {
 public:

src/internet-stack/pending-data.h

@@ -33,6 +33,11 @@ namespace ns3
 {
 class Packet;
 
+/**
+ * \ingroup tcp
+ *
+ * \brief class for managing I/O between applications and TCP
+ */
 class PendingData {
 public:
   PendingData ();

src/internet-stack/rtt-estimator.h

@@ -21,7 +21,6 @@
 // Georgia Tech Network Simulator - Round Trip Time Estimation Class
 // George F. Riley.  Georgia Tech, Spring 2002
 
-// Implements several variations of round trip time estimators
 
 #ifndef __rtt_estimator_h__
 #define __rtt_estimator_h__
@@ -33,6 +32,11 @@
 
 namespace ns3 {
 
+/**
+ * \ingroup tcp
+ *
+ * \brief Implements several variations of round trip time estimators
+ */
 class RttHistory {
 public:
   RttHistory (SequenceNumber s, uint32_t c, Time t);

src/internet-stack/sequence-number.h

@@ -22,8 +22,6 @@
 // Georgia Tech Network Simulator - Manage 32 bit unsigned sequence numbers
 // George F. Riley.  Georgia Tech, Spring 2002
 
-// Class to manage arithmetic operations on sequence numbers (mod 2^32)
-
 #ifndef __seq_h__
 #define __seq_h__
 
@@ -31,6 +29,11 @@
 
 #define MAX_SEQ ((uint32_t)0xffffffff)
 
+/**
+ * \ingroup tcp
+ *
+ * \brief Class to manage arithmetic operations on sequence numbers (mod 2^32)
+ */
 class SequenceNumber {
 public:
   SequenceNumber () : seq(0) { }

src/internet-stack/tcp-header.h

@@ -31,6 +31,7 @@
 namespace ns3 {
 
 /**
+ * \ingroup tcp
  * \brief Header for the Transmission Control Protocol
  *
  * This class has fields corresponding to those in a network TCP header

src/internet-stack/tcp-l4-protocol.h

@@ -41,6 +41,7 @@ class Socket;
 class TcpHeader;
 
 /**
+ * \ingroup tcp
  * \brief A layer between the sockets interface and IP
  * 
  * This class allocates "endpoint" objects (ns3::Ipv4EndPoint) for TCP,

src/internet-stack/tcp-socket-factory-impl.h

@@ -28,12 +28,8 @@ namespace ns3 {
 class TcpL4Protocol;
 
 /**
- * \ingroup internetNode
- * \defgroup Tcp Tcp
- */
-/**
- * \ingroup Tcp
- * \section Tcp Overview
+ * \ingroup internetStack
+ * \defgroup tcp Tcp
  *
  * The TCP code in ns3's internet stack is ported from the  
  * <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/">
@@ -43,6 +39,13 @@ class TcpL4Protocol;
  * This class serves to create sockets of the TcpSocketImpl
  * type.  That is, it creates sockets which use the GTNetS Tahoe code.
  */
+
+/**
+ * \ingroup tcp
+ *
+ * \brief socket factory implementation for native ns-3 TCP
+ *
+ */
 class TcpSocketFactoryImpl : public TcpSocketFactory
 {
 public:

src/internet-stack/tcp-socket-impl.h

@@ -44,6 +44,7 @@ class TcpHeader;
 
 /**
  * \ingroup socket
+ * \ingroup tcp
  *
  * \brief An implementation of a stream socket using TCP.
  *

src/internet-stack/udp-header.h

@@ -28,6 +28,7 @@
 
 namespace ns3 {
 /**
+ * \ingroup udp
  * \brief Packet header for UDP packets
  *
  * This class has fields corresponding to those in a network UDP header

src/internet-stack/udp-l4-protocol.h

@@ -34,6 +34,7 @@ namespace ns3 {
 class Node;
 class Socket;
 /**
+ * \ingroup udp
  * \brief Implementation of the UDP protocol
  */
 class UdpL4Protocol : public Ipv4L4Protocol {

src/internet-stack/udp-socket-factory-impl.h

@@ -28,6 +28,23 @@ namespace ns3 {
 class UdpL4Protocol;
 
 /**
+ * \ingroup internetStack
+ * \defgroup udp Udp
+ *
+ * This  is  an  implementation of the User Datagram Protocol described in
+ * RFC 768.  It implements a connectionless,  unreliable  datagram  packet
+ * service.   Packets  may  be reordered or duplicated before they arrive.
+ * UDP generates and checks checksums to catch transmission errors.
+ *
+ * The following options are not presently part of this implementation:
+ * UDP_CORK, MSG_DONTROUTE, path MTU discovery control (e.g. 
+ * IP_MTU_DISCOVER).  MTU handling is also weak in ns-3 for the moment;
+ * it is best to send datagrams that do not exceed 1500 byte MTU (e.g.
+ * 1472 byte UDP datagrams)
+ */
+
+/**
+ * \ingroup udp
  * \brief Object to create UDP socket instances 
  * \internal
  *

src/internet-stack/udp-socket-impl.h

@@ -37,6 +37,7 @@ class Packet;
 class UdpL4Protocol;
 
 /**
+ * \ingroup udp
  * \brief A sockets interface to UDP
  * 
  * This class subclasses ns3::UdpSocket, and provides a socket interface

src/internet-stack/wscript

@@ -54,6 +54,8 @@ def nsc_fetch():
         nsc_update()
 
 def configure(conf):
+    conf.env['ENABLE_NSC'] = False
+
     # checks for flex and bison, which is needed to build NSCs globaliser
     def check_nsc_buildutils():
         import flex
@@ -82,6 +84,7 @@ def configure(conf):
         e.define = 'HAVE_DL'
         e.uselib = 'DL'
         e.run()
+        conf.env['ENABLE_NSC'] = True
         ok = True
     conf.check_message('NSC supported architecture', arch, ok)
     conf.report_optional_feature("nsc", "Network Simulation Cradle", ok,

src/node/address.h

@@ -66,11 +66,11 @@ namespace ns3 {
 class Address 
 {
 public:
+  /**
+   * The maximum size of a byte buffer which
+   * can be stored in an Address instance.
+   */
   enum MaxSize_e {
-    /**
-     * The maximum size of a byte buffer which
-     * can be stored in an Address instance.
-     */
     MAX_SIZE = 30
   };
 

src/node/net-device.h

@@ -312,7 +312,7 @@ public:
   virtual void SetPromiscReceiveCallback (PromiscReceiveCallback cb) = 0;
 
   /**
-   * \return true if this interface supports a promiscuous mode, false otherwise.
+   * \return true if this interface supports a bridging mode, false otherwise.
    */
   virtual bool SupportsSendFrom (void) const = 0;
 

wscript

@@ -272,9 +272,12 @@ def configure(conf):
         conf.env['NS3_ENABLED_MODULES'] = ['ns3-'+mod for mod in
                                            Params.g_options.enable_modules.split(',')]
 
-    ## we cannot run regression tests without diff
+    # we cannot run regression tests without diff
     conf.find_program('diff', var='DIFF')
 
+    # we cannot pull regression traces without mercurial
+    conf.find_program('hg', var='MERCURIAL')
+
     # Write a summary of optional features status
     print "---- Summary of optional NS-3 features:"
     for (name, caption, was_enabled, reason_not_enabled) in conf.env['NS3_OPTIONAL_FEATURES']:
@@ -815,11 +818,35 @@ def dev_null():
 class Regression(object):
     def __init__(self, testdir):
         self.testdir = testdir
-        env = Params.g_build.env_of_name('default')
-        self.diff = env['DIFF']
+        self.env = Params.g_build.env_of_name('default')
 
-    def run_test(self, verbose, generate, refDirName, testName, *arguments):
-        refTestDirName = os.path.join(refDirName, (testName + ".ref"))
+    def run_test(self, verbose, generate, refDirName, testName, arguments=[], pyscript=None, refTestName=None):
+        """
+        @param verbose: enable verbose execution
+
+        @param generate: generate new traces instead of comparing with the reference
+
+        @param refDirName: name of the base directory containing reference traces
+
+        @param testName: name of the test
+
+        @arguments: list of extra parameters to pass to the program to be tested
+
+        @pyscript: if not None, the test is written in Python and this
+        parameter contains the path to the python script, relative to
+        the project root dir
+
+        @param refTestName: if not None, this is the name of the directory under refDirName
+        that contains the reference traces. Otherwise "refDirname/testName + .ref" is used.
+
+        """
+        if not isinstance(arguments, list):
+            raise TypeError
+        
+        if refTestName is None:
+            refTestDirName = os.path.join(refDirName, (testName + ".ref"))
+        else:
+            refTestDirName = os.path.join(refDirName, refTestName)
 
         if not os.path.exists(refDirName):
             print"No reference trace repository"
@@ -830,17 +857,25 @@ class Regression(object):
                 print "creating new " + refTestDirName
                 os.mkdir(refTestDirName)
 
-            Params.g_options.cwd_launch = refTestDirName
-            tmpl = "%s"
-            for arg in arguments:
-                tmpl = tmpl + " " + arg
-            run_program(testName, tmpl)
-
+            if pyscript is None:
+                Params.g_options.cwd_launch = refTestDirName
+                tmpl = "%s"
+                for arg in arguments:
+                    tmpl = tmpl + " " + arg
+                run_program(testName, tmpl)
+            else:
+                argv = [self.env['PYTHON'], os.path.join('..', '..', '..', *os.path.split(pyscript))] + arguments
+                before = os.getcwd()
+                os.chdir(refTestDirName)
+                try:
+                    _run_argv(argv)
+                finally:
+                    os.chdir(before)
             print "Remember to commit " + refTestDirName
             return 0
         else:
             if not os.path.exists(refTestDirName):
-                print "Cannot locate reference traces"
+                print "Cannot locate reference traces in " + refTestDirName
                 return 1
 
             shutil.rmtree("traces");
@@ -848,20 +883,30 @@ class Regression(object):
 
             #os.system("./waf --cwd regression/traces --run " +
             #  testName + " > /dev/null 2>&1")
-            Params.g_options.cwd_launch = "traces"
-            run_program(testName, command_template=get_command_template(*arguments))
+
+            if pyscript is None:
+                Params.g_options.cwd_launch = "traces"
+                run_program(testName, command_template=get_command_template(*arguments))
+            else:
+                argv = [self.env['PYTHON'], os.path.join('..', '..', *os.path.split(pyscript))] + arguments
+                before = os.getcwd()
+                os.chdir("traces")
+                try:
+                    _run_argv(argv)
+                finally:
+                    os.chdir(before)
 
             if verbose:
                 #diffCmd = "diff traces " + refTestDirName + " | head"
-                diffCmd = subprocess.Popen([self.diff, "traces", refTestDirName],
-                                           stdout=dev_null())
+                diffCmd = subprocess.Popen([self.env['DIFF'], "traces", refTestDirName],
+                                           stdout=subprocess.PIPE)
                 headCmd = subprocess.Popen("head", stdin=diffCmd.stdout)
                 rc2 = headCmd.wait()
                 diffCmd.stdout.close()
                 rc1 = diffCmd.wait()
                 rc = rc1 or rc2
             else:
-                rc = subprocess.Popen([self.diff, "traces", refTestDirName], stdout=dev_null()).wait()
+                rc = subprocess.Popen([self.env['DIFF'], "traces", refTestDirName], stdout=dev_null()).wait()
             if rc:
                 print "----------"
                 print "Traces differ in test: test-" + testName
@@ -907,8 +952,8 @@ def run_regression():
 
     print "========== Running Regression Tests =========="
     dir_name = APPNAME + '-' + VERSION + REGRESSION_SUFFIX
-
-    if subprocess.Popen(["hg", "version"], stdout=dev_null(), stderr=dev_null()).wait() == 0:
+    env = Params.g_build.env_of_name('default')
+    if env['MERCURIAL']:
         print "Synchronizing reference traces using Mercurial."
         if not os.path.exists(dir_name):
             print "Cloning " + REGRESSION_TRACES_REPO + dir_name + " from repo."
@@ -927,28 +972,32 @@ def run_regression():
             if result:
                 Params.fatal("Synchronizing reference traces using Mercurial failed.")
     else:
-        traceball = dir_name + TRACEBALL_SUFFIX
-        print "Retrieving " + traceball + " from web."
-        urllib.urlretrieve(REGRESSION_TRACES_URL + traceball, traceball)
-        os.system("tar -xjf %s -C .." % (traceball))
-    print "Done."
+        if not os.path.exists(dir_name):
+            traceball = dir_name + TRACEBALL_SUFFIX
+            print "Retrieving " + traceball + " from web."
+            urllib.urlretrieve(REGRESSION_TRACES_URL + traceball, traceball)
+            os.system("tar -xjf %s -C .." % (traceball))
+            print "Done."
 
     if not os.path.exists(dir_name):
-        print "Reference traces directory does not exist"
+        print "Reference traces directory (%s) does not exist" % dir_name
         return 3
     
     bad = []
 
     for test in tests:
-        result = _run_regression_test(test)
-        if result == 0:
-            if Params.g_options.regression_generate:
-                print "GENERATE " + test
+        try:
+            result = _run_regression_test(test)
+            if result == 0:
+                if Params.g_options.regression_generate:
+                    print "GENERATE " + test
+                else:
+                    print "PASS " + test
             else:
-                print "PASS " + test
-        else:
-            bad.append(test)
-            print "FAIL " + test
+                bad.append(test)
+                print "FAIL " + test
+        except NotImplementedError:
+                print "SKIP " + test            
 
     return len(bad) > 0