freshen tutorial

- 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,5 @@ 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

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
 -------------------------
@@ -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.

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/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-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/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,10 +818,28 @@ 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):
+    def run_test(self, verbose, generate, refDirName, testName, arguments=[], pyscript=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
+
+        """
+        if not isinstance(arguments, list):
+            raise TypeError
+        
         refTestDirName = os.path.join(refDirName, (testName + ".ref"))
 
         if not os.path.exists(refDirName):
@@ -830,17 +851,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 +877,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 +946,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 +966,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