merge with HEAD

2008-09-14 11:40:10 -07:00
parent 0c7ed36240 1994268a9b
commit 77e3a780bb
24 changed files with 168 additions and 73 deletions
--- a/CHANGES.html
+++ b/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>
--- a/53
+++ b/53
@@ -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,28 +56,13 @@ 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
@@ -84,11 +72,8 @@ ns-3 is known to fail on the following platforms:
 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.
--- a/doc/build.txt
+++ b/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:
--- a/doc/tutorial/introduction.texi
+++ b/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
--- a/src/contrib/contrib.h
+++ b/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
 */
--- a/src/contrib/gtk-config-store.h
+++ b/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:
--- a/src/internet-stack/arp-cache.h
+++ b/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.
--- a/src/internet-stack/arp-header.h
+++ b/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 
--- a/src/internet-stack/arp-ipv4-interface.h
+++ b/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
--- a/src/internet-stack/arp-l3-protocol.h
+++ b/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
--- a/src/internet-stack/nsc-tcp-l4-protocol.h
+++ b/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:
--- a/src/internet-stack/nsc-tcp-socket-factory-impl.h
+++ b/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:
--- a/src/internet-stack/nsc-tcp-socket-impl.h
+++ b/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:
--- a/src/internet-stack/pending-data.h
+++ b/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 ();
--- a/src/internet-stack/rtt-estimator.h
+++ b/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);
--- a/src/internet-stack/sequence-number.h
+++ b/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) { }
--- a/src/internet-stack/tcp-header.h
+++ b/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
--- a/src/internet-stack/tcp-l4-protocol.h
+++ b/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,
--- a/src/internet-stack/tcp-socket-factory-impl.h
+++ b/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:
--- a/src/internet-stack/tcp-socket-impl.h
+++ b/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.
 *
--- a/src/internet-stack/udp-header.h
+++ b/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
--- a/src/internet-stack/udp-l4-protocol.h
+++ b/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 {
--- a/src/internet-stack/udp-socket-factory-impl.h
+++ b/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
 *
--- a/src/internet-stack/udp-socket-impl.h
+++ b/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