From 1e1a5caeb2b0555080452f172cba8fa50075046c Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Thu, 11 Sep 2008 08:17:37 -0700 Subject: [PATCH 1/6] fix formatting --- CHANGES.html | 25 ++++++++----------------- 1 file changed, 8 insertions(+), 17 deletions(-) diff --git a/CHANGES.html b/CHANGES.html index 7d4b26b6d..38326fe84 100644 --- a/CHANGES.html +++ b/CHANGES.html @@ -47,6 +47,7 @@ us a note on ns-developers mailing list.

changes from ns-3.1 to ns-3.2

new API:

+ -
  • 26-08-2008; changeset @@ -68,11 +68,11 @@ Add threading and synchronization primitives. Enabling technology for multithreaded simulator implementation.
    • - +

    new API in existing classes:

    - +

    changes to existing API:

    + - - - -
  • 21-07-2008; changeset
    • - +

    changed behavior:

     -
  • 07-09-2008; changeset 7afa66c2b291
    • @@ -286,7 +278,6 @@ addressed by this changeset. See more. -
  • 28-07-2008; changeset 6f68f1044df1 @@ -298,8 +289,8 @@ hold time == refresh time was never intentional, as it leads to instability in neighbor detection.
    • - + From e054045b37dab812f62bd2c1ac337a7b8ceeb169 Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Thu, 11 Sep 2008 08:18:04 -0700 Subject: [PATCH 2/6] some release notes edits --- RELEASE_NOTES | 53 ++++++++++++++++++--------------------------------- 1 file changed, 19 insertions(+), 34 deletions(-) diff --git a/RELEASE_NOTES b/RELEASE_NOTES index 5d2a78b08..a38e7f82c 100644 --- a/RELEASE_NOTES +++ b/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,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 @@ -82,11 +70,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. From c46f02e9c848c16ac5d10c4d96e9ccd9ca542a7c Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Thu, 11 Sep 2008 08:45:00 -0700 Subject: [PATCH 3/6] add reference to wiki page --- doc/build.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/build.txt b/doc/build.txt index 95bc068e1..090b83408 100644 --- 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: From a70b07289ee384f8a9b4b039c83d0a7973476123 Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Thu, 11 Sep 2008 08:46:29 -0700 Subject: [PATCH 4/6] updates to the tutorial introduction --- doc/tutorial/introduction.texi | 44 +++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 11 deletions(-) diff --git a/doc/tutorial/introduction.texi b/doc/tutorial/introduction.texi index 0b4724061..004f3dd4c 100644 --- 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 From 6f3dc648ed3f0eb25c18f5131a4f445c23a520ef Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Fri, 12 Sep 2008 11:34:25 -0700 Subject: [PATCH 5/6] doxygen for src/contrib --- src/contrib/contrib.h | 13 +++++++++++++ src/contrib/gtk-config-store.h | 3 +++ 2 files changed, 16 insertions(+) diff --git a/src/contrib/contrib.h b/src/contrib/contrib.h index aec8ba6a2..127e09834 100644 --- 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 */ diff --git a/src/contrib/gtk-config-store.h b/src/contrib/gtk-config-store.h index c1a16408a..9b7cf7bbf 100644 --- 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: From 5d9c714c1ee7442ec803a6f6a50afcd027350183 Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Fri, 12 Sep 2008 16:12:58 -0700 Subject: [PATCH 6/6] Doxygen for internet-stack --- src/internet-stack/arp-cache.h | 1 + src/internet-stack/arp-header.h | 1 + src/internet-stack/arp-ipv4-interface.h | 1 + src/internet-stack/arp-l3-protocol.h | 7 +++++++ src/internet-stack/nsc-tcp-l4-protocol.h | 4 +++- .../nsc-tcp-socket-factory-impl.h | 18 ++++++++++++++++++ src/internet-stack/nsc-tcp-socket-impl.h | 10 ++++++++++ src/internet-stack/pending-data.h | 5 +++++ src/internet-stack/rtt-estimator.h | 6 +++++- src/internet-stack/sequence-number.h | 7 +++++-- src/internet-stack/tcp-header.h | 1 + src/internet-stack/tcp-l4-protocol.h | 1 + src/internet-stack/tcp-socket-factory-impl.h | 15 +++++++++------ src/internet-stack/tcp-socket-impl.h | 1 + src/internet-stack/udp-header.h | 1 + src/internet-stack/udp-l4-protocol.h | 1 + src/internet-stack/udp-socket-factory-impl.h | 17 +++++++++++++++++ src/internet-stack/udp-socket-impl.h | 1 + 18 files changed, 88 insertions(+), 10 deletions(-) diff --git a/src/internet-stack/arp-cache.h b/src/internet-stack/arp-cache.h index 1a27ff4f7..b143b4e0a 100644 --- 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. diff --git a/src/internet-stack/arp-header.h b/src/internet-stack/arp-header.h index cb6167d67..27a8eabca 100644 --- 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 diff --git a/src/internet-stack/arp-ipv4-interface.h b/src/internet-stack/arp-ipv4-interface.h index 2c5300e36..733e3b8ae 100644 --- 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 diff --git a/src/internet-stack/arp-l3-protocol.h b/src/internet-stack/arp-l3-protocol.h index 289e2296f..9b46d71b6 100644 --- 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 diff --git a/src/internet-stack/nsc-tcp-l4-protocol.h b/src/internet-stack/nsc-tcp-l4-protocol.h index b79250985..73c2d7da7 100644 --- 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: diff --git a/src/internet-stack/nsc-tcp-socket-factory-impl.h b/src/internet-stack/nsc-tcp-socket-factory-impl.h index 76ad02137..f64b074e7 100644 --- 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: diff --git a/src/internet-stack/nsc-tcp-socket-impl.h b/src/internet-stack/nsc-tcp-socket-impl.h index d3cb42a55..61689f88a 100644 --- 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: diff --git a/src/internet-stack/pending-data.h b/src/internet-stack/pending-data.h index eeba9ad69..4adec2f5c 100644 --- 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 (); diff --git a/src/internet-stack/rtt-estimator.h b/src/internet-stack/rtt-estimator.h index 9daf4584f..6ee3ad48b 100644 --- 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); diff --git a/src/internet-stack/sequence-number.h b/src/internet-stack/sequence-number.h index bca46e7a3..23093954e 100644 --- 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) { } diff --git a/src/internet-stack/tcp-header.h b/src/internet-stack/tcp-header.h index bfcbc81d8..e88c1a17e 100644 --- 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 diff --git a/src/internet-stack/tcp-l4-protocol.h b/src/internet-stack/tcp-l4-protocol.h index 492abb2f8..b567aaf6a 100644 --- 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, diff --git a/src/internet-stack/tcp-socket-factory-impl.h b/src/internet-stack/tcp-socket-factory-impl.h index acef1e2d9..b459e4ac8 100644 --- 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 * @@ -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: diff --git a/src/internet-stack/tcp-socket-impl.h b/src/internet-stack/tcp-socket-impl.h index 915c0ef5c..123d588ec 100644 --- 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. * diff --git a/src/internet-stack/udp-header.h b/src/internet-stack/udp-header.h index 23aaa1450..c6cd232b5 100644 --- 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 diff --git a/src/internet-stack/udp-l4-protocol.h b/src/internet-stack/udp-l4-protocol.h index e5ae60dda..c92f83a61 100644 --- 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 { diff --git a/src/internet-stack/udp-socket-factory-impl.h b/src/internet-stack/udp-socket-factory-impl.h index b4366fc31..e05e6443c 100644 --- 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 * diff --git a/src/internet-stack/udp-socket-impl.h b/src/internet-stack/udp-socket-impl.h index 1466b2d68..31f0f8bc7 100644 --- 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