--- a/doc/manual/Makefile Thu Dec 30 22:39:53 2010 +0100
+++ b/doc/manual/Makefile Thu Dec 30 23:39:27 2010 +0100
@@ -1,13 +1,8 @@
-TEXI2HTML = texi2html
-TEXI2PDF = texi2dvi --pdf
EPSTOPDF = epstopdf
DIA = dia
CONVERT = convert
-CSS = --css-include=manual.css
-SPLIT = --split section
FIGURES = figures
-DOC_FIGURES = ..
VPATH = $(FIGURES)
IMAGES_EPS = \
@@ -23,8 +18,8 @@
$(FIGURES)/testbed.eps \
$(FIGURES)/emulated-channel.eps \
$(FIGURES)/snir.eps \
- $(DOC_FIGURES)/WifiArchitecture.eps \
- $(DOC_FIGURES)/WimaxArchitecture.eps \
+ $(FIGURES)/WifiArchitecture.eps \
+ $(FIGURES)/WimaxArchitecture.eps \
$(FIGURES)/auvmobility-classes.eps \
# missing figure
@@ -49,68 +44,143 @@
IMAGES = $(IMAGES_EPS) $(IMAGES_PNG) $(IMAGES_PDF)
-CHAPTERS = \
- manual.texi \
- animation.texi \
- attributes.texi \
- bridge.texi \
- callbacks.texi \
- csma.texi \
- emulation.texi \
- emu.texi \
- flow-monitor.texi \
- helpers.texi \
- internet.texi \
- ipv4.texi \
- ipv6.texi \
- log.texi \
- manual.texi \
- mesh.texi \
- names.texi \
- new-models.texi \
- node.texi \
- objects.texi \
- other.texi \
- output.texi \
- packets.texi \
- point-to-point.texi \
- python.texi \
- random.texi \
- realtime.texi \
- distributed.texi \
- routing.texi \
- simple.texi \
- sockets.texi \
- statistics.texi \
- tap.texi \
- tcp.texi \
- tracing.texi \
- troubleshoot.texi \
- wifi.texi
-
%.eps : %.dia; $(DIA) -t eps $< -e $@
%.png : %.dia; $(DIA) -t png $< -e $@
%.pdf : %.eps; $(EPSTOPDF) $< -o=$@; if test x$($@_width) != x; then TMPFILE=`mktemp`; ./rescale-pdf.sh $($@_width) $@ $${TMPFILE} && mv $${TMPFILE} $@; fi
-all: $(IMAGES) version manual.pdf manual.html manual/manual.html
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = build
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
-manual.pdf: version $(IMAGES) $(CHAPTERS)
- $(TEXI2PDF) manual.texi
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
-manual.html: version $(IMAGES) $(CHAPTERS)
- $(TEXI2HTML) ${CSS} manual.texi
+clean:
+ -rm -rf $(BUILDDIR)/*
+ -rm -rf $(IMAGES)
+
+frag: pickle
+ @if test ! -d $(BUILDDIR)/frag; then mkdir $(BUILDDIR)/frag; fi
+ pushd $(BUILDDIR)/frag && ../../pickle-to-xml.py ../pickle/index.fpickle > navigation.xml && popd
+ cp -r $(BUILDDIR)/pickle/_images $(BUILDDIR)/frag
+
+html: $(IMAGES)
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-manual/manual.html: version $(IMAGES) $(CHAPTERS)
- $(TEXI2HTML) ${CSS} ${SPLIT} --output manual manual.texi
+dirhtml: $(IMAGES)
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml: $(IMAGES)
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle: $(IMAGES)
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json: $(IMAGES)
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
-figures-clean:
- rm -rf $(IMAGES)
+htmlhelp: $(IMAGES)
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
-version:
- echo -n "ns-" > VERSION-PREFIX; cat VERSION-PREFIX ../../VERSION > VERSION; rm -rf VERSION-PREFIX
+qthelp: $(IMAGES)
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/ns-3.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ns-3.qhc"
+
+devhelp: $(IMAGES)
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/ns-3"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ns-3"
+ @echo "# devhelp"
+
+epub: $(IMAGES)
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-texi-clean:
- rm -rf manual.aux manual.cp manual.cps manual.fn manual.ky manual.pg manual.tp
- rm -rf manual.vr manual.toc manual.log manual.pdf manual.html manual/ VERSION
+latex: $(IMAGES)
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf: $(IMAGES)
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ make -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text: $(IMAGES)
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
-clean: figures-clean texi-clean
+man: $(IMAGES)
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes: $(IMAGES)
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck: $(IMAGEs)
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest: $(IMAGES)
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
+
+
--- a/doc/manual/animation.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,209 +0,0 @@
-@node Animation
-@chapter Animation
-@anchor{chap:Animation}
-
-@menu
-* Animation interface::
-* NetAnim::
-@end menu
-
-Animation is an important tool for network simulation. While ns-3 does
-not contain a default graphical animation tool, it does provide an
-animation interface for use with stand-alone animators. One such
-animator called NetAnim, presently supporting packet flow animation
-for point-to-point links, has been developed. Other animators and
-visualization tools are in development; they may make use of the
-existing animation interface or may develop new ones,
-
-@node Animation interface
-@section Animation interface
-
-The animation interface uses underlying ns-3 trace sources to construct
-a timestamped ASCII file that can be read by a standalone animator.
-The animation interface in ns-3 currently only supports point-to-point
-links; however, we hope
-to support other link types such as CSMA and wireless in the near future.
-A snippet from a sample trace file is shown below.
-
-@verbatim
-0.0 N 0 4 5.5
-0.0 N 1 7 5.5
-0.0 N 2 2.5 2.90192
-
-...
-
-0.0 L 0 1
-0.0 L 0 2
-0.0 L 0 3
-
-...
-
-Running the simulation
-0.668926 P 11 1 0.66936 0.669926 0.67036
-0.67036 P 1 0 0.670794 0.67136 0.671794
-0.671794 P 0 6 0.672227 0.672794 0.673227
-
-...
-@end verbatim
-
-The tracefile describes where nodes and links should be placed at
-the top of the file. Following this placement, the packet events
-are shown. The format for node placement, link placement and
-packet events is shown below.
-
-@itemize @bullet
-@item Node placement: <time of placement> <N for node> <node id>
- <x position> <y position>
-@item Link placement: <time of placement> <L for link> <node1 id>
- <node2 id>
-@item Packet events: <time of first bit tx> <P for packet>
- <source node> <destination node>
- <time of last bit tx>
- <time of first bit rx>
- <time of last bit rx>
-@end itemize
-
-To get started using the animation interface, several example scripts
-have been provided to show proper use. These examples can be found
-in examples/animation. The example scripts use the animation interface
-as well as topology helpers in order to automatically place the nodes
-and generate the custom trace. It is important to note that if a
-topology helper is not used with its provided BoundingBox method,
-which automatically calculates the nodes' canvas positions, the nodes
-must be placed manually by aggregating a CanvasLocation to the node.
-An example use of CanvasLocation can be found in any of the topology
-helpers. Additionally, a simple example of placing a node is shown below:
-
-@verbatim
- // assuming a node container m_hub exists and
- // contains at least one node.
- // we grab this node and associate a
- // CanvasLocation to it, in order for the
- // animation interface to place the node
- Ptr<Node> hub = m_hub.Get (0);
- Ptr<CanvasLocation> hubLoc = hub->GetObject<CanvasLocation> ();
- if (hubLoc == 0)
- {
- hubLoc = CreateObject<CanvasLocation> ();
- hub->AggregateObject (hubLoc);
- }
- Vector hubVec (5, 7);
- hubLoc->SetLocation (hubVec);
-@end verbatim
-
-Finally, after the simulation has been set up and the nodes have been
-placed, the animation interface is used to start the animation, which
-writes the custom trace file. Below is an example of how to set
-up and start the animation interface.
-
-@verbatim
- AnimationInterface anim;
- // the animation interface can be set up to write
- // to a socket, if a port > 0 is specified
- // see doxygen for more information
- if (port > 0)
- {
- anim.SetServerPort (port);
- }
- else if (!animFile.empty ())
- {
- // if a file name is specified,
- // the trace is written to the file.
- // otherwise, it is directed to stdout
- anim.SetOutputFile (animFile);
- }
- anim.StartAnimation ();
-@end verbatim
-
-@node NetAnim
-@section NetAnim
-
-NetAnim is a stand-alone program which uses the custom trace files
-generated by the animation interface to graphically display the
-simulation. NetAnim is based on the multi-platform
-@uref{http://www.qtsoftware.com/products/,,Qt4 GUI toolkit}. A
-screenshot of the NetAnim GUI is shown below.
-
-@float Figure,fig:anim-dumbbell
-@caption{NetAnim GUI with dumbbell animation.}
-@image{figures/animation-dumbbell, 4in}
-@end float
-
-The NetAnim GUI provides play, pause, and record buttons. Play and
-pause start and stop the simulation. The record button starts a series
-of screenshots of the animator, which are written to the directory in
-which the trace file was run. Two slider bars also exist. The top
-slider provides a "seek" functionality, which allows a user to skip to
-any moment in the simulation. The bottom slider changes the granularity
-of the time step for the animation. Finally, there is a quit button to
-stop the simulation and quit the animator.
-
-@subsection Prerequisites
-
-The animator requires the Qt4 development packages. If you are using a
-Debian or Ubuntu Linux distribution, you can get the following package:
-qt4-dev-tools
-
-This should install everything you need to compile and build NetAnim.
-If you are using an Red Hat based distribution, look for similar qt4
-packages (or libqt4*) and install these using yum. Mac users should
-install the binaries: http://www.qtsoftware.com/downloads/mac-os-cpp
-
-Make sure to download the binary package; look for a link to something
-without the word "src" or "debug" in the download filename. These will
-be the library binaries you need.
-
-@subsection Downloading NetAnim
-
-The tarball of the source code for NetAnim is available here:
-@uref{http://www.nsnam.org/~jpelkey3/NetAnim.tar.gz,,http://www.nsnam.org/~jpelkey3/NetAnim.tar.gz}.
-Download it, then untar it:
-
-@verbatim
-tar -xzvf NetAnim.tar.gz
-@end verbatim
-
-@subsection Building NetAnim
-
-NetAnim uses a Qt4 build tool called qmake; this is similar to the
-configure script from autotools in that it generates the Makefile,
-which make then uses to build the project. qmake is different on
-different versions of Qt, so we'll provide some additional information
-that is system dependent. You can check your default version of qmake:
-
-@verbatim
-qmake --version
-Qmake version: 1.07a (Qt 3.3.8b)
-Qmake is free software from Trolltech ASA.
-@end verbatim
-
-If you see something like the above, where it says Qt 3.x.x, find the
-qt4 version of qmake on your system and explicitly call it instead.
-
-In general,
-
-@verbatim
-cd NetAnim
-qmake
-make
-@end verbatim
-
-On Mac OSX,
-
-@verbatim
-cd NetAnim
-/usr/local/Trolltech/Qt-4.x.y/bin/qmake
-make
-@end verbatim
-
-Note that above, the x.y is the specific version of Qt4 you are running.
-As of April 1st 2009, the latest version is 4.5.0, although you might
-have an older version already installed.
-
-On Ubuntu/Debian with Qt3 AND Qt4,
-
-@verbatim
-cd NetAnim
-qmake-qt4
-make
-@end verbatim
--- a/doc/manual/applications.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,6 +0,0 @@
-@node Applications Overview
-@chapter Applications Overview
-
-@cartouche
-Placeholder chapter
-@end cartouche
--- a/doc/manual/attributes.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,896 +0,0 @@
-@node Attributes
-@chapter Attributes
-@anchor{chap:Attributes}
-
-@menu
-* Object Overview::::
-* Attribute Overview::
-* Extending attributes::
-* Adding new class type::
-* ConfigStore::
-@end menu
-
-
-In ns-3 simulations, there are two main aspects to configuration:
-@itemize @bullet
-@item the simulation topology and how objects are connected
-@item the values used by the models instantiated in the topology
-@end itemize
-
-This chapter focuses on the second item above: how the many values
-in use in ns-3 are organized, documented, and modifiable by ns-3 users.
-The ns-3 attribute system is also the underpinning of how traces
-and statistics are gathered in the simulator.
-
-Before delving into details of the attribute value system,
-it will help to review some basic properties of @code{class ns3::Object}.
-
-@node Object Overview
-@section Object Overview
-
-ns-3 is fundamentally a C++ object-based system. By this we mean that
-new C++ classes (types) can be declared, defined, and subclassed
-as usual.
-
-Many ns-3 objects inherit from the @code{ns3::Object} base class. These
-objects have some additional properties that we exploit for
-organizing the system and improving the memory management
-of our objects:
-
-@itemize @bullet
-@item a "metadata" system that links the class name to a lot of
-meta-information about the object, including the base class of the subclass,
-the set of accessible constructors in the subclass, and the set of
-"attributes" of the subclass
-@item a reference counting smart pointer implementation, for memory
-management.
-@end itemize
-
-ns-3 objects that use the attribute system derive from either
-@code{ns3::Object} or @code{ns3::ObjectBase}. Most ns-3 objects
-we will discuss derive from @code{ns3::Object}, but a few that
-are outside the smart pointer memory management framework derive
-from @code{ns3::ObjectBase}.
-
-Let's review a couple of properties of these objects.
-
-@subsection Smart pointers
-
-As introduced in the ns-3 tutorial, ns-3 objects are memory managed by a
-@uref{http://en.wikipedia.org/wiki/Smart_pointer,,reference counting smart pointer implementation}, @code{class ns3::Ptr}.
-
-Smart pointers are used extensively in the ns-3 APIs, to avoid passing
-references to heap-allocated objects that may cause memory leaks.
-For most basic usage (syntax), treat a smart pointer like a regular pointer:
-@verbatim
- Ptr<WifiNetDevice> nd = ...;
- nd->CallSomeFunction ();
- // etc.
-@end verbatim
-
-@subsection CreateObject
-
-As we discussed above in @ref{Memory management and class Ptr},
-at the lowest-level API, objects of type @code{ns3::Object} are
-not instantiated using @code{operator new} as usual but instead by
-a templated function called @code{CreateObject()}.
-
-A typical way to create such an object is as follows:
-@verbatim
- Ptr<WifiNetDevice> nd = CreateObject<WifiNetDevice> ();
-@end verbatim
-
-You can think of this as being functionally equivalent to:
-@verbatim
- WifiNetDevice* nd = new WifiNetDevice ();
-@end verbatim
-
-Objects that derive from @code{ns3::Object} must be allocated
-on the heap using CreateObject(). Those deriving from
-@code{ns3::ObjectBase}, such as ns-3 helper functions and packet
-headers and trailers, can be allocated on the stack.
-
-In some scripts, you may not see a lot of CreateObject() calls
-in the code;
-this is because there are some helper objects in effect that
-are doing the CreateObject()s for you.
-
-@subsection TypeId
-
-ns-3 classes that derive from class ns3::Object can include
-a metadata class called @code{TypeId} that records meta-information
-about the class, for use in the object aggregation and component
-manager systems:
-@itemize @bullet
- @item a unique string identifying the class
- @item the base class of the subclass, within the metadata system
- @item the set of accessible constructors in the subclass
-@end itemize
-
-@subsection Object Summary
-
-Putting all of these concepts together, let's look at a specific
-example: @code{class ns3::Node}.
-
-The public header file node.h has a declaration that includes
-a static GetTypeId function call:
-
-@verbatim
-class Node : public Object
-@{
-public:
- static TypeId GetTypeId (void);
- ...
-@end verbatim
-
-This is defined in the node.cc file as follows:
-
-@smallformat
-@example
-TypeId
-Node::GetTypeId (void)
-@{
- static TypeId tid = TypeId ("ns3::Node")
- .SetParent<Object> ()
- .AddConstructor<Node> ()
- .AddAttribute ("DeviceList", "The list of devices associated to this Node.",
- ObjectVectorValue (),
- MakeObjectVectorAccessor (&Node::m_devices),
- MakeObjectVectorChecker<NetDevice> ())
- .AddAttribute ("ApplicationList", "The list of applications associated to this Node.",
- ObjectVectorValue (),
- MakeObjectVectorAccessor (&Node::m_applications),
- MakeObjectVectorChecker<Application> ())
- .AddAttribute ("Id", "The id (unique integer) of this Node.",
- TypeId::ATTR_GET, // allow only getting it.
- UintegerValue (0),
- MakeUintegerAccessor (&Node::m_id),
- MakeUintegerChecker<uint32_t> ())
- ;
- return tid;
-@}
-@end example
-@end smallformat
-
-Consider the TypeId of an ns-3 @code{Object} class as an extended form of run
-time type information (RTTI). The C++ language includes a simple kind of RTTI
-in order to support @code{dynamic_cast} and @code{typeid} operators.
-
-The ``@code{.SetParent<Object> ()}'' call in the declaration above is used in
-conjunction with our object aggregation mechanisms to allow safe up- and
-down-casting in inheritance trees during @code{GetObject}.
-
-The ``@code{.AddConstructor<Node> ()}'' call is used in conjunction with our
-abstract object factory mechanisms to allow us to construct C++ objects without
-forcing a user to know the concrete class of the object she is building.
-
-The three calls to ``@code{.AddAttribute}'' associate a given string with a
-strongly typed value in the class. Notice that you must provide a help string
-which may be displayed, for example, via command line processors. Each
-@code{Attribute} is associated with mechanisms for accessing the underlying
-member variable in the object (for example, @code{MakeUintegerAccessor} tells
-the generic @code{Attribute} code how to get to the node ID above). There are
-also ``Checker'' methods which are used to validate values.
-
-When users want to create Nodes, they will usually call some form of
-@code{CreateObject},
-
-@verbatim
- Ptr<Node> n = CreateObject<Node> ();
-@end verbatim
-
-or more abstractly, using an object factory, you can create a @code{Node} object
-without even knowing the concrete C++ type
-
-@verbatim
- ObjectFactory factory;
- const std::string typeId = "ns3::Node'';
- factory.SetTypeId (typeId);
- Ptr<Object> node = factory.Create <Object> ();
-@end verbatim
-
-Both of these methods result in fully initialized attributes being available
-in the resulting @code{Object} instances.
-
-We next discuss how attributes (values associated with member variables
-or functions of the class) are plumbed into the above TypeId.
-
-@node Attribute Overview
-@section Attribute Overview
-
-The goal of the attribute system is to organize the access of
-internal member objects of a simulation. This goal arises because,
-typically in simulation, users will cut and paste/modify existing
-simulation scripts, or will use higher-level simulation constructs,
-but often will be interested in studying or tracing particular
-internal variables. For instance, use cases such as:
-@itemize @bullet
-@item "I want to trace the packets on the wireless interface only on
-the first access point"
-@item "I want to trace the value of the TCP congestion window (every
-time it changes) on a particular TCP socket"
-@item "I want a dump of all values that were used in my simulation."
-@end itemize
-
-Similarly, users may want fine-grained access to internal
-variables in the simulation, or may want to broadly change the
-initial value used for a particular parameter in all subsequently
-created objects. Finally, users may wish to know what variables
-are settable and retrievable in a simulation configuration. This
-is not just for direct simulation interaction on the command line;
-consider also a (future) graphical user interface
-that would like to be able to provide a feature whereby a user
-might right-click on an node on the canvas and see a hierarchical,
-organized list of parameters that are settable on the node and its
-constituent member objects, and help text and default values for
-each parameter.
-
-@subsection Functional overview
-
-We provide a way for users to access values deep in the system, without
-having to plumb accessors (pointers) through the system and walk
-pointer chains to get to them. Consider a class DropTailQueue that
-has a member variable that is an unsigned integer @code{m_maxPackets};
-this member variable controls the depth of the queue.
-
-If we look at the declaration of DropTailQueue, we see the following:
-@verbatim
-class DropTailQueue : public Queue {
-public:
- static TypeId GetTypeId (void);
- ...
-
-private:
- std::queue<Ptr<Packet> > m_packets;
- uint32_t m_maxPackets;
-};
-@end verbatim
-
-Let's consider things that a user may want to do with the value of
-m_maxPackets:
-
-@itemize @bullet
-@item Set a default value for the system, such that whenever a new
-DropTailQueue is created, this member is initialized to that default.
-@item Set or get the value on an already instantiated queue.
-@end itemize
-
-The above things typically require providing Set() and Get() functions,
-and some type of global default value.
-
-In the ns-3 attribute system, these value definitions and accessor
-functions are moved into the TypeId class; e.g.:
-
-@smallformat
-@example
-NS_OBJECT_ENSURE_REGISTERED (DropTailQueue);
-
-TypeId DropTailQueue::GetTypeId (void)
-@{
- static TypeId tid = TypeId ("ns3::DropTailQueue")
- .SetParent<Queue> ()
- .AddConstructor<DropTailQueue> ()
- .AddAttribute ("MaxPackets",
- "The maximum number of packets accepted by this DropTailQueue.",
- UintegerValue (100),
- MakeUintegerAccessor (&DropTailQueue::m_maxPackets),
- MakeUintegerChecker<uint32_t> ())
- ;
-
- return tid;
-@}
-@end example
-@end smallformat
-
-The AddAttribute() method is performing a number of things with this
-value:
-@itemize @bullet
-@item Binding the variable m_maxPackets to a string "MaxPackets"
-@item Providing a default value (100 packets)
-@item Providing some help text defining the value
-@item Providing a "checker" (not used in this example) that can be used to set
-bounds on the allowable range of values
-@end itemize
-
-The key point is that now the value of this variable and its default
-value are accessible in the attribute namespace, which is based on
-strings such as "MaxPackets" and TypeId strings. In the next
-section, we will provide an example script that shows how users
-may manipulate these values.
-
-Note that initialization of the attribute relies on the macro
-@code{NS_OBJECT_ENSURE_REGISTERED} (DropTailQueue) being called; if you leave
-this out of your new class implementation, your attributes will not be
-initialized correctly.
-
-While we have described how to create attributes, we still haven't
-described how to access and manage these values. For instance, there is no
-@code{globals.h} header file where these are stored; attributes are
-stored with their classes. Questions that naturally arise are how
-do users easily learn about all of the attributes of their models, and
-how does a user access these attributes, or document their values
-as part of the record of their simulation?
-
-@subsection Default values and command-line arguments
-
-Let's look at how a user script might access these values.
-This is based on the script found at @code{samples/main-attribute-value.cc},
-with some details stripped out.
-@verbatim
-//
-// This is a basic example of how to use the attribute system to
-// set and get a value in the underlying system; namely, an unsigned
-// integer of the maximum number of packets in a queue
-//
-
-int
-main (int argc, char *argv[])
-@{
-
- // By default, the MaxPackets attribute has a value of 100 packets
- // (this default can be observed in the function DropTailQueue::GetTypeId)
- //
- // Here, we set it to 80 packets. We could use one of two value types:
- // a string-based value or a Uinteger value
- Config::SetDefault ("ns3::DropTailQueue::MaxPackets", StringValue ("80"));
- // The below function call is redundant
- Config::SetDefault ("ns3::DropTailQueue::MaxPackets", UintegerValue (80));
-
- // Allow the user to override any of the defaults and the above
- // SetDefaults() at run-time, via command-line arguments
- CommandLine cmd;
- cmd.Parse (argc, argv);
-@end verbatim
-
-The main thing to notice in the above are the two calls to
-@code{Config::SetDefault}. This is how we set the default value
-for all subsequently instantiated DropTailQueues. We illustrate
-that two types of Value classes, a StringValue and a UintegerValue class,
-can be used to assign the value to the attribute named by
-"ns3::DropTailQueue::MaxPackets".
-
-Now, we will create a few objects using the low-level API; here,
-our newly created queues will not have a m_maxPackets initialized to
-100 packets but to 80 packets, because of what we did above with
-default values.
-@smallformat
-@example
- Ptr<Node> n0 = CreateObject<Node> ();
-
- Ptr<PointToPointNetDevice> net0 = CreateObject<PointToPointNetDevice> ();
- n0->AddDevice (net0);
-
- Ptr<Queue> q = CreateObject<DropTailQueue> ();
- net0->AddQueue(q);
-@end example
-@end smallformat
-
-At this point, we have created a single node (Node 0) and a
-single PointToPointNetDevice (NetDevice 0) and added a
-DropTailQueue to it.
-
-Now, we can manipulate the MaxPackets value of the already
-instantiated DropTailQueue. Here are various ways to do that.
-
-@subsection Pointer-based access
-
-We assume that a smart pointer (Ptr) to a relevant network device is
-in hand; in the current example, it is the @code{net0} pointer.
-
-One way to change the value is to access a pointer to the
-underlying queue and modify its attribute.
-
-First, we observe that we can get a pointer to the (base class)
-queue via the PointToPointNetDevice attributes, where it is called
-TxQueue
-@example
- PointerValue tmp;
- net0->GetAttribute ("TxQueue", tmp);
- Ptr<Object> txQueue = tmp.GetObject ();
-@end example
-
-Using the GetObject function, we can perform a safe downcast
-to a DropTailQueue, where MaxPackets is a member
-@verbatim
- Ptr<DropTailQueue> dtq = txQueue->GetObject <DropTailQueue> ();
- NS_ASSERT (dtq != 0);
-@end verbatim
-
-Next, we can get the value of an attribute on this queue.
-We have introduced wrapper "Value" classes for the underlying
-data types, similar to Java wrappers around these types, since
-the attribute system stores values and not disparate types.
-Here, the attribute value is assigned to a UintegerValue, and
-the Get() method on this value produces the (unwrapped) uint32_t.
-@verbatim
- UintegerValue limit;
- dtq->GetAttribute ("MaxPackets", limit);
- NS_LOG_INFO ("1. dtq limit: " << limit.Get () << " packets");
-@end verbatim
-
-Note that the above downcast is not really needed; we could have
-done the same using the Ptr<Queue> even though the attribute
-is a member of the subclass
-@verbatim
- txQueue->GetAttribute ("MaxPackets", limit);
- NS_LOG_INFO ("2. txQueue limit: " << limit.Get () << " packets");
-@end verbatim
-
-Now, let's set it to another value (60 packets)
-@verbatim
- txQueue->SetAttribute("MaxPackets", UintegerValue (60));
- txQueue->GetAttribute ("MaxPackets", limit);
- NS_LOG_INFO ("3. txQueue limit changed: " << limit.Get () << " packets");
-@end verbatim
-
-@subsection Namespace-based access
-
-An alternative way to get at the attribute is to use the configuration namespace.
-Here, this attribute resides on a known path in this namespace; this approach
-is useful if one doesn't have access to the underlying pointers and would like
-to configure a specific attribute with a single statement.
-
-@smallformat
-@example
- Config::Set ("/NodeList/0/DeviceList/0/TxQueue/MaxPackets", UintegerValue (25));
- txQueue->GetAttribute ("MaxPackets", limit);
- NS_LOG_INFO ("4. txQueue limit changed through namespace: " <<
- limit.Get () << " packets");
-@end example
-@end smallformat
-
-We could have also used wildcards to set this value for all nodes and all net
-devices (which in this simple example has the same effect as the previous Set())
-@smallformat
-@example
- Config::Set ("/NodeList/*/DeviceList/*/TxQueue/MaxPackets", UintegerValue (15));
- txQueue->GetAttribute ("MaxPackets", limit);
- NS_LOG_INFO ("5. txQueue limit changed through wildcarded namespace: " <<
- limit.Get () << " packets");
-@end example
-@end smallformat
-
-@subsection Object Name Service-based access
-
-Another way to get at the attribute is to use the object name service facility.
-Here, this attribute is found using a name string. This approach is useful if
-one doesn't have access to the underlying pointers and it is difficult to
-determine the required concrete configuration namespaced path.
-
-@smallformat
-@example
- Names::Add ("server", serverNode);
- Names::Add ("server/eth0", serverDevice);
-
- ...
-
- Config::Set ("/Names/server/eth0/TxQueue/MaxPackets", UintegerValue (25));
-@end example
-@end smallformat
-
-@xref{Object names} for a fuller treatment of the ns-3 configuration namespace.
-
-@subsection Setting through constructors helper classes
-
-Arbitrary combinations of attributes can be set and fetched from
-the helper and low-level APIs; either from the constructors themselves:
-@verbatim
-Ptr<Object> p = CreateObject<MyNewObject> ("n1", v1, "n2", v2, ...);
-@end verbatim
-or from the higher-level helper APIs, such as:
-@verbatim
- mobility.SetPositionAllocator ("GridPositionAllocator",
- "MinX", DoubleValue (-100.0),
- "MinY", DoubleValue (-100.0),
- "DeltaX", DoubleValue (5.0),
- "DeltaY", DoubleValue (20.0),
- "GridWidth", UintegerValue (20),
- "LayoutType", StringValue ("RowFirst"));
-@end verbatim
-
-@subsection Implementation details
-@subsubsection Value classes
-Readers will note the new FooValue classes which are subclasses of the
-AttributeValue base class. These can be thought of as
-an intermediate class that can be used to convert from raw types to the
-Values that are used by the attribute system. Recall that this database is holding
-objects of many types with a single generic type. Conversions to this
-type can either be done using an intermediate class (IntegerValue, DoubleValue for
-"floating point") or via strings. Direct implicit conversion of types
-to Value is not really practical. So in the above, users have a choice
-of using strings or values:
-@verbatim
-p->Set ("cwnd", StringValue ("100")); // string-based setter
-p->Set ("cwnd", IntegerValue (100)); // integer-based setter
-@end verbatim
-
-The system provides some macros that help users declare and define
-new AttributeValue subclasses for new types that they want to introduce into
-the attribute system:
-@itemize @bullet
-@item ATTRIBUTE_HELPER_HEADER
-@item ATTRIBUTE_HELPER_CPP
-@end itemize
-
-@subsubsection Initialization order
-
-Attributes in the system must not depend on the state of any other Attribute
-in this system. This is because an ordering of Attribute initialization is
-not specified, nor enforced, by the system. A specific example of this
-can be seen in automated configuration programs such as @code{ns3::ConfigStore}.
-Although a given model may arrange it so that Attributes are initialized in
-a particular order, another automatic configurator may decide independently
-to change Attributes in, for example, alphabetic order.
-
-Because of this non-specific ordering, no Attribute in the system may have
-any dependence on any other Attribute. As a corollary, Attribute setters must
-never fail due to the state of another Attribute. No Attribute setter may
-change (set) any other Attribute value as a result of changing its value.
-
-This is a very strong restriction and there are cases where Attributes must
-set consistently to allow correct operation. To this end we do allow for
-consistency checking @emph{when the attribute is used} (cf. NS_ASSERT_MSG
-or NS_ABORT_MSG).
-
-In general, the attribute code to assign values to the underlying
-class member variables is executed after an object is constructed.
-But what if you need the values assigned before the constructor
-body executes, because you need them in the logic of the constructor?
-There is a way to do this, used for example in the class
-@code{ns3::ConfigStore}: call @code{ObjectBase::ConstructSelf ()}
-as follows:
-
-@verbatim
-ConfigStore::ConfigStore ()
-@{
- ObjectBase::ConstructSelf (AttributeList ());
- // continue on with constructor.
-@}
-@end verbatim
-
-@node Extending attributes
-@section Extending attributes
-
-The ns-3 system will place a number of internal values under the
-attribute system, but undoubtedly users will want to extend this
-to pick up ones we have missed, or to add their own classes to this.
-
-@subsection Adding an existing internal variable to the metadata system
-
-Consider this variable in class TcpSocket:
-@verbatim
- uint32_t m_cWnd; // Congestion window
-@end verbatim
-
-Suppose that someone working with TCP wanted to get or set the
-value of that variable using the metadata system. If it were not
-already provided by ns-3, the user could declare the following addition
-in the runtime metadata system (to the TypeId declaration for TcpSocket):
-@verbatim
- .AddAttribute ("Congestion window",
- "Tcp congestion window (bytes)",
- UintegerValue (1),
- MakeUintegerAccessor (&TcpSocket::m_cWnd),
- MakeUintegerChecker<uint16_t> ())
-
-@end verbatim
-
-Now, the user with a pointer to the TcpSocket can perform operations
-such as setting and getting the value, without having to add these
-functions explicitly. Furthermore, access controls can be applied, such
-as allowing the parameter to be read and not written, or bounds
-checking on the permissible values can be applied.
-
-@subsection Adding a new TypeId
-
-Here, we discuss the impact on a user who wants to add a new class to
-ns-3; what additional things must be done to hook it into this system.
-
-We've already introduced what a TypeId definition looks like:
-@smallformat
-@example
-TypeId
-RandomWalk2dMobilityModel::GetTypeId (void)
-@{
- static TypeId tid = TypeId ("ns3::RandomWalk2dMobilityModel")
- .SetParent<MobilityModel> ()
- .SetGroupName ("Mobility")
- .AddConstructor<RandomWalk2dMobilityModel> ()
- .AddAttribute ("Bounds",
- "Bounds of the area to cruise.",
- RectangleValue (Rectangle (0.0, 0.0, 100.0, 100.0)),
- MakeRectangleAccessor (&RandomWalk2dMobilityModel::m_bounds),
- MakeRectangleChecker ())
- .AddAttribute ("Time",
- "Change current direction and speed after moving for this delay.",
- TimeValue (Seconds (1.0)),
- MakeTimeAccessor (&RandomWalk2dMobilityModel::m_modeTime),
- MakeTimeChecker ())
- // etc (more parameters).
- ;
- return tid;
-@}
-@end example
-@end smallformat
-
-The declaration for this in the class declaration is one-line public
-member method:
-@verbatim
- public:
- static TypeId GetTypeId (void);
-@end verbatim
-
-Typical mistakes here involve:
-@itemize @bullet
-@item Not calling the SetParent method or calling it with the wrong type
-@item Not calling the AddConstructor method of calling it with the wrong type
-@item Introducing a typographical error in the name of the TypeId in its constructor
-@item Not using the fully-qualified c++ typename of the enclosing c++ class as the
-name of the TypeId
-@end itemize
-None of these mistakes can be detected by the ns-3 codebase so, users
-are advised to check carefully multiple times that they got these right.
-
-
-@node Adding new class type
-@section Adding new class type to the attribute system
-
-From the perspective of the user who writes a new class in the system and
-wants to hook it in to the attribute system, there is mainly the matter
-of writing
-the conversions to/from strings and attribute values. Most of this can be
-copy/pasted with macro-ized code. For instance, consider class
-declaration for Rectangle in the @code{src/mobility/} directory:
-
-@subsection Header file
-@smallformat
-@example
-/**
- * \brief a 2d rectangle
- */
-class Rectangle
-@{
- ...
-
- double xMin;
- double xMax;
- double yMin;
- double yMax;
-@};
-@end example
-@end smallformat
-
-One macro call and two operators, must be added below the class declaration
-in order to turn a Rectangle into a value usable by the @code{Attribute}
-system:
-
-@smallformat
-@example
-std::ostream &operator << (std::ostream &os, const Rectangle &rectangle);
-std::istream &operator >> (std::istream &is, Rectangle &rectangle);
-
-ATTRIBUTE_HELPER_HEADER (Rectangle);
-@end example
-@end smallformat
-
-@subsection Implementation file
-In the class definition (@code{.cc} file), the code looks like this:
-
-@smallformat
-@example
-ATTRIBUTE_HELPER_CPP (Rectangle);
-
-std::ostream &
-operator << (std::ostream &os, const Rectangle &rectangle)
-@{
- os << rectangle.xMin << "|" << rectangle.xMax << "|" << rectangle.yMin << "|"
- << rectangle.yMax;
- return os;
-@}
-std::istream &
-operator >> (std::istream &is, Rectangle &rectangle)
-@{
- char c1, c2, c3;
- is >> rectangle.xMin >> c1 >> rectangle.xMax >> c2 >> rectangle.yMin >> c3
- >> rectangle.yMax;
- if (c1 != '|' ||
- c2 != '|' ||
- c3 != '|')
- @{
- is.setstate (std::ios_base::failbit);
- @}
- return is;
-@}
-@end example
-@end smallformat
-
-These stream operators simply convert from a string representation of the
-Rectangle ("xMin|xMax|yMin|yMax") to the underlying Rectangle, and the
-modeler must specify these operators and the string syntactical representation
-of an instance of the new class.
-
-@node ConfigStore
-@section ConfigStore
-
-@strong{Feedback requested:} This is an experimental feature of ns-3. It is
-found in @code{src/contrib} and not in the main tree. If you like this feature
-and would like to provide feedback on it, please email us.
-
-Values for ns-3 attributes can be stored in an ASCII or XML text file and
-loaded into a future simulation. This feature is known as the
-ns-3 ConfigStore.
-The ConfigStore code is in @code{src/contrib/}. It is not yet main-tree
-code, because we are seeking some user feedback and experience with this.
-
-We can explore this system by using an example. Copy the @code{csma-bridge.cc}
-file to the scratch directory:
-@verbatim
- cp examples/csma-bridge.cc scratch/
- ./waf
-@end verbatim
-
-Let's edit it to add the ConfigStore feature. First, add an include statement
-to include the contrib module, and then add these lines:
-
-@smallformat
-@example
-#include "contrib-module.h"
-...
-int main (...)
-@{
- // setup topology
-
- // Invoke just before entering Simulator::Run ()
- ConfigStore config;
- config.ConfigureDefaults ();
- config.ConfigureAttributes ();
-
- Simulator::Run ();
-@}
-@end example
-@end smallformat
-
-There are three attributes that govern the behavior of the ConfigStore:
-"Mode", "Filename", and "FileFormat". The Mode (default "None") configures
-whether ns-3 should load configuration from a previously saved file
-(specify "Mode=Load") or save it to a file (specify "Mode=Save").
-The Filename (default "") is where the ConfigStore should store its
-output data. The FileFormat (default "RawText") governs whether
-the ConfigStore format is Xml or RawText format.
-
-So, using the above modified program, try executing the following
-waf command and
-@smallformat
-@example
-./waf --command-template="%s --ns3::ConfigStore::Filename=csma-bridge-config.xml
---ns3::ConfigStore::Mode=Save --ns3::ConfigStore::FileFormat=Xml" --run scratch/csma-bridge
-@end example
-@end smallformat
-After running, you can open the csma-bridge-config.xml file and it will
-display the configuration that was applied to your simulation; e.g.
-@smallformat
-@example
-<?xml version="1.0" encoding="UTF-8"?>
-<ns3>
- <default name="ns3::V4Ping::Remote" value="102.102.102.102"/>
- <default name="ns3::MsduStandardAggregator::MaxAmsduSize" value="7935"/>
- <default name="ns3::EdcaTxopN::MinCw" value="31"/>
- <default name="ns3::EdcaTxopN::MaxCw" value="1023"/>
- <default name="ns3::EdcaTxopN::Aifsn" value="3"/>
- <default name="ns3::StaWifiMac::ProbeRequestTimeout" value="50000000ns"/>
- <default name="ns3::StaWifiMac::AssocRequestTimeout" value="500000000ns"/>
- <default name="ns3::StaWifiMac::MaxMissedBeacons" value="10"/>
- <default name="ns3::StaWifiMac::ActiveProbing" value="false"/>
-...
-@end example
-@end smallformat
-
-This file can be archived with your simulation script and output data.
-
-While it is possible to generate a sample config file and lightly
-edit it to change a couple of values, there are cases where this
-process will not work because the same value on the same object
-can appear multiple times in the same automatically-generated
-configuration file under different configuration paths.
-
-As such, the best way to use this class is to use it to generate
-an initial configuration file, extract from that configuration
-file only the strictly necessary elements, and move these minimal
-elements to a new configuration file which can then safely
-be edited and loaded in a subsequent simulation run.
-
-When the ConfigStore object is instantiated, its attributes Filename,
-Mode, and FileFormat must be set, either via command-line or via
-program statements.
-
-As a more complicated example, let's assume that we want to
-read in a configuration of defaults from an input file named
-"input-defaults.xml", and write out the resulting attributes to a
-separate file called "output-attributes.xml". (Note-- to get this
-input xml file to begin with, it is sometimes helpful to run the
-program to generate an output xml file first, then hand-edit that
-file and re-input it for the next simulation run).
-@smallformat
-@example
-#include "contrib-module.h"
-...
-int main (...)
-@{
-
- Config::SetDefault ("ns3::ConfigStore::Filename", StringValue ("input-defaults.xml"));
- Config::SetDefault ("ns3::ConfigStore::Mode", StringValue ("Load"));
- Config::SetDefault ("ns3::ConfigStore::FileFormat", StringValue ("Xml"));
- ConfigStore inputConfig;
- inputConfig.ConfigureDefaults ();
-
- //
- // Allow the user to override any of the defaults and the above Bind() at
- // run-time, via command-line arguments
- //
- CommandLine cmd;
- cmd.Parse (argc, argv);
-
- // setup topology
- ...
-
- // Invoke just before entering Simulator::Run ()
- Config::SetDefault ("ns3::ConfigStore::Filename", StringValue ("output-attributes.xml"));
- Config::SetDefault ("ns3::ConfigStore::Mode", StringValue ("Save"));
- ConfigStore outputConfig;
- outputConfig.ConfigureAttributes ();
- Simulator::Run ();
-@}
-@end example
-@end smallformat
-
-@subsection GTK-based ConfigStore
-
-There is a GTK-based front end for the ConfigStore. This allows users
-to use a GUI to access and change variables. Screenshots of this
-feature are available in the
-@uref{http://www.nsnam.org/docs/ns-3-overview.pdf,,ns-3 Overview} presentation.
-
-To use this feature, one must install libgtk and libgtk-dev; an example
-Ubuntu installation command is:
-@verbatim
-sudo apt-get install libgtk2.0-0 libgtk2.0-dev
-@end verbatim
-To check whether it is configured or not, check the output of the
-./waf configure step:
-@smallformat
-@example
----- Summary of optional NS-3 features:
-Threading Primitives : enabled
-Real Time Simulator : enabled
-GtkConfigStore : not enabled (library 'gtk+-2.0 >= 2.12' not found)
-@end example
-@end smallformat
-
-In the above example, it was not enabled, so it cannot be used until a
-suitable version is installed and ./waf configure; ./waf is rerun.
-
-Usage is almost the same as the non-GTK-based version, but there
-are no ConfigStore attributes involved:
-@smallformat
-@example
- // Invoke just before entering Simulator::Run ()
- GtkConfigStore config;
- config.ConfigureDefaults ();
- config.ConfigureAttributes ();
-@end example
-@end smallformat
-
-Now, when you run the script, a GUI should pop up, allowing you to open
-menus of attributes on different nodes/objects, and then launch the
-simulation execution when you are done.
-
-@subsection Future work
-There are a couple of possible improvements:
-@itemize @bullet
-@item save a unique version number with date and time at start of file
-@item save rng initial seed somewhere.
-@item make each RandomVariable serialize its own initial seed and re-read
-it later
-@item add the default values
-@end itemize
-
--- a/doc/manual/bridge.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-@node Bridge NetDevice
-@chapter Bridge NetDevice
-
-@cartouche
-Placeholder chapter
-@end cartouche
-
-Some examples of the use of Bridge NetDevice can be found in
-@code{examples/csma/} directory.
--- a/doc/manual/callbacks.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,646 +0,0 @@
-@node Callbacks
-@chapter Callbacks
-
-Some new users to @command{ns-3} are unfamiliar with an extensively used
-programming idiom used throughout the code: the ``ns-3 callback''. This
-chapter provides some motivation on the callback, guidance on how to use
-it, and details on its implementation.
-
-@menu
-* Callbacks Motivation::
-* Callbacks Background::
-* Using the Callback API::
-* Bound Callbacks::
-* Traced Callbacks::
-* Callback locations in ns-3::
-* Implementation details::
-@end menu
-
-@node Callbacks Motivation
-@section Motivation
-
-Consider that you have two simulation models A and B, and you wish
-to have them pass information between them during the simulation. One
-way that you can do that is that you can make A and B each explicitly
-knowledgeable about the other, so that they can invoke methods on each
-other.
-
-@verbatim
-class A {
-public:
- void ReceiveInput ( // parameters );
- ...
-}
-
-(in another source file:)
-
-class B {
-public:
- void DoSomething (void);
- ...
-
-private:
- A* a_instance; // pointer to an A
-}
-
-void
-B::DoSomething()
-{
- // Tell a_instance that something happened
- a_instance->ReceiveInput ( // parameters);
- ...
-}
-@end verbatim
-
-This certainly works, but it has the drawback that it introduces a
-dependency on A and B to know about the other at compile time (this
-makes it harder to have independent compilation units in the simulator)
-and is not generalized; if in a later usage scenario, B needs to talk
-to a completely different C object, the source code for B needs to be
-changed to add a ``c_instance'' and so forth. It is easy to see that
-this is a brute force mechanism of communication that can lead to
-programming cruft in the models.
-
-This is not to say that objects should not know about one another
-if there is a hard dependency between them, but that often the model
-can be made more flexible if its interactions are less constrained at
-compile time.
-
-This is not an abstract problem for network simulation research,
-but rather it has been a source of problems in previous simulators,
-when researchers want to extend or modify the system to do different
-things (as they are apt to do in research). Consider, for example,
-a user who wants to add an IPsec security protocol sublayer
-between TCP and IP:
-@verbatim
------------- -----------
-| TCP | | TCP |
------------- -----------
- | becomes -> |
------------ -----------
-| IP | | IPsec |
------------ -----------
- |
- -----------
- | IP |
- -----------
-@end verbatim
-If the simulator has
-made assumptions, and hard coded into the code, that IP always talks
-to a transport protocol above, the user may be forced to hack the
-system to get the desired interconnections, This is clearly not an
-optimal way to design a generic simulator.
-
-@node Callbacks Background
-@section Background
-
-@cartouche
-Readers familiar with programming callbacks may skip this tutorial section.
-@end cartouche
-
-The basic mechanism that allows one to address the problem above is known as
-a @emph{callback}. The ultimate goal is to allow one piece of code to call
-a function (or method in C++) without any specific inter-module dependency.
-
-This ultimately means you need some kind of indirection -- you treat the address
-of the called function as a variable. This variable is called a pointer-to-function
-variable. The relationship between function and pointer-to-function pointer is
-really no different that that of object and pointer-to-object.
-
-In C the canonical example of a pointer-to-function is a
-pointer-to-function-returning-integer (PFI). For a PFI taking one int parameter,
-this could be declared like,
-
-@verbatim
- int (*pfi)(int arg) = 0;
-@end verbatim
-
-What you get from this is a variable named simply ``pfi'' that is initialized
-to the value 0. If you want to initialize this pointer to something meaningful,
-you have to have a function with a matching signature. In this case,
-
-@verbatim
- int MyFunction (int arg) {}
-@end verbatim
-
-If you have this target, you can initialize the variable to point to your
-function like,
-
-@verbatim
- pfi = MyFunction;
-@end verbatim
-
-You can then call MyFunction indirectly using the more suggestive form of
-the call,
-
-@verbatim
- int result = (*pfi) (1234);
-@end verbatim
-
-This is suggestive since it looks like you are dereferencing the function
-pointer just like you would dereference any pointer. Typically, however,
-people take advantage of the fact that the compiler knows what is going on
-and will just use a shorter form,
-
-@verbatim
- int result = pfi (1234);
-@end verbatim
-
-Notice that the function pointer obeys value semantics, so you can pass it
-around like any other value. Typically, when you use an asynchronous interface
-you will pass some entity like this to a function which will perform an action
-and ``call back'' to let you know it completed. It calls back by following the
-indirection and executing the provided function.
-
-In C++ you have the added complexity of objects. The analogy with the PFI
-above means you have a pointer to a member function returning an int (PMI)
-instead of the pointer to function returning an int (PFI).
-
-The declaration of the variable providing the indirection looks only slightly
-different,
-
-@verbatim
- int (MyClass::*pmi) (int arg) = 0;
-@end verbatim
-
-This declares a variable named ``pmi'' just as the previous example declared a
-variable named ``pfi.'' Since the will be to call a method of an instance of
-a particular class, one must declare that method in a class.
-
-@verbatim
- class MyClass {
- public:
- int MyMethod (int arg);
- };
-@end verbatim
-
-Given this class declaration, one would then initialize that variable like this,
-
-@verbatim
- pmi = &MyClass::MyMethod;
-@end verbatim
-
-This assigns the address of the code implementing the method to the variable,
-completing the indirection. In order to call a method, the code needs a ``this''
-pointer. This, in turn, means there must be an object of MyClass to refer to.
-A simplistic example of this is just calling a method indirectly (think virtual
-function).
-
-@verbatim
- int (MyClass::*pmi) (int arg) = 0; // Declare a PMI
- pmi = &MyClass::MyMethod; // Point at the implementation code
-
- MyClass myClass; // Need an instance of the class
- (myClass.*pmi) (1234); // Call the method with an object ptr
-@end verbatim
-
-Just like in the C example, you can use this in an asynchronous call to another
-module which will ``call back'' using a method and an object pointer. The
-straightforward extension one might consider is to pass a pointer to the object
-and the PMI variable. The module would just do,
-
-@verbatim
- (*objectPtr.*pmi) (1234);
-@end verbatim
-
-to execute the callback on the desired object.
-
-One might ask at this time, ``what's the point''? The called module will have
-to understand the concrete type of the calling object in order to properly make
-the callback. Why not just accept this, pass the correctly typed object pointer
-and do object->Method(1234) in the code instead of the callback? This is
-precisely the problem described above. What is needed is a way to decouple the
-calling function from the called class completely. This requirement led to the
-development of the @emph{Functor}.
-
-A functor is the outgrowth of something invented in the 1960s called a closure.
-It is basically just a packaged-up function call, possibly with some state.
-
-A functor has two parts, a specific part and a generic part, related through
-inheritance. The calling code (the code that executes the callback) will execute
-a generic overloaded @code{operator ()} of a generic functor to cause the callback
-to be called. The called code (the code that wants to be called back) will have
-to provide a specialized implementation of the @code{operator ()} that performs the
-class-specific work that caused the close-coupling problem above.
-
-With the specific functor and its overloaded @code{operator ()} created, the called
-code then gives the specialized code to the module that will execute the callback
-(the calling code).
-
-The calling code will take a generic functor as a parameter, so an implicit cast
-is done in the function call to convert the specific functor to a generic functor.
-This means that the calling module just needs to understand the generic functor
-type. It is decoupled from the calling code completely.
-
-The information one needs to make a specific functor is the object pointer and
-the pointer-to-method address.
-
-The essence of what needs to happen is that the system declares a generic part
-of the functor,
-
-@verbatim
- template <typename T>
- class Functor
- {
- public:
- virtual void operator() (T arg) = 0;
- };
-@end verbatim
-
-The caller defines a specific part of the functor that really is just there to
-implement the specific operator() method,
-
-@verbatim
- template <typename T, typename ARG>
- class SpecificFunctor : public Functor
- {
- public:
- SpecificFunctor(T* p, int (T::*_pmi)(ARG arg))
- {
- m_p = p;
- m_pmi = pmi;
- }
-
- virtual int operator() (ARG arg)
- {
- (*m_p.*m_pmi)(arg);
- }
- private:
- void (T::*m_pmi)(ARG arg);
- T* m_p;
- };
-@end verbatim
-
-@emph{N.B. The previous code is not real ns-3 code. It is simplistic example
-code used only to illustrate the concepts involved and to help you understand
-the system more. Do not expect to find this code anywhere in the ns-3 tree}
-
-Notice that there are two variables defined in the class above. The m_p
-variable is the object pointer and m_pmi is the variable containing the
-address of the function to execute.
-
-Notice that when @code{operator()} is called, it in turn calls the method provided
-with the object pointer using the C++ PMI syntax.
-
-To use this, one could then declare some model code that takes a generic functor
-as a parameter
-
-@verbatim
- void LibraryFunction (Functor functor);
-@end verbatim
-
-The code that will talk to the model would build a specific functor and pass it to
-@code{LibraryFunction},
-
-@verbatim
- MyClass myClass;
- SpecificFunctor<MyClass, int> functor (&myclass, MyClass::MyMethod);
-@end verbatim
-
-When @code{LibraryFunction} is done, it executes the callback using the
-@code{operator()} on the generic functor it was passed, and in this particular
-case, provides the integer argument:
-
-@verbatim
- void
- LibraryFunction (Functor functor)
- {
- // Execute the library function
- functor(1234);
- }
-@end verbatim
-
-Notice that @code{LibraryFunction} is completely decoupled from the specific
-type of the client. The connection is made through the Functor polymorphism.
-
-The Callback API in @command{ns-3} implements object-oriented callbacks using
-the functor mechanism. This callback API, being based on C++ templates, is
-type-safe; that is, it performs static type checks to enforce proper signature
-compatibility between callers and callees. It is therefore more type-safe to
-use than traditional function pointers, but the syntax may look imposing at
-first. This section is designed to walk you through the Callback system so
-that you can be comfortable using it in @command{ns-3}.
-
-@node Using the Callback API
-@section Using the Callback API
-
-The Callback API is fairly minimal, providing only two services:
-@itemize @bullet
-@item callback type declaration: a way to declare a type of callback
-with a given signature, and,
-@item callback instantiation: a way to instantiate a
-template-generated forwarding callback which can forward any calls
-to another C++ class member method or C++ function.
-@end itemize
-
-This is best observed via walking through an example, based on
-@code{samples/main-callback.cc}.
-
-@subsection Using the Callback API with static functions
-
-Consider a function:
-
-@verbatim
- static double
- CbOne (double a, double b)
- {
- std::cout << "invoke cbOne a=" << a << ", b=" << b << std::endl;
- return a;
- }
-@end verbatim
-
-Consider also the following main program snippet:
-
-@verbatim
- int main (int argc, char *argv[])
- {
- // return type: double
- // first arg type: double
- // second arg type: double
- Callback<double, double, double> one;
- }
-@end verbatim
-
-This is an example of a C-style callback -- one which does not include or need
-a @code{this} pointer. The function template @code{Callback} is essentially the
-declaration of the variable containing the pointer-to-function. In the example
-above, we explicitly showed a pointer to a function that returned an integer and
-took a single integer as a parameter, The @code{Callback} template function is
-a generic version of that -- it is used to declare the type of a callback.
-
-@strong{Note1:} Readers unfamiliar with C++ templates may consult
-@uref{http://www.cplusplus.com/doc/tutorial/templates/,,this reference}.
-
-The @code{Callback} template requires one mandatory argument (the return type
-of the function to be assigned to this callback) and up to five optional
-arguments, which each specify the type of the arguments (if your particular
-callback function has more than five arguments, then this can be handled
-by extending the callback implementation).
-
-So in the above example, we have a declared a callback named "one" that will
-eventually hold a function pointer. The signature of the function that it will
-hold must return double and must support two double arguments. If one tries
-to pass a function whose signature does not match the declared callback,
-a compilation error will occur. Also, if one tries to assign to a callback
-an incompatible one, compilation will succeed but a run-time
-NS_FATAL_ERROR will be raised. The sample program
-@command{samples/main-callback.cc} demonstrates both of these error cases
-at the end of the @command{main()} program.
-
-Now, we need to tie together this callback instance and the actual target function
-(CbOne). Notice above that CbOne has the same function signature types as the
-callback-- this is important. We can pass in any such properly-typed function
-to this callback. Let's look at this more closely:
-
-@verbatim
-static double CbOne (double a, double b) {}
- ^ ^ ^
- | ---| ------|
- | | |
-Callback<double, double, double> one;
-@end verbatim
-
-You can only bind a function to a callback if they have the matching signature.
-The first template argument is the return type, and the additional template
-arguments are the types of the arguments of the function signature.
-
-Now, let's bind our callback "one" to the function that matches its signature:
-
-@verbatim
- // build callback instance which points to cbOne function
- one = MakeCallback (&CbOne);
-@end verbatim
-
-This call to @code{MakeCallback} is, in essence, creating one of the specialized
-functors mentioned above. The variable declared using the @code{Callback}
-template function is going to be playing the part of the generic functor. The
-assignment @code{one = MakeCallback (&CbOne)} is the cast that converts the
-specialized functor known to the callee to a generic functor known to the caller.
-
-Then, later in the program, if the callback is needed, it can be used as follows:
-@verbatim
- NS_ASSERT (!one.IsNull ());
-
- // invoke cbOne function through callback instance
- double retOne;
- retOne = one (10.0, 20.0);
-@end verbatim
-
-The check for @code{IsNull()} ensures that the callback is not null -- that there
-is a function to call behind this callback. Then, @code{one()} executes the
-generic @code{operator()} which is really overloaded with a specific implementation
-of @code{operator()} and returns the same result as if @code{CbOne()} had been
-called directly.
-
-@subsection Using the Callback API with member functions
-
-Generally, you will not be calling static functions but instead public member
-functions of an object. In this case, an extra argument is needed to the
-MakeCallback function, to tell the system on which object the function should be
-invoked. Consider this example, also from main-callback.cc:
-
-@verbatim
- class MyCb {
- public:
- int CbTwo (double a) {
- std::cout << "invoke cbTwo a=" << a << std::endl;
- return -5;
- }
- };
-
- int main ()
- {
- ...
- // return type: int
- // first arg type: double
- Callback<int, double> two;
- MyCb cb;
- // build callback instance which points to MyCb::cbTwo
- two = MakeCallback (&MyCb::CbTwo, &cb);
- ...
- }
-@end verbatim
-
-Here, we pass an additional object pointer to the @code{MakeCallback<>} function.
-Recall from the background section above that @code{Operator()} will use the pointer to
-member syntax when it executes on an object:
-
-@verbatim
- virtual int operator() (ARG arg)
- {
- (*m_p.*m_pmi)(arg);
- }
-@end verbatim
-
-And so we needed to provide the two variables (@code{m_p} and @code{m_pmi}) when
-we made the specific functor. The line,
-
-@verbatim
- two = MakeCallback (&MyCb::CbTwo, &cb);
-@end verbatim
-
-does precisely that. In this case,
-
-When @code{two ()} is invoked,
-
-@verbatim
- int result = two (1.0);
-@end verbatim
-
-I will result in a call the @code{CbTwo} member function (method) on the object
-pointed to by @code{&cb}.
-
-@subsection Building Null Callbacks
-
-It is possible for callbacks to be null; hence it may be wise to
-check before using them. There is a special construct for a null
-callback, which is preferable to simply passing "0" as an argument;
-it is the @code{MakeNullCallback<>} construct:
-
-@verbatim
- two = MakeNullCallback<int, double> ();
- NS_ASSERT (two.IsNull ());
-@end verbatim
-
-Invoking a null callback is just like invoking a null function pointer: it will
-crash at runtime.
-
-@node Bound Callbacks
-@section Bound Callbacks
-
-A very useful extension to the functor concept is that of a Bound Callback.
-Previously it was mentioned that closures were originally function calls
-packaged up for later execution. Notice that in all of the Callback
-descriptions above, there is no way to package up any parameters for use
-later -- when the @code{Callback} is called via @code{operator()}. All of
-the parameters are provided by the calling function.
-
-What if it is desired to allow the client function (the one that provides the
-callback) to provide some of the parameters? @uref{http://erdani.com/book/main.html,,Alexandrescu} calls the process of
-allowing a client to specify one of the parameters @emph{binding}. One of the
-parameters of @code{operator()} has been bound (fixed) by the client.
-
-Some of our pcap tracing code provides a nice example of this. There is a
-function that needs to be called whenever a packet is received. This function
-calls an object that actually writes the packet to disk in the pcap file
-format. The signature of one of these functions will be,
-
-@verbatim
- static void SniffEvent (Ptr<PcapWriter> writer, Ptr<const Packet> packet);
-@end verbatim
-
-The static keyword means this is a static function which does not need a
-@code{this} pointer, so it will be using C-style callbacks. We don't want the
-calling code to have to know about anything but the Packet. What we want there
-is just a call that looks like,
-
-@verbatim
- m_promiscSnifferTrace (m_currentPkt);
-@end verbatim
-
-What we want to do is to @emph{bind} the @code{Ptr<PcapWriter> writer} to the
-specific callback implementation when it is created and arrange for the
-@code{operator()} of the Callback to provide that parameter for free.
-
-We provide the @code{MakeBoundCallback} template function for that purpose. It
-takes the same parameters as the @code{MakeCallback} template function but also
-takes the parameters to be bound. In the case of the example above,
-
-@verbatim
- MakeBoundCallback (&CsmaHelper::SniffEvent, pcap));
-@end verbatim
-
-will create a specific callback implementation that knows to add in the extra
-bound arguments. Conceptually, it extends the specific functor described above
-with one or more bound arguments
-
-@verbatim
- template <typename T, typename ARG, typename BOUND_ARG>
- class SpecificFunctor : public Functor
- {
- public:
- SpecificFunctor(T* p, int (T::*_pmi)(ARG arg), BOUND_ARG boundArg)
- {
- m_p = p;
- m_pmi = pmi;
- m_boundArg = boundArg;
- }
-
- virtual int operator() (ARG arg)
- {
- (*m_p.*m_pmi)(m_boundArg, arg);
- }
- private:
- void (T::*m_pmi)(ARG arg);
- T* m_p;
- BOUND_ARG m_boundArg;
- };
-@end verbatim
-
-You can see that when the specific functor is created, the bound argument is saved
-in the functor / callback object itself. When the @code{operator()} is invoked with
-the single parameter, as in
-
-@verbatim
- m_promiscSnifferTrace (m_currentPkt);
-@end verbatim
-
-the implementation of @code{operator()} adds the bound parameter into the actual
-function call:
-
-@verbatim
- (*m_p.*m_pmi)(m_boundArg, arg);
-@end verbatim
-
-@node Traced Callbacks
-@section Traced Callbacks
-@cartouche
-Placeholder subsection
-@end cartouche
-
-@node Callback locations in ns-3
-@section Callback locations in @command{ns-3}
-
-Where are callbacks frequently used in @command{ns-3}? Here are some of the
-more visible ones to typical users:
-
-@itemize @bullet
-@item Socket API
-@item Layer-2/Layer-3 API
-@item Tracing subsystem
-@item API between IP and routing subsystems
-@end itemize
-
-@node Implementation details
-@section Implementation details
-
-The code snippets above are simplistic and only designed to illustrate the mechanism
-itself. The actual Callback code is quite complicated and very template-intense and
-a deep understanding of the code is not required. If interested, expert users may
-find the following useful:
-
-The code was originally written based on the techniques described in
-@uref{http://www.codeproject.com/cpp/TTLFunction.asp,,
-http://www.codeproject.com/cpp/TTLFunction.asp}.
-It was subsequently rewritten to follow the architecture outlined in
-@uref{http://www.amazon.com/Modern-C\%2B\%2B-Design-Programming-Patterns/dp/0201704315/ref=pd_bbs_sr_1/102-0157303-1900156?ie=UTF8\&s=books\&qid=1187982662\&sr=1-1,,Modern C++ Design: Generic Programming and Design Patterns Applied-- Alexandrescu}, chapter 5, "Generalized Functors".
-
-This code uses:
-@itemize @bullet
-@item default template parameters to saves users from having to
-specify empty parameters when the number of parameters
-is smaller than the maximum supported number
-@item the pimpl idiom: the Callback class is passed around by
-value and delegates the crux of the work to its pimpl pointer.
-@item two pimpl implementations which derive from CallbackImpl
-FunctorCallbackImpl can be used with any functor-type
-while MemPtrCallbackImpl can be used with pointers to
-member functions.
-@item a reference list implementation to implement the Callback's
-value semantics.
-@end itemize
-
-This code most notably departs from the Alexandrescu implementation in that it
-does not use type lists to specify and pass around the types of the callback
-arguments. Of course, it also does not use copy-destruction semantics and
-relies on a reference list rather than autoPtr to hold the pointer.
--- a/doc/manual/csma.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,338 +0,0 @@
-@node CSMA NetDevice
-@chapter CSMA NetDevice
-
-This is the introduction to CSMA NetDevice chapter, to complement the
-Csma model doxygen.
-
-@menu
-* Overview of the CSMA model::
-* CSMA Channel Model::
-* CSMA Net Device Model::
-* Using the CsmaNetDevice::
-* CSMA Tracing::
-@end menu
-
-@node Overview of the CSMA model
-@section Overview of the CSMA model
-
-The ns-3 CSMA device models a simple bus network in the spirit of Ethernet.
-Although it does not model any real physical network you could ever build
-or buy, it does provide some very useful functionality.
-
-Typically when one thinks of a bus network Ethernet or IEEE 802.3 comes to
-mind. Ethernet uses CSMA/CD (Carrier Sense Multiple Access with Collision
-Detection with exponentially increasing backoff to contend for the shared
-transmission medium. The ns-3 CSMA device models only a portion of this
-process, using the nature of the globally available channel to provide
-instantaneous (faster than light) carrier sense and priority-based
-collision "avoidance." Collisions in the sense of Ethernet never happen and
-so the ns-3 CSMA device does not model collision detection, nor will any
-transmission in progress be "jammed."
-
-@subsection CSMA Layer Model
-
-There are a number of conventions in use for describing layered
-communications architectures in the literature and in textbooks. The most
-common layering model is the ISO seven layer reference model. In this view
-the CsmaNetDevice and CsmaChannel pair occupies the lowest two
-layers -- at the physical (layer one), and data link (layer two) positions.
-Another important reference model is that specified by RFC 1122,
-"Requirements for Internet Hosts -- Communication Layers." In this view the
-CsmaNetDevice and CsmaChannel pair occupies the lowest layer --
-the link layer. There is also a seemingly endless litany of alternative
-descriptions found in textbooks and in the literature. We adopt the naming
-conventions used in the IEEE 802 standards which speak of LLC, MAC, MII
-and PHY layering. These acronyms are defined as:
-
-@itemize @bullet
-@item LLC: Logical Link Control;
-@item MAC: Media Access Control;
-@item MII: Media Independent Interface;
-@item PHY: Physical Layer.
-@end itemize
-
-In this case the @emph{LLC} and @emph{MAC }are sublayers of the OSI data link
-layer and the @emph{MII} and @emph{PHY} are sublayers of the OSI physical layer.
-
-The "top" of the CSMA device defines the transition from the network layer
-to the data link layer. This transition is performed by higher layers by
-calling either CsmaNetDevice::Send or CsmaNetDevice::SendFrom.
-
-In contrast to the IEEE 802.3 standards, there is no precisely specified
-PHY in the CSMA model in the sense of wire types, signals or pinouts. The
-"bottom" interface of the CsmaNetDevice can be thought of as as a kind
-of Media Independent Interface (MII) as seen in the "Fast Ethernet"
-(IEEE 802.3u) specifications. This MII interface fits into a corresponding
-media independent interface on the CsmaChannel. You will not find the
-equivalent of a 10BASE-T or a 1000BASE-LX PHY.
-
-The CsmaNetDevice calls the CsmaChannel through a media independent
-interface. There is a method defined to tell the channel when to start
-"wiggling the wires" using the method CsmaChannel::TransmitStart, and
-a method to tell the channel when the transmission process is done and
-the channel should begin propagating the last bit across the "wire":
-CsmaChannel::TransmitEnd.
-
-When the TransmitEnd method is executed, the channel will model a single
-uniform signal propagation delay in the medium and deliver copes of the packet
-to each of the devices attached to the packet via the
-CsmaNetDevice::Receive method.
-
-There is a "pin" in the device media independent interface corresponding to
-"COL" (collision). The state of the channel may be sensed by calling
-CsmaChannel::GetState. Each device will look at this "pin" before
-starting a send and will perform appropriate backoff operations if required.
-
-Properly received packets are forwarded up to higher levels from the
-CsmaNetDevice via a callback mechanism. The callback function is
-initialized by the higher layer (when the net device is attached) using
-CsmaNetDevice::SetReceiveCallback and is invoked upon "proper"
- reception of a packet by the net device in order to forward the packet up
-the protocol stack.
-
-@node CSMA Channel Model
-@section CSMA Channel Model
-
-The class CsmaChannel models the actual transmission medium.
-There is no fixed limit for the number of devices connected to the channel.
-The CsmaChannel models a data rate and a speed-of-light delay which can
-be accessed via the attributes "DataRate" and "Delay" respectively.
-The data rate provided to the channel is used to set the data rates
-used by the transmitter sections of the CSMA devices connected to the
-channel. There is no way to independently set data rates in the
-devices. Since the data rate is only used to calculate a delay time, there
-is no limitation (other than by the data type holding the value) on the
-speed at which CSMA channels and devices can operate; and no restriction
-based on any kind of PHY characteristics.
-
-The CsmaChannel has three states, @code{IDLE}, @code{TRANSMITTING} and
-@code{PROPAGATING}. These three states are "seen" instantaneously by all
-devices on the channel. By this we mean that if one device begins or ends a
-simulated transmission, all devices on the channel are @emph{immediately}
-aware of the change in state. There is no time during which one device may
-see an @code{IDLE} channel while another device physically further away in
-the collision domain may have begun transmitting with the associated signals
-not propagated down the channel to other devices. Thus there is no need for
-collision detection in the CsmaChannel model and it is not implemented in any
-way.
-
-We do, as the name indicates, have a Carrier Sense aspect to the model.
-Since the simulator is single threaded, access to the common channel will
-be serialized by the simulator. This provides a deterministic mechanism
-for contending for the channel. The channel is allocated (transitioned from
-state @code{IDLE} to state @code{TRANSMITTING}) on a first-come first-served
-basis. The channel always goes through a three state process:
-
-@verbatim
- IDLE -> TRANSMITTING -> PROPAGATING -> IDLE
-@end verbatim
-
-The @code{TRANSMITTING} state models the time during which the source net device
-is actually wiggling the signals on the wire. The @code{PROPAGATING} state
-models the time after the last bit was sent, when the signal is propagating down
-the wire to the "far end."
-
-The transition to the @code{TRANSMITTING} state is driven by a call to
-CsmaChannel::TransmitStart which is called by the net device that
-transmits the packet. It is the responsibility of that device to end the
-transmission with a call to CsmaChannel::TransmitEnd at the appropriate
-simulation time that reflects the time elapsed to put all of the packet bits
-on the wire. When TransmitEnd is called, the channel schedules an event
-corresponding to a single speed-of-light delay. This delay applies to all
-net devices on the channel identically. You can think of a symmetrical hub
-in which the packet bits propagate to a central location and then back out
-equal length cables to the other devices on the channel. The single ``speed
-of light'' delay then corresponds to the time it takes for: 1) a signal to
-propagate from one CsmaNetDevice through its cable to the hub; plus 2) the
-time it takes for the hub to forward the packet out a port; plus 3) the time
-it takes for the signal in question to propagate to the destination net
-device.
-
-The CsmaChannel models a broadcast medium so the packet is delivered
-to all of the devices on the channel (including the source) at the end of
-the propagation time. It is the responsibility of the sending device to
-determine whether or not it receives a packet broadcast over the channel.
-
-The CsmaChannel provides following Attributes:
-
-@itemize @bullet
-@item DataRate: The bitrate for packet transmission on connected devices;
-@item Delay: The speed of light transmission delay for the channel.
-@end itemize
-
-@node CSMA Net Device Model
-@section CSMA Net Device Model
-
- The CSMA network device appears somewhat like an Ethernet device. The
- CsmaNetDevice provides following Attributes:
-
-@itemize @bullet
-@item Address: The Mac48Address of the device;
-@item SendEnable: Enable packet transmission if true;
-@item ReceiveEnable: Enable packet reception if true;
-@item EncapsulationMode: Type of link layer encapsulation to use;
-@item RxErrorModel: The receive error model;
-@item TxQueue: The transmit queue used by the device;
-@item InterframeGap: The optional time to wait between "frames";
-@item Rx: A trace source for received packets;
-@item Drop: A trace source for dropped packets.
-@end itemize
-
-The CsmaNetDevice supports the assignment of a "receive error model."
-This is an ErrorModel object that is used to simulate data corruption
-on the link.
-
-Packets sent over the CsmaNetDevice are always routed through the
-transmit queue to provide a trace hook for packets sent out over the
-network. This transmit queue can be set (via attribute) to model different
-queuing strategies.
-
-Also configurable by attribute is the encapsulation method used by the
-device. Every packet gets an EthernetHeader that includes the
-destination and source MAC addresses, and a length/type field. Every packet
-also gets an EthernetTrailer which includes the FCS. Data in the
-packet may be encapsulated in different ways.
-
-By default, or by setting the "EncapsulationMode" attribute to "Dix", the
-encapsulation is according to the DEC, Intel, Xerox standard. This is sometimes
-called EthernetII framing and is the familiar destination MAC, source MAC,
-EtherType, Data, CRC format.
-
-If the "EncapsulationMode" attribute is set to "Llc", the encapsulation is by
-LLC SNAP. In this case, a SNAP header is added that contains the EtherType
-(IP or ARP).
-
-The other implemented encapsulation modes are IP_ARP (set "EncapsulationMode" to
-"IpArp") in which the length type of the Ethernet header receives the protocol
-number of the packet; or ETHERNET_V1 (set "EncapsulationMode" to "EthernetV1")
-in which the length type of the Ethernet header receives the length of the packet.
-A "Raw" encapsulation mode is defined but not implemented -- use of the RAW mode
-results in an assertion.
-
-Note that all net devices on a channel must be set to the same encapsulation mode
-for correct results. The encapsulation mode is not sensed at the receiver.
-
-The CsmaNetDevice implements a random exponential backoff algorithm
-that is executed if the channel is determined to be busy (@code{TRANSMITTING} or
-@code{PPROPAGATING}) when the device wants to start propagating. This results in a
-random delay of up to pow (2, retries) - 1 microseconds before a retry is
-attempted. The default maximum number of retries is 1000.
-
-@node Using the CsmaNetDevice
-@section Using the CsmaNetDevice
-
-The CSMA net devices and channels are typically created and configured using
-the associated @code{CsmaHelper} object. The various ns3 device helpers
-generally work in a similar way, and their use is seen in many of our example
-programs.
-
-The conceptual model of interest is that of a bare computer ``husk'' into which
-you plug net devices. The bare computers are created using a @code{NodeContainer}
-helper. You just ask this helper to create as many computers (we call them
-@code{Nodes}) as you need on your network:
-
-@verbatim
- NodeContainer csmaNodes;
- csmaNodes.Create (nCsmaNodes);
-@end verbatim
-
-Once you have your nodes, you need to instantiate a @code{CsmaHelper} and set
-any attributes you may want to change.
-
-@verbatim
- CsmaHelper csma;
- csma.SetChannelAttribute ("DataRate", StringValue ("100Mbps"));
- csma.SetChannelAttribute ("Delay", TimeValue (NanoSeconds (6560)));
-
- csma.SetDeviceAttribute ("EncapsulationMode", StringValue ("Dix"));
- csma.SetDeviceAttribute ("FrameSize", UintegerValue (2000));
-@end verbatim
-
-Once the attributes are set, all that remains is to create the devices
-and install them on the required nodes, and to connect the devices
-together using a CSMA channel. When we create the net devices, we add
-them to a container to allow you to use them in the future. This all
-takes just one line of code.
-
-@verbatim
- NetDeviceContainer csmaDevices = csma.Install (csmaNodes);
-@end verbatim
-
-@node CSMA Tracing
-@section CSMA Tracing
-
-Like all ns-3 devices, the CSMA Model provides a number of trace sources.
-These trace sources can be hooked using your own custom trace code, or you
-can use our helper functions to arrange for tracing to be enabled on devices
-you specify.
-
-@subsection Upper-Level (MAC) Hooks
-
-From the point of view of tracing in the net device, there are several
-interesting points to insert trace hooks. A convention inherited from other
-simulators is that packets destined for transmission onto attached networks
-pass through a single "transmit queue" in the net device. We provide trace
-hooks at this point in packet flow, which corresponds (abstractly) only to a
-transition from the network to data link layer, and call them collectively
-the device MAC hooks.
-
-When a packet is sent to the CSMA net device for transmission it always
-passes through the transmit queue. The transmit queue in the
-CsmaNetDevice inherits from Queue, and therefore inherits three
-trace sources:
-
-@itemize @bullet
-@item An Enqueue operation source (see Queue::m_traceEnqueue);
-@item A Dequeue operation source (see Queue::m_traceDequeue);
-@item A Drop operation source (see Queue::m_traceDrop).
-@end itemize
-
-The upper-level (MAC) trace hooks for the CsmaNetDevice are, in fact,
-exactly these three trace sources on the single transmit queue of the device.
-
-The m_traceEnqueue event is triggered when a packet is placed on the transmit
-queue. This happens at the time that CsmaNetDevice::Send or
-CsmaNetDevice::SendFrom is called by a higher layer to queue a packet for
-transmission.
-
-The m_traceDequeue event is triggered when a packet is removed from the
-transmit queue. Dequeues from the transmit queue can happen in three
-situations: 1) If the underlying channel is idle when the
-CsmaNetDevice::Send or CsmaNetDevice::SendFrom is called, a packet
-is dequeued from the transmit queue and immediately transmitted; 2) If the
-underlying channel is idle, a packet may be dequeued and immediately
-transmitted in an internal TransmitCompleteEvent that functions much
-like a transmit complete interrupt service routine; or 3) from
-the random exponential backoff handler if a timeout is detected.
-
-Case (3) implies that a packet is dequeued from the transmit queue if it is
-unable to be transmitted according to the backoff rules. It is important
-to understand that this will appear as a Dequeued packet and it is easy to
-incorrectly assume that the packet was transmitted since it passed through
-the transmit queue. In fact, a packet is actually dropped by the net device
-in this case. The reason for this behavior is due to the definition of the
-Queue Drop event. The m_traceDrop event is, by definition, fired when a
-packet cannot be enqueued on the transmit queue because it is full. This
-event only fires if the queue is full and we do not overload this event
-to indicate that the CsmaChannel is "full."
-
-@subsection Lower-Level (PHY) Hooks
-
-Similar to the upper level trace hooks, there are trace hooks available at
-the lower levels of the net device. We call these the PHY hooks. These
-events fire from the device methods that talk directly to the CsmaChannel.
-
-The trace source m_dropTrace is called to indicate a packet that is dropped
-by the device. This happens in two cases: First, if the receive side of
-the net device is not enabled (see CsmaNetDevice::m_receiveEnable and the
-associated attribute "ReceiveEnable").
-
-The m_dropTrace is also used to indicate that a packet was discarded as
-corrupt if a receive error model is used (see
-CsmaNetDevice::m_receiveErrorModel and the associated attribute
-"ReceiveErrorModel").
-
-The other low-level trace source fires on reception of an accepted packet
-(see CsmaNetDevice::m_rxTrace). A packet is accepted if it is destined
-for the broadcast address, a multicast address, or to the MAC address
-assigned to the net device.
--- a/doc/manual/distributed.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,225 +0,0 @@
-@node Distributed
-@chapter Distributed Simulation with MPI
-@anchor{chap:Distributed}
-
-@menu
-* Current Implementation Details::
-* Running Distributed Simulations::
-* Tracing During Distributed Simulations::
-@end menu
-
-Parallel and distributed discrete event simulation allows the execution of a
-single simulation program on multiple processors. By splitting up the
-simulation into logical processes, LPs, each LP can be executed by a different
-processor. This simulation methodology enables very large-scale simulations by
-leveraging increased processing power and memory availability. In order to
-ensure proper execution of a distributed simulation, message passing between
-LPs is required. To support distributed simulation in ns-3, the standard
-Message Passing Interface (MPI) is used, along with a new distributed simulator
-class. Currently, dividing a simulation for distributed purposes in ns-3 can
-only occur across point-to-point links.
-
-@node Current Implementation Details
-@section Current Implementation Details
-During the course of a distributed simulation, many packets must cross
-simulator boundaries. In other words, a packet that originated on one LP
-is destined for a different LP, and in order to make this transition, a message
-containing the packet contents must be sent to the remote LP. Upon receiving
-this message, the remote LP can rebuild the packet and proceed as normal. The
-process of sending an receiving messages between LPs is handled easily by the
-new MPI interface in ns-3.
-
-Along with simple message passing between LPs, a distributed simulator is used
-on each LP to determine which events to process. It is important to process
-events in time-stamped order to ensure proper simulation execution. If a
-LP receives a message containing an event from the past, clearly this is an
-issue, since this event could change other events which have already been
-executed. To address this problem, a conservative synchronization algorithm with
-lookahead is used in ns-3. For more information on different synchronization
-approaches and parallel and distributed simulation in general, please refer to
-"Parallel and Distributed Simulation Systems" by Richard Fujimoto.
-
-@subsection Remote point-to-point links
-As described in the introduction, dividing a simulation for distributed purposes
-in ns-3 currently can only occur across point-to-point links; therefore, the idea
-of remote point-to-point links is very important for distributed simulation in ns-3.
-When a point-to-point link is installed, connecting two nodes, the point-to-point
-helper checks the system id, or rank, of both nodes. The rank should be assigned
-during node creation for distributed simulation and is intended to signify on which
-LP a node belongs. If the two nodes are on the same rank, a regular point-to-point
-link is created. If, however, the two nodes are on different ranks, then these nodes
-are intended for different LPs, and a remote point-to-point link is used. If a packet
-is to be sent across a remote point-to-point link, MPI is used to send the message to
-the remote LP.
-
-@subsection Distributing the topology
-Currently, the full topology is created on each rank, regardless of the individual node
-system ids. Only the applications are specific to a rank. For example, consider
-node 1 on LP 1 and node 2 on LP 2, with a traffic generator on node 1. Both node
-1 and node 2 will be created on both LP1 and LP2; however, the traffic generator
-will only be installed on LP1. While this is not optimal for memory efficiency, it
-does simplify routing, since all current routing implementations in ns-3 will work
-with distributed simulation.
-
-@node Running Distributed Simulations
-@section Running Distributed Simulations
-
-@subsection Prerequisites
-Ensure that MPI is installed, as well as mpic++. In Ubuntu repositories,
-these are openmpi-bin, openmpi-common, openmpi-doc, libopenmpi-dev. In
-Fedora, these are openmpi and openmpi-devel.
-
-Note:
-There is a conflict on some Fedora systems between libotf and openmpi. A
-possible "quick-fix" is to yum remove libotf before installing openmpi.
-This will remove conflict, but it will also remove emacs. Alternatively,
-these steps could be followed to resolve the conflict:
-
-@verbatim
-1) Rename the tiny otfdump which emacs says it needs:
-
- mv /usr/bin/otfdump /usr/bin/otfdump.emacs-version
-
-2) Manually resolve openmpi dependencies:
-
- sudo yum install libgfortran libtorque numactl
-
-3) Download rpm packages:
-
- openmpi-1.3.1-1.fc11.i586.rpm
- openmpi-devel-1.3.1-1.fc11.i586.rpm
- openmpi-libs-1.3.1-1.fc11.i586.rpm
- openmpi-vt-1.3.1-1.fc11.i586.rpm
-
- from
-
- http://mirrors.kernel.org/fedora/releases/11/Everything/i386/os/Packages/
-
-4) Force the packages in:
-
- sudo rpm -ivh --force openmpi-1.3.1-1.fc11.i586.rpm
- openmpi-libs-1.3.1-1.fc11.i586.rpm openmpi-devel-1.3.1-1.fc11.i586.rpm
- openmpi-vt-1.3.1-1.fc11.i586.rpm
-
-@end verbatim
-
-Also, it may be necessary to add the openmpi bin directory to PATH in order to
-execute mpic++ and mpirun from the command line. Alternatively, the full path
-to these executables can be used. Finally, if openmpi complains about the
-inability to open shared libraries, such as libmpi_cxx.so.0, it may be
-necessary to add the openmpi lib directory to LD_LIBRARY_PATH.
-
-@subsection Building and Running Examples
-If you already built ns-3 without MPI enabled, you must re-build:
-@verbatim
-./waf distclean
-@end verbatim
-
-Configure ns-3 with the --enable-mpi option:
-@verbatim
-./waf -d debug configure --enable-mpi
-@end verbatim
-
-Ensure that MPI is enabled by checking the optional features shown from the
-output of configure.
-
-Next, build ns-3:
-@verbatim
-./waf
-@end verbatim
-
-After building ns-3 with mpi enabled, the example programs are now ready to
-run with mpirun. Here are a few examples (from the root ns-3 directory):
-
-@verbatim
-mpirun -np 2 ./waf --run simple-distributed
-mpirun -np 4 -machinefile mpihosts ./waf --run 'nms-udp-nix --LAN=2 --CN=4 --nix=1'
-@end verbatim
-
-The np switch is the number of logical processors to use. The
-machinefile switch is which machines to use. In order to use machinefile,
-the target file must exist (in this case mpihosts). This can simply contain
-something like:
-
-@verbatim
-localhost
-localhost
-localhost
-...
-@end verbatim
-
-Or if you have a cluster of machines, you can name them.
-
-** NOTE: Some users have experienced issues using mpirun and waf together.
-An alternative way to run distributed examples is shown below:
-
-@verbatim
-./waf shell
-cd build/debug
-mpirun -np 2 examples/mpi/simple-distributed
-@end verbatim
-
-@subsection Creating custom topologies
-The example programs in examples/mpi give a good idea of how to create
-different topologies for distributed simulation. The main points are
-assigning system ids to individual nodes, creating point-to-point
-links where the simulation should be divided, and installing
-applications only on the LP associated with the target node.
-
-Assigning system ids to nodes is simple and can be handled two different
-ways. First, a NodeContainer can be used to create the nodes and assign
-system ids:
-
-@verbatim
-NodeContainer nodes;
-nodes.Create (5, 1); // Creates 5 nodes with system id 1.
-@end verbatim
-
-Alternatively, nodes can be created individually, assigned system ids, and
-added to a NodeContainer. This is useful if a NodeContainer holds nodes with
-different system ids:
-
-@verbatim
-NodeContainer nodes;
-Ptr<Node> node1 = CreateObject<Node> (0); // Create node1 with system id 0
-Ptr<Node> node2 = CreateObject<Node> (1); // Create node2 with system id 1
-nodes.Add (node1);
-nodes.Add (node2);
-@end verbatim
-
-Next, where the simulation is divided is determined by the placement of
-point-to-point links. If a point-to-point link is created between two
-nodes with different system ids, a remote point-to-point link is created,
-as described in @ref{Current Implementation Details}.
-
-Finally, installing applications only on the LP associated with the target
-node is very important. For example, if a traffic generator is to be placed
-on node 0, which is on LP0, only LP0 should install this application.
-This is easily accomplished by first checking the simulator system id, and
-ensuring that it matches the system id of the target node before installing
-the application.
-
-@node Tracing During Distributed Simulations
-@section Tracing During Distributed Simulations
-Depending on the system id (rank) of the simulator, the information traced
-will be different, since traffic originating on one simulator is not seen
-by another simulator until it reaches nodes specific to that simulator. The
-easiest way to keep track of different traces is to just name the trace files
-or pcaps differently, based on the system id of the simulator. For example,
-something like this should work well, assuming all of these local variables
-were previously defined:
-
-@verbatim
-if (MpiInterface::GetSystemId () == 0)
- {
- pointToPoint.EnablePcapAll ("distributed-rank0");
- phy.EnablePcap ("distributed-rank0", apDevices.Get (0));
- csma.EnablePcap ("distributed-rank0", csmaDevices.Get (0), true);
- }
-else if (MpiInterface::GetSystemId () == 1)
- {
- pointToPoint.EnablePcapAll ("distributed-rank1");
- phy.EnablePcap ("distributed-rank1", apDevices.Get (0));
- csma.EnablePcap ("distributed-rank1", csmaDevices.Get (0), true);
- }
-@end verbatim
--- a/doc/manual/emu.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,288 +0,0 @@
-@node Emu NetDevice
-@chapter Emu NetDevice
-
-@section Behavior
-
-The @code{Emu} net device allows a simulation node to send and receive packets
-over a real network. The emulated net device relies on a specified interface
-being in promiscuous mode. It opens a raw socket and binds to that interface.
-We perform MAC spoofing to separate simulation network traffic from other
-network traffic that may be flowing to and from the host.
-
-One can use the @code{Emu} net device in a testbed situation where the
-host on which the simulation is running has a specific interface of interest
-which drives the testbed hardware. You would also need to set this specific
-interface into promiscuous mode and provide an appropriate device name to the
-ns-3 emulated net device. An example of this environment is the ORBIT testbed
-as described above.
-
-The @code{Emu} net device only works if the underlying interface is up and in
-promiscuous mode. Packets will be sent out over the device, but we use MAC
-spoofing. The MAC addresses will be generated (by default) using the
-Organizationally Unique Identifier (OUI) 00:00:00 as a base. This vendor code
-is not assigned to any organization and so should not conflict with any real
-hardware.
-
-It is always up to the user to determine that using these MAC addresses is
-okay on your network and won't conflict with anything else (including another
-simulation using @code{Emu} devices) on your network. If you are using the
-emulated net device in separate simulations you must consider global MAC
-address assignment issues and ensure that MAC addresses are unique across
-all simulations. The emulated net device respects the MAC address provided
-in the @code{SetAddress} method so you can do this manually. For larger
-simulations, you may want to set the OUI in the MAC address allocation function.
-
-IP addresses corresponding to the emulated net devices are the addresses
-generated in the simulation, which are generated in the usual way via helper
-functions. Since we are using MAC spoofing, there will not be a conflict
-between ns-3 network stacks and any native network stacks.
-
-The emulated net device comes with a helper function as all ns-3 devices do.
-One unique aspect is that there is no channel associated with the underlying
-medium. We really have no idea what this external medium is, and so have not
-made an effort to model it abstractly. The primary thing to be aware of is the
-implication this has for IPv4 global routing. The global router module
-attempts to walk the channels looking for adjacent networks. Since there
-is no channel, the global router will be unable to do this and you must then
-use a dynamic routing protocol such as OLSR to include routing in
-@code{Emu}-based networks.
-
-@section Usage
-
-Any mixing of ns-3 objects with real objects will typically require that
-ns-3 compute checksums in its protocols. By default, checksums are not
-computed by ns-3. To enable checksums (e.g. UDP, TCP, IP), users must set
-the attribute @code{ChecksumEnabled} to true, such as follows:
-@verbatim
-GlobalValue::Bind ("ChecksumEnabled", BooleanValue (true));
-@end verbatim
-
-The usage of the @code{Emu} net device is straightforward once the network of
-simulations has been configured. Since most of the work involved in working
-with this device is in network configuration before even starting a simulation,
-you may want to take a moment to review a couple of HOWTO pages on the ns-3 wiki
-that describe how to set up a virtual test network using VMware and how to run
-a set of example (client server) simulations that use @code{Emu} net devices.
-
-@itemize @bullet
-@item @uref{http://www.nsnam.org/wiki/index.php/HOWTO_use_VMware_to_set_up_virtual_networks_(Windows)}
-@item @uref{http://www.nsnam.org/wiki/index.php/HOWTO_use_ns-3_scripts_to_drive_real_hardware_(experimental)}
-@end itemize
-
-Once you are over the configuration hurdle, the script changes required to use
-an @code{Emu} device are trivial. The main structural difference is that you
-will need to create an ns-3 simulation script for each node. In the case of
-the HOWTOs above, there is one client script and one server script. The only
-``challenge'' is to get the addresses set correctly.
-
-Just as with all other ns-3 net devices, we provide a helper class for the
-@code{Emu} net device. The following code snippet illustrates how one would
-declare an EmuHelper and use it to set the ``DeviceName'' attribute to ``eth1''
-and install @code{Emu} devices on a group of nodes. You would do this on both
-the client and server side in the case of the HOWTO seen above.
-
-@verbatim
- EmuHelper emu;
- emu.SetAttribute ("DeviceName", StringValue ("eth1"));
- NetDeviceContainer d = emu.Install (n);
-@end verbatim
-
-The only other change that may be required is to make sure that the address
-spaces (MAC and IP) on the client and server simulations are compatible. First
-the MAC address is set to a unique well-known value in both places (illustrated
-here for one side).
-
-@verbatim
- //
- // We've got the devices in place. Since we're using MAC address
- // spoofing under the sheets, we need to make sure that the MAC addresses
- // we have assigned to our devices are unique. Ns-3 will happily
- // automatically assign the same MAC address to the devices in both halves
- // of our two-script pair, so let's go ahead and just manually change them
- // to something we ensure is unique.
- //
- Ptr<NetDevice> nd = d.Get (0);
- Ptr<EmuNetDevice> ed = nd->GetObject<EmuNetDevice> ();
- ed->SetAddress ("00:00:00:00:00:02");
-@end verbatim
-
-And then the IP address of the client or server is set in the usual way using
-helpers.
-
-@verbatim
- //
- // We've got the "hardware" in place. Now we need to add IP addresses.
- // This is the server half of a two-script pair. We need to make sure
- // that the addressing in both of these applications is consistent, so
- // we use provide an initial address in both cases. Here, the client
- // will reside on one machine running ns-3 with one node having ns-3
- // with IP address "10.1.1.2" and talk to a server script running in
- // another ns-3 on another computer that has an ns-3 node with IP
- // address "10.1.1.3"
- //
- Ipv4AddressHelper ipv4;
- ipv4.SetBase ("10.1.1.0", "255.255.255.0", "0.0.0.2");
- Ipv4InterfaceContainer i = ipv4.Assign (d);
-@end verbatim
-
-You will use application helpers to generate traffic exactly as you do in any
-ns-3 simulation script. Note that the server address shown below in a snippet
-from the client, must correspond to the IP address assigned to the server node
-similarly to the snippet above.
-
-@verbatim
- uint32_t packetSize = 1024;
- uint32_t maxPacketCount = 2000;
- Time interPacketInterval = Seconds (0.001);
- UdpEchoClientHelper client ("10.1.1.3", 9);
- client.SetAttribute ("MaxPackets", UintegerValue (maxPacketCount));
- client.SetAttribute ("Interval", TimeValue (interPacketInterval));
- client.SetAttribute ("PacketSize", UintegerValue (packetSize));
- ApplicationContainer apps = client.Install (n.Get (0));
- apps.Start (Seconds (1.0));
- apps.Stop (Seconds (2.0));
-@end verbatim
-
-The @code{Emu} net device and helper provide access to ASCII and pcap tracing
-functionality just as other ns-3 net devices to. You enable tracing similarly
-to these other net devices:
-
-@verbatim
- EmuHelper::EnablePcapAll ("emu-udp-echo-client");
-@end verbatim
-
-To see an example of a client script using the @code{Emu} net device, see
-@code{examples/emu-udp-echo-client.cc} and @code{examples/emu-udp-echo-server.cc}
-in the repository @uref{http://code.nsnam.org/craigdo/ns-3-emu/}.
-
-@section Implementation
-
-Perhaps the most unusual part of the @code{Emu} and @code{Tap} device
-implementation relates to the requirement for executing some of the code
-with super-user permissions. Rather than force the user to execute the entire
-simulation as root, we provide a small ``creator'' program that runs as root
-and does any required high-permission sockets work.
-
-We do a similar thing for both the @code{Emu} and the @code{Tap} devices.
-The high-level view is that the @code{CreateSocket} method creates a local
-interprocess (Unix) socket, forks, and executes the small creation program.
-The small program, which runs as suid root, creates a raw socket and sends
-back the raw socket file descriptor over the Unix socket that is passed to
-it as a parameter. The raw socket is passed as a control message (sometimes
-called ancillary data) of type SCM_RIGHTS.
-
-The @code{Emu} net device uses the ns-3 threading and multithreaded real-time
-scheduler extensions. The interesting work in the @code{Emu} device is done
-when the net device is started (@code{EmuNetDevice::StartDevice ()}). An
-attribute (``Start'') provides a simulation time at which to spin up the
-net device. At this specified time (which defaults to t=0), the socket
-creation function is called and executes as described above. You may also
-specify a time at which to stop the device using the ``Stop'' attribute.
-
-Once the (promiscuous mode) socket is created, we bind it to an interface name
-also provided as an attribute (``DeviceName'') that is stored internally as
-@code{m_deviceName}:
-
-@verbatim
- struct ifreq ifr;
- bzero (&ifr, sizeof(ifr));
- strncpy ((char *)ifr.ifr_name, m_deviceName.c_str (), IFNAMSIZ);
-
- int32_t rc = ioctl (m_sock, SIOCGIFINDEX, &ifr);
-
- struct sockaddr_ll ll;
- bzero (&ll, sizeof(ll));
-
- ll.sll_family = AF_PACKET;
- ll.sll_ifindex = m_sll_ifindex;
- ll.sll_protocol = htons(ETH_P_ALL);
-
- rc = bind (m_sock, (struct sockaddr *)&ll, sizeof (ll));
-@end verbatim
-
-After the promiscuous raw socket is set up, a separate thread is spawned to do
-reads from that socket and the link state is set to @code{Up}.
-
-@verbatim
- m_readThread = Create<SystemThread> (
- MakeCallback (&EmuNetDevice::ReadThread, this));
- m_readThread->Start ();
-
- NotifyLinkUp ();
-@end verbatim
-
-The @code{EmuNetDevice::ReadThread} function basically just sits in an infinite
-loop reading from the promiscuous mode raw socket and scheduling packet
-receptions using the real-time simulator extensions.
-
-@verbatim
- for (;;)
- {
- ...
-
- len = recvfrom (m_sock, buf, bufferSize, 0, (struct sockaddr *)&addr,
- &addrSize);
-
- ...
-
- DynamicCast<RealtimeSimulatorImpl> (Simulator::GetImplementation ())->
- ScheduleRealtimeNow (
- MakeEvent (&EmuNetDevice::ForwardUp, this, buf, len));
-
- ...
- }
-@end verbatim
-
-The line starting with our templated DynamicCast function probably deserves a
-comment. It gains access to the simulator implementation object using
-the @code{Simulator::GetImplementation} method and then casts to the real-time
-simulator implementation to use the real-time schedule method
-@code{ScheduleRealtimeNow}. This function will cause a handler for the newly
-received packet to be scheduled for execution at the current real time clock
-value. This will, in turn cause the simulation clock to be advanced to that
-real time value when the scheduled event (@code{EmuNetDevice::ForwardUp}) is
-fired.
-
-The @code{ForwardUp} function operates as most other similar ns-3 net device
-methods do. The packet is first filtered based on the destination address. In
-the case of the @code{Emu} device, the MAC destination address will be the
-address of the @code{Emu} device and not the hardware address of the real
-device. Headers are then stripped off and the trace hooks are hit. Finally,
-the packet is passed up the ns-3 protocol stack using the receive callback
-function of the net device.
-
-Sending a packet is equally straightforward as shown below. The first thing
-we do is to add the ethernet header and trailer to the ns-3 @code{Packet} we
-are sending. The source address corresponds to the address of the @code{Emu}
-device and not the underlying native device MAC address. This is where the
-MAC address spoofing is done. The trailer is added and we enqueue and dequeue
-the packet from the net device queue to hit the trace hooks.
-
-@verbatim
- header.SetSource (source);
- header.SetDestination (destination);
- header.SetLengthType (packet->GetSize ());
- packet->AddHeader (header);
-
- EthernetTrailer trailer;
- trailer.CalcFcs (packet);
- packet->AddTrailer (trailer);
-
- m_queue->Enqueue (packet);
- packet = m_queue->Dequeue ();
-
- struct sockaddr_ll ll;
- bzero (&ll, sizeof (ll));
-
- ll.sll_family = AF_PACKET;
- ll.sll_ifindex = m_sll_ifindex;
- ll.sll_protocol = htons(ETH_P_ALL);
-
- rc = sendto (m_sock, packet->PeekData (), packet->GetSize (), 0,
- reinterpret_cast<struct sockaddr *> (&ll), sizeof (ll));
-@end verbatim
-
-
-Finally, we simply send the packet to the raw socket which puts it out on the
-real network.
-
--- a/doc/manual/emulation.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,69 +0,0 @@
-@node Emulation Overview
-@chapter Emulation Overview
-
-ns-3 has been designed for integration into testbed and virtual machine
-environments. We have addressed this need by providing two kinds of
-net devices. The first kind, which we call an @code{Emu} @code{NetDevice}
-allows ns-3 simulations to send data on a ``real'' network. The second kind,
-called a @code{Tap} @code{NetDevice} allows a ``real'' host to participate
-in an ns-3 simulation as if it were one of the simulated nodes. An ns-3
-simulation may be constructed with any combination of simulated, @code{Emu},
-or @code{Tap} devices.
-
-One of the use-cases we want to support is that of a testbed. A concrete
-example of an environment of this kind is the ORBIT testbed. ORBIT is a
-laboratory emulator/field trial network arranged as a two dimensional grid of
-400 802.11 radio nodes. We integrate with ORBIT by using their ``imaging''
-process to load and run ns-3 simulations on the ORBIT array. We use our
-@code{Emu} @code{NetDevice}s to drive the hardware in the testbed and we can
-accumulate results either using the ns-3 tracing and logging functions, or the
-native ORBIT data gathering techniques. See @uref{http://www.orbit-lab.org/}
-for details on the ORBIT testbed.
-
-A simulation of this kind is shown in the following figure:
-
-@float Figure,fig:testbed
-@caption{Example Implementation of Testbed Emulation.}
-@center @image{figures/testbed, 5in}
-@end float
-
-You can see that there are separate hosts, each running a subset of a ``global''
-simulation. Instead of an ns-3 channel connecting the hosts, we use real
-hardware provided by the testbed. This allows ns-3 applications and protocol
-stacks attached to a simulation node to communicate over real hardware.
-
-We expect the primary use for this configuration will be to generate repeatable
-experimental results in a real-world network environment that includes all of
-the ns-3 tracing, logging, visualization and statistics gathering tools.
-
-In what can be viewed as essentially an inverse configuration, we allow ``real''
-machines running native applications and protocol stacks to integrate with
-an ns-3 simulation. This allows for the simulation of large networks connected
-to a real machine, and also enables virtualization. A simulation of this kind
-is shown in the following figure:
-
-@float Figure,fig:emulated-channel
-@caption{Implementation overview of emulated channel.}
-@image{figures/emulated-channel, 6in}
-@end float
-
-Here, you will see that there is a single host with a number of virtual machines
-running on it. An ns-3 simulation is shown running in the virtual machine shown
-in the center of the figure. This simulation has a number of nodes with associated
-ns-3 applications and protocol stacks that are talking to an ns-3 channel through
-native simulated ns-3 net devices.
-
-There are also two virtual machines shown at the far left and far right of the
-figure. These VMs are running native (Linux) applications and protocol stacks.
-The VM is connected into the simulation by a Linux Tap net device. The user-mode
-handler for the Tap device is instantiated in the simulation and attached to a
-proxy node that represents the native VM in the simulation. These handlers allow
-the Tap devices on the native VMs to behave as if they were ns-3 net devices in
-the simulation VM. This, in turn, allows the native software and protocol suites
-in the native VMs to believe that they are connected to the simulated ns-3
-channel.
-
-We expect the typical use case for this environment will be to analyze the
-behavior of native applications and protocol suites in the presence of large
-simulated ns-3 networks.
-
Binary file doc/manual/figures/WifiArchitecture.dia has changed
Binary file doc/manual/figures/WimaxArchitecture.dia has changed
--- a/doc/manual/flow-monitor.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,11 +0,0 @@
-@node Flow Monitor
-@chapter Flow Monitor
-
-@cartouche
-Placeholder chapter
-@end cartouche
-
-This feature was added as contributed code (@code{src/contrib}) in ns-3.6 and
-to the main distribution for ns-3.7.
-A paper on this feature is published in the proceedings of NSTools: @*
-@uref{http://www.nstools.org/techprog.shtml,,http://www.nstools.org/techprog.shtml}
--- a/doc/manual/helpers.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,42 +0,0 @@
-@node Helpers
-@chapter Helpers
-
-The above chapters introduced you to various ns-3 programming concepts
-such as smart pointers for reference-counted memory management, attributes,
-namespaces, callbacks, etc. Users who work at this low-level API
-can interconnect ns-3 objects with fine granulariy. However, a
-simulation program written entirely using the low-level API would
-be quite long and tedious to code. For this reason, a separate so-called
-``helper API'' has been overlaid on the core ns-3 API. If you have read
-the ns-3 tutorial, you will already be familiar with the helper API,
-since it is the API that new users are typically introduced to first.
-In this chapter, we introduce the design philosophy of the helper
-API and contrast it to the low-level API. If you become a heavy
-user of ns-3, you will likely move back and forth between these
-APIs even in the same program.
-
-The helper API has a few goals:
-@enumerate
-@item the rest of @code{src/} has no dependencies on the helper API;
-anything that can be done with the helper API can be coded also at
-the low-level API
-@item @strong{Containers:} Often simulations will need to do
-a number of identical actions to groups of objects. The helper
-API makes heavy use of containers of similar objects to which similar
-or identical operations can be performed.
-@item The helper API is not generic; it does not strive to maximize
-code reuse. So, programming constructs such as polymorphism and
-templates that achieve code reuse are not as prevalent. For instance,
-there are separate CsmaNetDevice helpers and PointToPointNetDevice
-helpers but they do not derive from a common NetDevice base class.
-@item The helper API typically works with stack-allocated (vs.
-heap-allocated) objects. For some programs, ns-3 users may not
-need to worry about any low level Object Create or Ptr handling;
-they can make do with containers of objects and stack-allocated helpers
-that operate on them.
-@end enumerate
-
-The helper API is really all about making ns-3 programs easier to
-write and read, without taking away the power of the low-level
-interface. The rest of this chapter provides some examples of
-the programming conventions of the helper API.
--- a/doc/manual/internet.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,243 +0,0 @@
-@node Internet Stack
-@chapter Internet Stack
-
-@section Internet stack aggregation
-
-A bare @code{class Node} is not very useful as-is; other objects
-must be aggregated to it to provide useful node functionality.
-
-The ns-3 source code directory @code{src/internet-stack} provides
-implementation of TCP/IPv4- and IPv6-related components. These include IPv4,
-ARP, UDP, TCP, IPv6, Neighbor Discovery, and other related protocols.
-
-Internet Nodes are not subclasses of class Node; they are simply Nodes
-that have had a bunch of IPv4-related
-objects aggregated to them. They can be put together by hand, or
-via a helper function @code{InternetStackHelper::Install ()} which does the
-following to all nodes passed in as arguments:
-@smallformat
-@example
-void
-InternetStackHelper::Install (Ptr<Node> node) const
-@{
- if (node->GetObject<Ipv4> () != 0)
- @{
- NS_FATAL_ERROR ("InternetStackHelper::Install(): Aggregating "
- "an InternetStack to a node with an existing Ipv4 object");
- return;
- @}
-
- CreateAndAggregateObjectFromTypeId (node, "ns3::ArpL3Protocol");
- CreateAndAggregateObjectFromTypeId (node, "ns3::Ipv4L3Protocol");
- CreateAndAggregateObjectFromTypeId (node, "ns3::Icmpv4L4Protocol");
- CreateAndAggregateObjectFromTypeId (node, "ns3::UdpL4Protocol");
- node->AggregateObject (m_tcpFactory.Create<Object> ());
- Ptr<PacketSocketFactory> factory = CreateObject<PacketSocketFactory> ();
- node->AggregateObject (factory);
- // Set routing
- Ptr<Ipv4> ipv4 = node->GetObject<Ipv4> ();
- Ptr<Ipv4RoutingProtocol> ipv4Routing = m_routing->Create (node);
- ipv4->SetRoutingProtocol (ipv4Routing);
-@}
-@end example
-@end smallformat
-
-Where multiple implementations exist in ns-3 (TCP, IP routing), these
-objects are added by a factory object (TCP) or by a routing helper
-(m_routing).
-
-Note that the routing protocol is configured and set outside this
-function. By default, the following protocols are added to Ipv4:
-@verbatim
-InternetStackHelper::InternetStackHelper ()
-{
- SetTcp ("ns3::TcpL4Protocol");
- static Ipv4StaticRoutingHelper staticRouting;
- static Ipv4GlobalRoutingHelper globalRouting;
- static Ipv4ListRoutingHelper listRouting;
- listRouting.Add (staticRouting, 0);
- listRouting.Add (globalRouting, -10);
- SetRoutingHelper (listRouting);
-}
-@end verbatim
-
-By default, IPv4 and IPv6 are enabled.
-
-@subsection Internet Node structure
-
-An IPv4-capable Node (an ns-3 Node augmented by aggregation to have one or more
-IP stacks) has the following internal structure.
-
-@subsubsection Layer-3 protocols
-At the lowest layer, sitting above the NetDevices, are the "layer 3"
-protocols, including IPv4, IPv6 (in the future), and ARP. The
-@code{class Ipv4L3Protocol} is an
-implementation class whose public interface is
-typically @code{class Ipv4} (found in src/node directory), but the
-Ipv4L3Protocol public API is also used internally in the
-src/internet-stack directory at present.
-
-In class Ipv4L3Protocol, one method described below is @code{Receive ()}:
-@smallformat
-@example
- /**
- * Lower layer calls this method after calling L3Demux::Lookup
- * The ARP subclass needs to know from which NetDevice this
- * packet is coming to:
- * - implement a per-NetDevice ARP cache
- * - send back arp replies on the right device
- */
- void Receive( Ptr<NetDevice> device, Ptr<const Packet> p, uint16_t protocol,
-const Address &from, const Address &to, NetDevice::PacketType packetType);
-@end example
-@end smallformat
-
-First, note that the @code{Receive ()} function has a matching signature
-to the ReceiveCallback in the @code{class Node}. This function pointer
-is inserted into the Node's protocol handler when
-@code{AddInterface ()} is called. The actual registration is done
-with a statement such as:
-follows:
-@verbatim
- RegisterProtocolHandler ( MakeCallback (&Ipv4Protocol::Receive, ipv4),
- Ipv4L3Protocol::PROT_NUMBER, 0);
-@end verbatim
-
-The Ipv4L3Protocol object is aggregated to the Node; there is only one
-such Ipv4L3Protocol object. Higher-layer protocols that have a packet
-to send down to the Ipv4L3Protocol object can call
-@code{GetObject<Ipv4L3Protocol> ()} to obtain a pointer, as follows:
-@verbatim
- Ptr<Ipv4L3Protocol> ipv4 = m_node->GetObject<Ipv4L3Protocol> ();
- if (ipv4 != 0)
- {
- ipv4->Send (packet, saddr, daddr, PROT_NUMBER);
- }
-@end verbatim
-
-This class nicely demonstrates two techniques we exploit in
-ns-3 to bind objects together: callbacks, and object aggregation.
-
-Once IPv4 routing has determined that a packet is for the local node, it
-forwards it up the stack. This is done with the following function:
-
-@smallformat
-@example
-void
-Ipv4L3Protocol::LocalDeliver (Ptr<const Packet> packet, Ipv4Header const&ip, uint32_t iif)
-@end example
-@end smallformat
-
-The first step is to find the right Ipv4L4Protocol object , based on IP protocol
-number. For instance, TCP is registered in the demux as protocol number 6.
-Finally, the @code{Receive()} function on the Ipv4L4Protocol (such as
-@code{TcpL4Protocol::Receive} is called.
-
-We have not yet introduced the class Ipv4Interface. Basically,
-each NetDevice is paired with an IPv4 representation of such device.
-In Linux, this @code{class Ipv4Interface} roughly corresponds to
-the @code{struct in_device}; the main purpose is to provide
-address-family specific information (addresses) about an interface.
-
-The IPv6 implementation follows a similar architecture.
-
-@subsubsection Layer-4 protocols and sockets
-
-We next describe how the transport protocols, sockets, and applications
-tie together. In summary, each transport protocol implementation is
-a socket factory. An application that needs a new socket
-
-For instance, to create a UDP socket, an application would use a code
-snippet such as the following:
-@verbatim
- Ptr<Udp> udpSocketFactory = GetNode ()->GetObject<Udp> ();
- Ptr<Socket> m_socket = socketFactory->CreateSocket ();
- m_socket->Bind (m_local_address);
- ...
-@end verbatim
-The above will query the node to get a pointer to its UDP socket
-factory, will create one such socket, and will use the socket with
-an API similar to the C-based sockets API, such as @code{Connect ()}
-and @code{Send ()}. See the chapter on ns-3 sockets for more information.
-
-We have described so far a socket factory (e.g. @code{class Udp}) and
-a socket, which may be specialized (e.g., @code{class UdpSocket}).
-There are a few more key objects that relate to the specialized
-task of demultiplexing a packet to one or more receiving sockets.
-The key object in this task is @code{class Ipv4EndPointDemux}.
-This demultiplexer stores objects of @code{class Ipv4EndPoint}.
-This class holds the addressing/port tuple (local port, local address,
-destination port, destination address) associated with the socket,
-and a receive callback. This receive callback has a receive
-function registered by the socket. The @code{Lookup ()} function to
-Ipv4EndPointDemux returns a list of Ipv4EndPoint objects (there may
-be a list since more than one socket may match the packet). The
-layer-4 protocol copies the packet to each Ipv4EndPoint and calls
-its @code{ForwardUp ()} method, which then calls the @code{Receive ()}
-function registered by the socket.
-
-An issue that arises when working with the sockets API on real
-systems is the need to manage the reading from a socket, using
-some type of I/O (e.g., blocking, non-blocking, asynchronous, ...).
-ns-3 implements an asynchronous model for socket I/O; the application
-sets a callback to be notified of received data ready to be read, and the
-callback is invoked by the transport protocol when data is available.
-This callback is specified as follows:
-@verbatim
- void Socket::SetRecvCallback (Callback<void, Ptr<Socket>,
- Ptr<Packet>, const Address&> receivedData);
-@end verbatim
-The data being received is conveyed in the Packet data buffer. An example
-usage is in @code{class PacketSink}:
-@verbatim
- m_socket->SetRecvCallback (MakeCallback(&PacketSink::HandleRead, this));
-@end verbatim
-
-To summarize, internally, the UDP implementation is organized as follows:
-@itemize @bullet
-@item a @code{UdpImpl} class that implements the UDP socket factory
-functionality
-@item a @code{UdpL4Protocol} class that implements the protocol logic
-that is socket-independent
-@item a @code{UdpSocketImpl} class that implements socket-specific aspects
-of UDP
-@item a class called @code{Ipv4EndPoint} that stores the
-addressing tuple (local port, local address, destination port, destination
-address) associated with the socket, and a receive callback for the socket.
-@end itemize
-
-@subsection Ipv4-capable node interfaces
-
-Many of the implementation details, or internal objects themselves,
-of Ipv4-capable Node objects are not exposed at the simulator public
-API. This allows for different implementations; for instance,
-replacing the native ns-3 models with ported TCP/IP stack code.
-
-The C++ public APIs of all of these objects is found in the
-@code{src/node} directory, including principally:
-@itemize @bullet
-@item @code{socket.h}
-@item @code{tcp.h}
-@item @code{udp.h}
-@item @code{ipv4.h}
-@end itemize
-These are typically base class objects that implement the default
-values used in the implementation, implement access methods to get/set
-state variables, host attributes, and implement publicly-available methods
-exposed to clients such as @code{CreateSocket}.
-
-@subsection Example path of a packet
-
-These two figures show an example stack trace of how packets flow
-through the Internet Node objects.
-
-@float Figure,fig:internet-node-send
-@caption{Send path of a packet.}
-@image{figures/internet-node-send,5in}
-@end float
-
-@float Figure,fig:internet-node-recv
-@caption{Receive path of a packet.}
-@image{figures/internet-node-recv,5in}
-@end float
-
--- a/doc/manual/ipv4.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,6 +0,0 @@
-@node IPv4
-@chapter IPv4
-
-@cartouche
-Placeholder chapter
-@end cartouche
--- a/doc/manual/ipv6.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,10 +0,0 @@
-@node IPv6
-@chapter IPv6
-
-@cartouche
-Placeholder chapter
-@end cartouche
-IPv6 models are being added to ns-3. A paper on the IPv6 models was
-published in WNS2 2008: @*
-@uref{http://lsiit.u-strasbg.fr/Publications/2008/VMM08/,,http://lsiit.u-strasbg.fr/Publications/2008/VMM08/}
-
--- a/doc/manual/log.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,7 +0,0 @@
-@node Logging
-@chapter Logging
-
-@cartouche
-This chapter not yet written. For now, the ns-3 tutorial contains logging
-information.
-@end cartouche
--- a/doc/manual/lte.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,327 +0,0 @@
-@node LTE Module
-@chapter LTE Module
-@anchor{chap:lte}
-
-This chapter describes the ns-3 LteNetDevice and related models.
-By adding LteNetDevice objects to ns-3 nodes, one can create models of 3GPP E-UTRAN infrastructure
-and Long Term Evolution (LTE) networks.
-
-Below, we list some more details about what ns-3 LTE models cover but, in summary, the most important features
-of the ns-3 model are:
-@itemize @bullet
-@item a basic implementation of both the User Equipment (UE) and the enhanced NodeB (eNB) devices,
-@item RRC entities for both the UE and the eNB,
-@item a state-of-the-art Adaptive Modulation and Coding (AMC) scheme for the downlink
-@item the management of the data radio bearers (with their QoS parameters), the MAC queues and the RLC instances,
-@item Channel Quality Indicator (CQI) management,
-@item support for both uplink and downlik packet scheduling,
-@item a PHY layer model with Resource Block level granularity
-@item a channel model with the outdoor E-UTRAN propagation loss model.
-@end itemize
-
-@menu
-* lte-Model Description::
-* lte-Usage::
-* lte-Validation::
-@end menu
-
-@node lte-Model Description
-@section Model Description
-
-The source code for the LTE models lives in the directory
-@code{src/devices/lte}.
-
-@menu
-* lte-Design::
-* lte-Scope and Limitations::
-* lte-Future Work::
-* lte-References::
-@end menu
-
-@node lte-Design
-@subsection Design
-
-The LTE model provides a basic implementation of LTE devices, including propagation models and PHY and MAC layers. It allow to simulate an E-UTRAN interface where one eNB and several UEs can communicate among them using a shared downlink (uplink) channel.
-
-The PHY layer has been developed extending the Spectrum Framework [1]. The MAC model, instead, as been developed extending and adding some features to the base class @code{ns3::NetDevice}.
-
-
-@subsubsection Physical layer
-
-A @code{ns3::LtePhy} class models the LTE PHY layer.
-
-Basic functionalities of the PHY layer are: (i) transmit packets coming from the device to the channel; (ii) receive packets from the channel; (ii) evaluate the quality of the channel from the Signal To Noise ratio of the received signal; and (iii) forward received packets to the device.
-
-Both the PHY and channel have been developed exending @code{ns3::SpectrumPhy} and @code{ns3::SpectrumChannel} classes, respectively.
-
-The module implements an FDD channel access. In FDD channel access, downlink and uplink transmissions work together in the time but using a different set of frequencies.
-Since DL and UL are indipendent between them, the PHY is composed by couple of LteSpectrumPhy object (i.e., implemented into the @code{ns3::LteSpectrumPhy} class); one for the downlink and one for the uplink.
-The LtePhy stores and manages both downlink and uplink LteSpectrumPhy elements.
-
-In order to customize all physical functionalities for both UE and eNB devices, dedicated classes have been inherited from ones described before. In particular, UePhy and EnbPhy classes, inherited from the LtePhy class, implement the PHY layer for the UE and the eNB, respectively. In the same way, UeLteSpectrumPhy and EnbLteSpectrumPhy classes, inherited from the LteSpectrumPhy, implement the downlink/uplink spectrum channel for the UE and the eNB, respectively.
-
-Fig, @ref{fig:lte-transmission} shows how UE and eNB can exchange packets througth the considered PHY layer.
-
-@float Figure,fig:lte-transmission
-@caption{DL and UL transmision on the LTE network}
-@image{figures/lte-transmission,,3in}
-@end float
-
-For the downlink, when the eNB whants to send packets, it calls StartTx function to send them into the downlink channel. Then, the downlink channel delivers the burst of packets to all the UeLteSpectrumPhy attached to it, handling the StartRx function. When the UE receives packets, it executes the follos tasks:
-@itemize @bullet
-@item compute the SINR for all the sub channel used in the downlink
-@item create and send CQI feedbacks
-@item forward all the received packets to the device
-@end itemize
-
-The uplink works similary to the previous one.
-
-
-@subsubsection Propagation Loss Models
-
-A proper propagation loss model has been developed for the LTE E-UTRAN interface [2][3].
-It is used by the PHY layer to compute the loss due to the propagation.
-
-The LTE propagation loss model is composed by 4 different models (shadowing, multipath, penetration loss and path loss) [2]:
-@itemize @bullet
-@item Pathloss: PL = 128.1 + (37.6 * log10 (R)), where R is the distance between the UE and the eNB in Km.
-@item Multipath: Jakes model
-@item PenetrationLoss: 10 dB
-@item Shadowing: log-normal distribution (mean=0dB, standard deviation=8dB)
-@end itemize
-
-Every time that the LteSpectrumPHY::StartRx () function is called, the SpectrumInterferenceModel is used to computed the SINR, as proposed in [3]. Then, the network device uses the AMC module to map the SINR to a proper CQI and to send it to the eNB using the ideal control channel.
-
-
-@subsubsection LTE Devices
-
-All the common functionalities of the LTE network devices have been defined into the @code{ns3::LteNetDevice} class. Moreover, the LTE device has been conceived as a container of several entities such as MAC, RRC, RLC etc .. For each of these entity a dedicated class has been developed.
-
-For each device are defined the following entity/element
-@itemize @bullet
-@item the LTE PHY layer (described in the previous sub section)
-@item rrc entity
-@item mac entity
-@item rlc entity
-@end itemize
-
-The module is perfectly integrated into the whole ns-3 project: it is already possible to attach to each device a TCP/IP protocol stack and all the implemented applications (i.e., udp client/server, trace based, etc..).
-
-
-@subsubsection The RRC Entity
-
-RRC entity is implemented by the @code{ns3::RrcEntity} class, and provides only the Radio Bearer management functionality.
-A dedicated bearer is created for each downlink flow. The RRC
-
-The RRC entity performs the classification of the packets coming from the upper layer into the corresponding Radio Bearer. This classification is
-based on the information provided by the class @code{ns3::IpcsClassifierRecord}.
-
-
-
-@subsubsection The MAC Entity
-Class @code{ns3::MacEntity} provides a basic implementation of the MAC entity for the LTE device. Moreover, @code{ns3::EnbMacEntity} and @code{ns3::UeMacEntity} classes, inherited from the previous one, provides an implementation for the eNB and the UE MAC entity, respectively.
-In all MAC entities is defined the AMC module [4]. Furthermore, into the @code{ns3::EnbMacEntity} class are defined also both uplink and downlink schedulers.
-
-Every time the PHY layer of the UE receives a packet form the channel, it calls the AMC module, define into the MAC entity, in order to convert the SINR of the received signal to CQI feedbacks.
-Every sub frame, the eNB performs both uplink and downlink radio resource allocation. Actually only a simple packet scheduler has been implemented that is able to send, every sub frame, only one packet in the downlink.
-
-
-@subsubsection The RLC Entity
-The RLC entity performs an interface between the MAC layer and the MAC queue for a given bearer. Actually, only the RLC Transport Mode has been implemented.
-
-
-@subsubsection Control Channel
-
-Control channel keeps a very important role in LTE networks. In fact, it is responsible of the transmission of several information (i.e., CQI feedback, allocation map, etc...). For this reason, also in a framework oriented to data transmision, it is necesary to find a tecnique for exchange these information. To this aim, an ideal control channel will be developed.
-Using ideal control messages, both UE and eNB can exchange control information without simulating a realistic transmission over the LTE channel.
-
-Two types of control messages have been implemented: the Pdcch Map Ideal Control Message and the Cqi Ideal Control Message. The first one is used by the eNB to send the uplink and downlink resource mapping to all registered UE. In particular, this message carries information about UEs that have been scheduled in the ul/dl, a list of assigned sub channels and the selected MCS for the transmission.
-The second one, instead, is used by the UE to send CQI feedbacks to the eNB.
-
-
-
-@node lte-Scope and Limitations
-@subsection Scope and Limitations
-
-The framework has been designed in order to support data transmission for both uplink and downlink. It is important to note that downlin and uplink transmissions are managed by the packet scheduler that works at the eNB. It decides, in fact, what UEs should be scheduled every TTI and what radio resource should be allocated to them.
-
-In the current implementation, the downlink transmission is administrated by the downlink packet scheduler. Furthermore, no packet scheduler for uplink transmission has been developed.
-As a consequence, for the downlink packet are sent only after scheduling decisions; for the uplink, instead, packet are sent directly, without any scheduling decisions.
-
-Finally, the transmission of control messages (such as CQI feedbacks, PDCCH, etc..) is done by an ideal control channel.
-
-
-@node lte-Future Work
-@subsection Future Work
-In the future, several LTE features will be developed in order to improve the proposed module.
-
-In particular, for the near future have been scheduled the following implementations:
-
-- a more efficient design for the RRM (Radio resource management)
-
-- a complete packet scheduler (i.e., a simple round robin scheme, maximum througput and proportional fair allocation schemes) for both downlink and uplink, in order to support a standard compliant packet transmission
-
-- ideal PDCCH control messages
-
-- a standard compliant RLC entity
-
-- PHY error model
-
-
-
-@node lte-References
-@subsection References
-
-@enumerate
-@item N. Baldo and M. Miozzo, Spectrum-aware Channel and PHY layer modeling for ns3, Proceedings of ICST NSTools 2009, Pisa, Italy.
-The framework is designed to simulate only data transmissions. For the transmission of control messages (such as CQI feedback, PDCCH, etc..) will be used an ideal control channel).
-@item 3GPP TS 25.814 ( http://www.3gpp.org/ftp/specs/html-INFO/25814.htm )
-@item Giuseppe Piro, Luigi Alfredo Grieco, Gennaro Boggia, and Pietro Camarda", A Two-level Scheduling Algorithm for QoS Support in the Downlink of LTE Cellular Networks", Proc. of European Wireless, EW2010, Lucca, Italy, Apr., 2010 ( draft version is available on http://telematics.poliba.it/index.php?option=com_jombib&task=showbib&id=330)
-@item 3GPP R1-081483 (available on @*
-http://www.3gpp.org/ftp/tsg_ran/WG1_RL1/TSGR1_52b/Docs/R1-081483.zip)
-@end enumerate
-
-@node lte-Usage
-@section Usage
-
-The main way that users who write simulation scripts will typically
-interact with the LTE models is through the helper API and through
-the publicly visible attributes of the model.
-
-The helper API is defined in @code{src/helper/lte-helper{cc,h}}.
-
-The example @code{examples/lte/} contain some basic
-code that shows how to set up the model in order to simualte an E-UTRAN downlink transmission.
-
-@menu
-* lte-Examples::
-* lte-Helpers::
-* lte-Attributes::
-* lte-Tracing::
-* lte-Logging::
-* lte-Caveats::
-@end menu
-
-@node lte-Examples
-@subsection Examples
-
-@code{examples/lte/lte.device.cc} shows how it is possible to set up the LTE module:
-
-@smallformat
-@example
-
- NodeContainer ueNodes;
- NodeContainer enbNodes;
-
- ueNodes.Create (1);
- enbNodes.Create (1);
-
- LteHelper lte;
-
- NetDeviceContainer ueDevs, enbDevs;
- ueDevs = lte.Install (ueNodes, LteHelper::DEVICE_TYPE_USER_EQUIPMENT);
- enbDevs = lte.Install (enbNodes, LteHelper::DEVICE_TYPE_ENODEB);
-
-@end example
-@end smallformat
-
-The helper method @code{Install} creates LTE device, the DL, UL physical layer and attach the to proper LTE channels.
-
-
-Moreover, to simulate a complete LTE system, it is necessary to define other information, as expressed in what follows:
-
-(i) install IP protocol stack
-@smallformat
-@example
- InternetStackHelper stack;
- stack.Install (ueNodes);
- stack.Install (enbNodes);
- Ipv4AddressHelper address;
- address.SetBase ("10.1.1.0", "255.255.255.0");
- Ipv4InterfaceContainer UEinterfaces = address.Assign (ueDevs);
- Ipv4InterfaceContainer ENBinterface = address.Assign (enbDevs);
-@end example
-@end smallformat
-
-
-(ii) register UE to a given eNB
-@smallformat
-@example
- Ptr<EnbNetDevice> enb = enbDevs.Get (0)->GetObject<EnbNetDevice> ();
- Ptr<UeNetDevice> ue = ueDevs.Get (i)->GetObject<UeNetDevice> ();
- lte.RegisterUeToTheEnb (ue, enb);
-@end example
-@end smallformat
-
-
-(ii) create the mobility model for each device
-@smallformat
-@example
- Ptr<ConstantPositionMobilityModel> enbMobility = new ConstantPositionMobilityModel ();
- enbMobility->SetPosition (Vector (0.0, 0.0, 0.0));
- lte.AddMobility (enb->GetPhy (), enbMobility);
-
- Ptr<ConstantVelocityMobilityModel> ueMobility = new ConstantVelocityMobilityModel ();
- ueMobility->SetPosition (Vector (30.0, 0.0, 0.0));
- ueMobility->SetVelocity (Vector (30.0, 0.0, 0.0));
- lte.AddMobility (ue->GetPhy (), ueMobility);
-@end example
-@end smallformat
-
-
-(iii) define a set of sub channels to use for dl and ul transmission
-@smallformat
-@example
- std::vector<int> dlSubChannels;
- for (int i = 0; i < 25; i++)
- {
- dlSubChannels.push_back (i);
- }
- std::vector<int> ulSubChannels;
- for (int i = 50; i < 100; i++)
- {
- ulSubChannels.push_back (i);
- }
-
- enb->GetPhy ()->SetDownlinkSubChannels (dlSubChannels);
- enb->GetPhy ()->SetUplinkSubChannels (ulSubChannels);
- ue->GetPhy ()->SetDownlinkSubChannels (dlSubChannels);
- ue>GetPhy ()->SetUplinkSubChannels (ulSubChannels);
-@end example
-@end smallformat
-
-
-(iv) define a channel realization for the PHY model
-@smallformat
-@example
-lte.AddDownlinkChannelRealization (enbMobility, ueMobility, ue->GetPhy ());
-@end example
-@end smallformat
-
-
-@node Helpers
-@subsection Helpers
-
-@node lte-Attributes
-@subsection Attributes
-
-@node lte-Tracing
-@subsection Tracing
-
-@node lte-Logging
-@subsection Logging
-
-@node lte-Caveats
-@subsection Caveats
-
-@node lte-Validation
-@section Validation
-
-In the @code{src/example/lte-amc.cc} has been developed an important example that shows the proper functioning of both AMC module and Channel model.
-The analyzed scenario is composed by two nodes: a eNB and a single UE (registered to the eNB). The UE moves into the cell using the @code{ConstantVelocityMobilityModel}, along a radial direction.
-The proposed example describes how the channel quality decreases as the distance between UE and eNB increases.
-As a conseguence, the total bit rate (in bits per TTI) available to the UE decreases as the distance between nodes increases, as
-expected.
-
-
-
--- a/doc/manual/manual.css Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,156 +0,0 @@
-body {
- font-family: "Trebuchet MS", "Bitstream Vera Sans", verdana, lucida, arial, helvetica, sans-serif;
- background: white;
- color: black;
- font-size: 11pt;
-}
-
-h1, h2, h3, h4, h5, h6 {
-# color: #990000;
- color: #009999;
-}
-
-pre {
- font-size: 10pt;
- background: #e0e0e0;
- color: black;
-}
-
-a:link, a:visited {
- font-weight: normal;
- text-decoration: none;
- color: #0047b9;
-}
-
-a:hover {
- font-weight: normal;
- text-decoration: underline;
- color: #0047b9;
-}
-
-img {
- border: 0px;
-}
-
-#main th {
- font-size: 12pt;
- background: #b0b0b0;
-}
-
-.odd {
- font-size: 12pt;
- background: white;
-}
-
-.even {
- font-size: 12pt;
- background: #e0e0e0;
-}
-
-.answer {
- font-size: large;
- font-weight: bold;
-}
-
-.answer p {
- font-size: 12pt;
- font-weight: normal;
-}
-
-.answer ul {
- font-size: 12pt;
- font-weight: normal;
-}
-
-#container {
- position: absolute;
- width: 100%;
- height: 100%;
- top: 0px;
-}
-
-#feedback {
- color: #b0b0b0;
- font-size: 9pt;
- font-style: italic;
-}
-
-#header {
- position: absolute;
- margin: 0px;
- top: 10px;
- height:96px;
- left: 175px;
- right: 10em;
- bottom: auto;
- background: white;
- clear: both;
-}
-
-#middle {
- position: absolute;
- left: 0;
- height: auto;
- width: 100%;
-}
-
-#main {
- position: absolute;
- top: 50px;
- left: 175px;
- right: 100px;
- background: white;
- padding: 0em 0em 0em 0em;
-}
-
-#navbar {
- position: absolute;
- top: 75px;
- left: 0em;
- width: 146px;
- padding: 0px;
- margin: 0px;
- font-size: 10pt;
-}
-
-#navbar a:link, #navbar a:visited {
- font-weight: normal;
- text-decoration: none;
- color: #0047b9;
-}
-
-#navbar a:hover {
- font-weight: normal;
- text-decoration: underline;
- color: #0047b9;
-}
-
-#navbar dl {
- width: 146px;
- padding: 0;
- margin: 0 0 10px 0px;
- background: #99ffff url(images/box_bottom2.gif) no-repeat bottom left;
-}
-
-#navbar dt {
- padding: 6px 10px;
- font-size: 100%;
- font-weight: bold;
- background: #009999;
- margin: 0px;
- border-bottom: 1px solid #fff;
- color: white;
- background: #009999 url(images/box_top2.gif) no-repeat top left;
-}
-
-#navbar dd {
- font-size: 100%;
- margin: 0 0 0 0px;
- padding: 6px 10px;
- color: #0047b9;
-}
-
-dd#selected {
- background: #99ffff url(images/arrow.gif) no-repeat;
- background-position: 4px 10px;
-}
--- a/doc/manual/manual.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,245 +0,0 @@
-\input texinfo @c -*-texinfo-*-
-@c %**start of header
-@setfilename ns-3.info
-@settitle ns-3 manual
-@c %**end of header
-
-@ifinfo
-Primary documentation for the @command{ns-3} project is available in
-four forms:
-@itemize @bullet
-@item @uref{http://www.nsnam.org/doxygen/index.html,,ns-3 Doxygen/Manual}: Documentation of the public APIs of the simulator
-@item @uref{http://www.nsnam.org/docs/tutorial/tutorial.html,,ns-3 Tutorial}
-@item Reference Manual (this document)
-@item @uref{http://www.nsnam.org/wiki/index.php,, ns-3 wiki}
-@end itemize
-
-This document is written in GNU Texinfo and is to be maintained in
-revision control on the @command{ns-3} code server. Both PDF and HTML versions
-should be available on the server. Changes to
-the document should be discussed on the ns-developers@@isi.edu mailing list.
-@end ifinfo
-
-@copying
-
-This is an @command{ns-3} reference manual.
-Primary documentation for the @command{ns-3} project is available in
-five forms:
-@itemize @bullet
-@item @uref{http://www.nsnam.org/docs/tutorial/tutorial.html,,ns-3 Tutorial}
-@item @uref{http://www.nsnam.org/doxygen/index.html,,ns-3 Doxygen}: Documentation of the public APIs of the simulator
-@item Reference Manual (this document)
-@item @uref{http://www.nsnam.org/tutorials.html,, ns-3 Testing and Validation manual}
-@item @uref{http://www.nsnam.org/wiki/index.php,, ns-3 wiki}
-@end itemize
-
-This document is written in GNU Texinfo and is to be maintained in
-revision control on the @command{ns-3} code server. Both PDF and HTML
-versions should be available on the server. Changes to
-the document should be discussed on the ns-developers@@isi.edu mailing list.
-
-This software is free software; you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation; either version 2 of the License, or
-(at your option) any later version.
-
-This software is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this program. If not, see @uref{http://www.gnu.org/licenses/}.
-@end copying
-
-@titlepage
-@title ns-3 Reference Manual
-@author ns-3 project
-@author feedback: ns-developers@@isi.edu
-
-@b{Simulator version: }
-@include VERSION
-@today{}
-
-@vskip 0pt plus 1filll
-@insertcopying
-@page
-@center This page is intentionally blank.
-@end titlepage
-
-@c So the toc is printed at the start.
-@ifnottex
-@anchor{Full Table of Contents}
-@end ifnottex
-@shortcontents
-
-@ifnottex
-@node Top
-@top ns-3 Manual (html version)
-
-For a pdf version of this manual,
-see @uref{http://www.nsnam.org/docs/manual.pdf}.
-
-Simulator version:
-@include VERSION
-
-@insertcopying
-@end ifnottex
-
-@menu
-* Organization::
-* Core::
-* Node and NetDevices::
-* Emulation::
-* Internet Models::
-* Applications::
-* Support::
-@end menu
-
-@setchapternewpage odd
-@headings off
-@everyheading @thischapter @| @| ns-3 manual
-@everyfooting ns-3 @| @thispage @| @today
-@include organization.texi
-
-@node Core
-@chapter Core
-
-@lowersections
-@menu
-* Random variables::
-* Callbacks::
-* Object model::
-* Attributes::
-* Object names::
-* Logging::
-* Tracing::
-* RealTime::
-* Distributed::
-* Packets::
-* Helpers::
-* Python::
-* LTE Module::
-@end menu
-
-@setchapternewpage off
-@include random.texi
-@setchapternewpage odd
-@include callbacks.texi
-@include objects.texi
-@include attributes.texi
-@include names.texi
-@include log.texi
-@include tracing.texi
-@include realtime.texi
-@include distributed.texi
-@include packets.texi
-@include helpers.texi
-@include python.texi
-@raisesections
-
-@node Node and NetDevices
-@chapter Node and NetDevices
-
-@lowersections
-@menu
-* Node and NetDevices Overview::
-* Simple NetDevice::
-* PointToPoint NetDevice::
-* CSMA NetDevice::
-* Wifi NetDevice::
-* Mesh NetDevice::
-* Bridge NetDevice::
-* Wimax NetDevice::
-@end menu
-
-@setchapternewpage off
-@include node.texi
-@setchapternewpage odd
-@include simple.texi
-@include point-to-point.texi
-@include csma.texi
-@include wifi.texi
-@include mesh.texi
-@include bridge.texi
-@include lte.texi
-@include wimax.texi
-@raisesections
-
-@node Emulation
-@chapter Emulation
-
-@menu
-* Emulation Overview::
-* Emu NetDevice::
-* Tap NetDevice::
-@end menu
-
-@lowersections
-@setchapternewpage off
-@include emulation.texi
-@setchapternewpage odd
-@include emu.texi
-@include tap.texi
-@raisesections
-
-@node Internet Models
-@chapter Internet Models
-
-@menu
-* Sockets APIs::
-* Internet Stack::
-* IPv4::
-* IPv6::
-* Routing overview::
-* TCP::
-@end menu
-
-@lowersections
-@setchapternewpage off
-@include sockets.texi
-@setchapternewpage odd
-@include internet.texi
-@include ipv4.texi
-@include ipv6.texi
-@include routing.texi
-@include tcp.texi
-@raisesections
-
-@node Applications
-@chapter Applications
-
-@menu
-* Applications Overview::
-@end menu
-
-@lowersections
-@setchapternewpage off
-@include applications.texi
-@setchapternewpage odd
-@raisesections
-
-@node Support
-@chapter Support
-
-@menu
-* Flow Monitor::
-* Animation::
-* Statistics::
-* Creating a new ns-3 model::
-* Troubleshooting::
-@end menu
-
-@lowersections
-@setchapternewpage off
-@include flow-monitor.texi
-@setchapternewpage odd
-@include animation.texi
-@include statistics.texi
-@include new-models.texi
-@include troubleshoot.texi
-@raisesections
-
-@printindex cp
-
-@bye
--- a/doc/manual/mesh.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,11 +0,0 @@
-@node Mesh NetDevice
-@chapter Mesh NetDevice
-
-@cartouche
-Placeholder chapter
-@end cartouche
-
-The Mesh NetDevice based on 802.11s was added in ns-3.6.
-An overview presentation by Kirill Andreev was published at the wns-3 workshop
-in 2009: @*
-@uref{http://www.nsnam.org/wiki/index.php/Wns3-2009,,http://www.nsnam.org/wiki/index.php/Wns3-2009}
--- a/doc/manual/names.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,6 +0,0 @@
-@node Object names
-@chapter Object names
-
-@cartouche
-Placeholder chapter
-@end cartouche
--- a/doc/manual/new-models.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,601 +0,0 @@
-@node Creating a new ns-3 model
-@chapter Creating a new ns-3 model
-
-@menu
-* Design-approach::
-* Scaffolding::
-* Initial Implementation::
-* Adding-a-sample-script::
-* Add subclass::
-* Build-core-functions-and-unit-tests::
-@end menu
-
-This chapter walks through the design process of an @command{ns-3} model.
-In many research cases, users will not be satisfied to merely adapt
-existing models, but may want to extend the core of the simulator in
-a novel way. We will use the example of adding an ErrorModel to
-a simple @command{ns-3} link as a motivating example of how one might
-approach this problem and proceed through a design and implementation.
-
-@node Design-approach
-@section Design-approach
-
-Consider how you want it to work; what should it do. Think about these
-things:
-@itemize @bullet
-@item @emph{functionality:} What functionality should it have? What
-attributes or configuration is exposed to the user?
-@item @emph{reusability:} How much should others be able to reuse my design?
-Can I reuse code from ns-2 to get started? How does a user integrate
-the model with the rest of another simulation?
-@item @emph{dependencies:} How can I reduce the introduction of
-outside dependencies on my new code as much as possible (to make it
-more modular)? For instance, should I avoid any dependence on IPv4 if
-I want it to also be used by IPv6? Should I avoid any dependency
-on IP at all?
-@end itemize
-
-Do not be hesitant to contact the ns-3-users or ns-developers list if
-you have questions. In particular, it is important to think about
-the public API of your new model and ask for feedback. It also helps
-to let others know of your work in case you are interested in
-collaborators.
-
-@subsection Example: ErrorModel
-
-An error model exists in ns-2. It allows packets to be passed to
-a stateful object that determines, based on a random
-variable, whether the packet is corrupted. The caller can then
-decide what to do with the packet (drop it, etc.).
-
-The main API of the error model is a function to pass a packet
-to, and the return value of this function is a boolean that
-tells the caller whether any corruption occurred. Note that
-depending on the error model, the packet data buffer may or may
-not be corrupted. Let's call this function "IsCorrupt()".
-
-So far, in our design, we have:
-@verbatim
-class ErrorModel
-{
-public:
- /**
- * \returns true if the Packet is to be considered as errored/corrupted
- * \param pkt Packet to apply error model to
- */
- bool IsCorrupt (Ptr<Packet> pkt);
-};
-@end verbatim
-Note that we do not pass a const pointer, thereby allowing the function
-to modify the packet if IsCorrupt() returns true. Not all error models
-will actually modify the packet; whether or not the packet data
-buffer is corrupted should be documented.
-
-We may also want specialized versions of this, such as in ns-2, so
-although it is not the only design choice for polymorphism, we assume
-that we will subclass a base class ErrorModel for specialized classes,
-such as RateErrorModel, ListErrorModel, etc, such as is done in ns-2.
-
-You may be thinking at this point, "Why not make IsCorrupt() a virtual
-method?". That is one approach; the other is to make the public
-non-virtual function indirect through a private virtual function
-(this in C++ is known as the non virtual interface idiom and is
-adopted in the ns-3 ErrorModel class).
-
-Next, should this device have any dependencies on IP or other protocols?
-We do not want to create dependencies on Internet protocols (the error
-model should be applicable to non-Internet protocols too), so we'll keep
-that in mind later.
-
-Another consideration is how objects will include this error model.
-We envision putting an explicit setter in certain NetDevice implementations,
-for example.
-@verbatim
- /**
- * Attach a receive ErrorModel to the PointToPointNetDevice.
- *
- * The PointToPointNetDevice may optionally include an ErrorModel in
- * the packet receive chain.
- *
- * @see ErrorModel
- * @param em Ptr to the ErrorModel.
- */
- void PointToPointNetDevice::SetReceiveErrorModel(Ptr<ErrorModel> em);
-@end verbatim
-Again, this is not the only choice we have (error models could be aggregated
-to lots of other objects), but it satisfies our primary use case, which
-is to allow a user to force errors on otherwise successful packet
-transmissions, at the NetDevice level.
-
-After some thinking and looking at existing ns-2 code, here is a sample
-API of a base class and first subclass that could be posted for initial
-review:
-@verbatim
-class ErrorModel
-{
-public:
- ErrorModel ();
- virtual ~ErrorModel ();
- bool IsCorrupt (Ptr<Packet> pkt);
- void Reset (void);
- void Enable (void);
- void Disable (void);
- bool IsEnabled (void) const;
-private:
- virtual bool DoCorrupt (Ptr<Packet> pkt) = 0;
- virtual void DoReset (void) = 0;
-};
-
-enum ErrorUnit
- {
- EU_BIT,
- EU_BYTE,
- EU_PKT
- };
-
-// Determine which packets are errored corresponding to an underlying
-// random variable distribution, an error rate, and unit for the rate.
-class RateErrorModel : public ErrorModel
-{
-public:
- RateErrorModel ();
- virtual ~RateErrorModel ();
- enum ErrorUnit GetUnit (void) const;
- void SetUnit (enum ErrorUnit error_unit);
- double GetRate (void) const;
- void SetRate (double rate);
- void SetRandomVariable (const RandomVariable &ranvar);
-private:
- virtual bool DoCorrupt (Ptr<Packet> pkt);
- virtual void DoReset (void);
-};
-@end verbatim
-
-@node Scaffolding
-@section Scaffolding
-
-Let's say that you are ready to start implementing; you have a fairly clear
-picture of what you want to build, and you may have solicited some
-initial review or suggestions from the list.
-One way to approach the next step (implementation) is to create scaffolding
-and fill in the details as the design matures.
-
-This section walks through many of the steps you should consider to
-define scaffolding, or a non-functional skeleton of what your model
-will eventually implement. It is usually good practice to not wait
-to get these details integrated at the end, but instead to plumb a
-skeleton of your model into the system early and then add functions
-later once the API and integration seems about right.
-
-Note that you will want to modify a few things in the below presentation
-for your model since if you follow the error model verbatim, the code
-you produce will collide with the existing error model. The below is
-just an outline of how ErrorModel was built that you can adapt to
-other models.
-
-@subsection Review the ns-3 coding style document
-
-At this point, you may want to pause and read the ns-3 coding
-style document, especially if you are considering to contribute your
-code back to the project. The coding style document is linked off
-the main project page:
-@uref{http://www.nsnam.org/codingstyle.html,,ns-3 coding style}.
-
-@subsection Decide where in the source tree the model will reside in
-
-All of the ns-3 model source code is in the directory @code{src/}.
-You will need to choose which subdirectory it resides in. If it is
-new model code of some sort, it makes sense to put it into the
-@code{src/} directory somewhere, particularly for ease of integrating
-with the build system.
-
-In the case of the error model, it is very related to the packet
-class, so it makes sense to implement this in the @code{src/common/}
-directory where ns-3 packets are implemented.
-
-@subsection waf and wscript
-
-ns-3 uses the @uref{http://www.freehackers.org/~tnagy/waf.html,,Waf}
-build system. You will want to integrate your new
-ns-3 uses the Waf build system. You will want to integrate your new
-source files into this system. This requires that you add your files
-to the @code{wscript} file found in each directory.
-
-Let's start with empty files error-model.h and error-model.cc, and
-add this to @code{src/common/wscript}. It is really just a matter
-of adding the .cc file to the rest of the source files, and the .h
-file to the list of the header files.
-
-Now, pop up to the top level directory and type "./waf --check". You
-shouldn't have broken anything by this operation.
-@subsection include guards
-Next, let's add some
-@uref{http://en.wikipedia.org/wiki/Include_guard,,include guards} in our
-header file.
-@verbatim
-#ifndef ERROR_MODEL_H
-#define ERROR_MODEL_H
-...
-#endif
-@end verbatim
-
-@subsection namespace ns3
-ns-3 uses the ns3 @uref{http://en.wikipedia.org/wiki/Namespace_(computer_science)#Use_in_common_languages,,namespace}
-to isolate its symbols from other namespaces.
-Typically, a user will next put an ns-3 namespace block in both the cc and
-h file.
-@verbatim
-namespace ns3 {
-...
-}
-@end verbatim
-
-At this point, we have some skeletal files in which we can start defining
-our new classes. The header file looks like this:
-
-@verbatim
-#ifndef ERROR_MODEL_H
-#define ERROR_MODEL_H
-
-namespace ns3 {
-
-} // namespace ns3
-#endif
-@end verbatim
-while the @code{error-model.cc} file simply looks like this:
-@verbatim
-#include "error-model.h"
-
-namespace ns3 {
-
-} // namespace ns3
-@end verbatim
-These files should compile since they don't really have any contents.
-We're now ready to start adding classes.
-
-@node Initial Implementation
-@section Initial Implementation
-
-At this point, we're still working on some scaffolding, but we can
-begin to define our classes, with the functionality to be added later.
-
-@subsection use of class Object?
-
-This is an important design step; whether to use @code{class Object} as
-a base class for your new classes.
-
-As described in the chapter on the ns-3 @ref{Object model}, classes that
-inherit from @code{class Object} get special properties:
-@itemize @bullet
-@item the ns-3 type and attribute system (see @ref{Attributes})
-@item an object aggregation system
-@item a smart-pointer reference counting system (class Ptr)
-@end itemize
-
-Classes that derive from @code{class ObjectBase} get the first two
-properties above, but do not get smart pointers. Classes that
-derive from @code{class RefCountBase} get only the smart-pointer
-reference counting system.
-
-In practice, @code{class Object} is the variant of the three above that
-the ns-3 developer will most commonly encounter.
-
-In our case, we want to make use of the attribute system, and we
-will be passing instances of this object across the ns-3 public API,
-so @code{class Object} is appropriate for us.
-
-@subsection initial classes
-
-One way to proceed is to start by defining the bare minimum functions
-and see if they will compile. Let's review what all is needed to
-implement when we derive from class Object.
-
-@verbatim
-#ifndef ERROR_MODEL_H
-#define ERROR_MODEL_H
-
-#include "ns3/object.h"
-
-namespace ns3 {
-
-class ErrorModel : public Object
-{
-public:
- static TypeId GetTypeId (void);
-
- ErrorModel ();
- virtual ~ErrorModel ();
-};
-
-class RateErrorModel : public ErrorModel
-{
-public:
- static TypeId GetTypeId (void);
-
- RateErrorModel ();
- virtual ~RateErrorModel ();
-};
-#endif
-@end verbatim
-
-A few things to note here. We need to include @code{object.h}. The
-convention in ns-3 is that if the header file is co-located in the
-same directory, it may be included without any path prefix. Therefore,
-if we were implementing ErrorModel in @code{src/core} directory, we could
-have just said "@code{#include "object.h"}". But we are in @code{src/common},
-so we must include it as "@code{#include "ns3/object.h"}". Note also
-that this goes outside the namespace declaration.
-
-Second, each class must implement a static public member function
-called @code{GetTypeId (void)}.
-
-Third, it is a good idea to implement constructors and destructors rather
-than to let the compiler generate them, and to make the destructor virtual.
-In C++, note also that copy assignment operator and copy constructors
-are auto-generated if they are not defined, so if you do not want those,
-you should implement those as private members. This aspect of C++ is
-discussed in Scott Meyers' Effective C++ book. item 45.
-
-Let's now look at some corresponding skeletal implementation code in the .cc
-file.
-
-@verbatim
-#include "error-model.h"
-
-namespace ns3 {
-
-NS_OBJECT_ENSURE_REGISTERED (ErrorModel);
-
-TypeId ErrorModel::GetTypeId (void)
-{
- static TypeId tid = TypeId ("ns3::ErrorModel")
- .SetParent<Object> ()
- ;
- return tid;
-}
-
-ErrorModel::ErrorModel ()
-{
-}
-
-ErrorModel::~ErrorModel ()
-{
-}
-
-NS_OBJECT_ENSURE_REGISTERED (RateErrorModel);
-
-TypeId RateErrorModel::GetTypeId (void)
-{
- static TypeId tid = TypeId ("ns3::RateErrorModel")
- .SetParent<ErrorModel> ()
- .AddConstructor<RateErrorModel> ()
- ;
- return tid;
-}
-
-RateErrorModel::RateErrorModel ()
-{
-}
-
-RateErrorModel::~RateErrorModel ()
-{
-}
-@end verbatim
-
-What is the @code{GetTypeId (void)} function? This function does a few
-things. It registers a unique string into the TypeId system. It establishes
-the hierarchy of objects in the attribute system (via @code{SetParent}).
-It also declares that certain objects can be created via the object
-creation framework (@code{AddConstructor}).
-
-The macro @code{NS_OBJECT_ENSURE_REGISTERED (classname)} is needed also
-once for every class that defines a new GetTypeId method, and it does
-the actual registration of the class into the system.
-The @ref{Object model} chapter discusses this in more detail.
-
-@subsection how to include files from elsewhere
-@subsection log component
-
-@cartouche
-Here, write a bit about adding ns-3 logging macros. Note that @*
-LOG_COMPONENT_DEFINE is done outside the namespace ns3
-@end cartouche
-
-@subsection constructor, empty function prototypes
-
-@subsection key variables (default values, attributes)
-
-@subsection test program 1
-
-
-
-@subsection Object Framework
-@smallformat
-@example
- static const ClassId cid;
-
-
-const InterfaceId ErrorModel::iid =
- MakeInterfaceId ("ErrorModel", Object::iid);
-
-const ClassId ErrorModel::cid =
- MakeClassId<ErrorModel> ("ErrorModel", ErrorModel::iid);
-@end example
-@end smallformat
-
-@node Adding-a-sample-script
-@section Adding a sample script
-
-At this point, one may want to try to take the basic scaffolding
-defined above and add it into the system. Performing this step
-now allows one to use a simpler model when plumbing into the system
-and may also reveal whether any design or API modifications need to be
-made. Once this is done, we will return to building out the functionality
-of the ErrorModels themselves.
-
-@subsection Add basic support in the class
-
-@smallformat
-@example
-point-to-point-net-device.h
- class ErrorModel;
-
- /**
- * Error model for receive packet events
- */
- Ptr<ErrorModel> m_receiveErrorModel;
-
-@end example
-@end smallformat
-
-@subsection Add Accessor
-
-@smallformat
-@example
- void
-PointToPointNetDevice::SetReceiveErrorModel (Ptr<ErrorModel> em)
-@{
- NS_LOG_FUNCTION (this << em);
- m_receiveErrorModel = em;
-@}
-
- .AddAttribute ("ReceiveErrorModel",
- "The receiver error model used to simulate packet loss",
- PointerValue (),
- MakePointerAccessor (&PointToPointNetDevice::m_receiveErrorModel),
- MakePointerChecker<ErrorModel> ())
-@end example
-@end smallformat
-
-@subsection Plumb into the system
-
-@smallformat
-@example
-void PointToPointNetDevice::Receive (Ptr<Packet> packet)
-@{
- NS_LOG_FUNCTION (this << packet);
- uint16_t protocol = 0;
-
- if (m_receiveErrorModel && m_receiveErrorModel->IsCorrupt (packet) )
- @{
-//
-// If we have an error model and it indicates that it is time to lose a
-// corrupted packet, don't forward this packet up, let it go.
-//
- m_dropTrace (packet);
- @}
- else
- @{
-//
-// Hit the receive trace hook, strip off the point-to-point protocol header
-// and forward this packet up the protocol stack.
-//
- m_rxTrace (packet);
- ProcessHeader(packet, protocol);
- m_rxCallback (this, packet, protocol, GetRemote ());
- if (!m_promiscCallback.IsNull ())
- @{ m_promiscCallback (this, packet, protocol, GetRemote (),
- GetAddress (), NetDevice::PACKET_HOST);
- @}
- @}
-@}
-@end example
-@end smallformat
-
-@subsection Create null functional script
-
-@smallformat
-@example
-simple-error-model.cc
-
- // Error model
- // We want to add an error model to node 3's NetDevice
- // We can obtain a handle to the NetDevice via the channel and node
- // pointers
- Ptr<PointToPointNetDevice> nd3 = PointToPointTopology::GetNetDevice
- (n3, channel2);
- Ptr<ErrorModel> em = Create<ErrorModel> ();
- nd3->SetReceiveErrorModel (em);
-
-
-bool
-ErrorModel::DoCorrupt (Packet& p)
-@{
- NS_LOG_FUNCTION;
- NS_LOG_UNCOND("Corrupt!");
- return false;
-@}
-@end example
-@end smallformat
-
-At this point, we can run the program with our trivial ErrorModel
-plumbed into the receive path of the PointToPointNetDevice. It
-prints out the string "Corrupt!" for each packet received at
-node n3. Next, we return to the error model to add in a subclass
-that performs more interesting error modeling.
-
-@node Add subclass
-@section Add subclass
-
-The trivial base class ErrorModel does not do anything interesting,
-but it provides a useful base class interface (Corrupt () and Reset ()),
-forwarded to virtual functions that can be subclassed. Let's next
-consider what we call a BasicErrorModel which is based on the
-ns-2 ErrorModel class (in ns-2/queue/errmodel.@{cc,h@}).
-
-What properties do we want this to have, from a user interface
-perspective? We would like for the user to be able to trivially
-swap out the type of ErrorModel used in the NetDevice. We would also
-like the capability to set configurable parameters.
-
-Here are a few simple requirements we will consider:
-@itemize @bullet
-@item Ability to set the random variable that governs the losses
-(default is UniformVariable)
-@item Ability to set the unit (bit, byte, packet, time) of granularity
-over which errors are applied.
-@item Ability to set the rate of errors (e.g. 10^-3) corresponding to
-the above unit of granularity.
-@item Ability to enable/disable (default is enabled)
-@end itemize
-
-@subsection How to subclass
-
-We declare BasicErrorModel to be a subclass of ErrorModel as follows,
-
-@smallformat
-@example
-class BasicErrorModel : public ErrorModel
-@{
-public:
- static TypeId GetTypeId (void);
- ...
-private:
- // Implement base class pure virtual functions
- virtual bool DoCorrupt (Ptr<Packet> p);
- virtual bool DoReset (void);
- ...
-@}
-@end example
-@end smallformat
-
-and configure the subclass GetTypeId function by setting a unique
-TypeId string and setting the Parent to ErrorModel:
-
-@verbatim
-TypeId RateErrorModel::GetTypeId (void)
-@{
- static TypeId tid = TypeId ("ns3::RateErrorModel")
- .SetParent<ErrorModel> ()
- .AddConstructor<RateErrorModel> ()
- ...
-@end verbatim
-
-@node Build-core-functions-and-unit-tests
-@section Build core functions and unit tests
-
-@subsection assert macros
-
-@subsection Writing unit tests
-
-
--- a/doc/manual/node.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,119 +0,0 @@
-@node Node and NetDevices Overview
-@chapter Node and NetDevices Overview
-@anchor{chap:Node}
-
-@menu
-* NodeList::
-@end menu
-
-This chapter describes how ns-3 nodes are put together, and provides
-a walk-through of how packets traverse an internet-based Node.
-
-@float Figure,fig:node
-@caption{High-level node architecture.}
-@image{figures/node,5in}
-@end float
-
-In ns-3, nodes are instances of @code{class Node}. This class
-may be subclassed, but instead, the conceptual model is that
-we @emph{aggregate} or insert objects to it rather than define
-subclasses.
-
-One might think of a bare ns-3 node as a shell of a computer,
-to which one may add NetDevices (cards) and other innards including
-the protocols and applications. @ref{fig:node} illustrates
-that Node objects contain a list of Applications (initially,
-the list is empty), a list of NetDevices (initially, the list
-is empty), a list of ProtocolHandlers, a unique integer ID, and
-a system ID (for distributed simulation).
-
-The design tries to avoid putting too many dependencies on the
-base class Node, Application, or NetDevice for the following:
-@itemize @bullet
-@item IP version, or whether IP is at all even used in the Node.
-@item implementation details of the IP stack
-@end itemize
-
-From a software perspective, the lower interface of applications
-corresponds to the C-based sockets API. The upper interface
-of NetDevice objects corresponds to the device independent
-sublayer of the Linux stack. Everything in between can be
-aggregated and plumbed together as needed.
-
-Let's look more closely at the protocol demultiplexer. We want
-incoming frames at layer-2 to be delivered to the right layer-3
-protocol such as Ipv4. The
-function of this demultiplexer is to register callbacks for
-receiving packets. The callbacks are indexed based on the
-@uref{http://en.wikipedia.org/wiki/EtherType,,EtherType}
-in the layer-2 frame.
-
-Many different types of higher-layer protocols may be
-connected to the NetDevice, such as IPv4, IPv6, ARP,
-MPLS, IEEE 802.1x, and packet sockets. Therefore, the
-use of a callback-based demultiplexer avoids the need to
-use a common base class for all of these protocols, which
-is problematic because of the different types of objects
-(including packet sockets) expected to be registered there.
-
-Each NetDevice delivers packets to a callback with the following
-signature:
-@verbatim
- /**
- * \param device a pointer to the net device which is calling this callback
- * \param packet the packet received
- * \param protocol the 16 bit protocol number associated with this packet.
- * This protocol number is expected to be the same protocol number
- * given to the Send method by the user on the sender side.
- * \param address the address of the sender
- * \returns true if the callback could handle the packet successfully,
- * false otherwise.
- */
- typedef Callback<bool, Ptr<NetDevice>, Ptr<Packet>, uint16_t,
- const Address &> ReceiveCallback;
-@end verbatim
-
-There is a function in class Node that matches that signature:
-@verbatim
-private:
- bool ReceiveFromDevice (Ptr<NetDevice> device, Ptr<Packet>,
- uint16_t protocol, const Address &from);
-@end verbatim
-
-However, users do not need to access this function directly. Instead,
-when users call @code{uint32_t AddDevice (Ptr<NetDevice> device)},
-the implementation of this function sets the callback (and the
-function returns the ifIndex of the NetDevice on that Node).
-
-But what does the ReceiveFromDevice function do? Here, it looks
-up another callback, in its list of callbacks, corresponding to the
-matching EtherType. This callback is called a ProtocolHandler, and
-is specified as follows:
-@verbatim
- typedef Callback<void, Ptr<NetDevice>, Ptr<Packet>, uint16_t,
- const Address &> ProtocolHandler;
-@end verbatim
-
-Upper-layer protocols or objects are expected to provide such a function.
-and register it with the list of ProtocolHandlers by calling
-@code{Node::RegisterProtocolHandler ();}
-For instance, if Ipv4 is aggregated to a Node, then the Ipv4 receive
-function can be registered with the protocol handler by calling:
-@verbatim
- RegisterProtocolHandler (
- MakeCallback (&Ipv4L3Protocol::Receive, ipv4),
- Ipv4L3Protocol::PROT_NUMBER, 0);
-@end verbatim
-and likewise for Ipv6, ARP, etc.
-
-@node NodeList
-@section NodeList
-
-Every Node created is automatically added to the ns-3 @code{NodeList}.
-The NodeList class provides an @code{Add()} method and C++ iterators
-to allow one to walk the node list or fetch a Node pointer by
-its integer identifier.
-
-The following chapters provide reference information on the available
-NetDevices in ns-3.
-
--- a/doc/manual/objects.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,322 +0,0 @@
-@c ========================================================================
-@c ns-3 Object model
-@c ========================================================================
-
-@node Object model
-@chapter Object model
-
-@menu
-* Object-oriented behavior::
-* Object base classes::
-* Memory management and class Ptr::
-* Object factories::
-* Downcasting::
-@end menu
-
-@command{ns-3} is fundamentally a C++ object system. Objects can
-be declared and instantiated as usual, per C++ rules. ns-3 also
-adds some features to traditional C++ objects, as described below,
-to provide greater functionality and features. This manual chapter
-is intended to introduce the reader to the ns-3 object model.
-
-This section describes the C++ class design for ns-3 objects. In brief,
-several design patterns in use include classic object-oriented design
-(polymorphic interfaces and implementations), separation of interface
-and implementation, the non-virtual public interface design pattern,
-an object aggregation facility, and reference counting
-for memory management. Those familiar with component models such
-as COM or Bonobo will recognize elements of the design in the
-ns-3 object aggregation model, although
-the ns-3 design is not strictly in accordance with either.
-
-@node Object-oriented behavior
-@section Object-oriented behavior
-
-C++ objects, in general, provide common object-oriented capabilities
-(abstraction, encapsulation, inheritance, and polymorphism) that are part
-of classic object-oriented design. ns-3 objects make use of these
-properties; for instance:
-
-@verbatim
-class Address
-{
-public:
- Address ();
- Address (uint8_t type, const uint8_t *buffer, uint8_t len);
- Address (const Address & address);
- Address &operator = (const Address &address);
- ...
-private:
- uint8_t m_type;
- uint8_t m_len;
- ...
-};
-@end verbatim
-
-@node Object base classes
-@section Object base classes
-
-There are three special base classes used in ns-3. Classes that inherit
-from these base classes can instantiate objects with special properties.
-These base classes are:
-@itemize @bullet
-@item @code{class Object}
-@item @code{class ObjectBase}
-@item @code{class SimpleRefCount}
-@end itemize
-It is not required that ns-3 objects inherit from these class, but
-those that do get special properties. Classes deriving from
-@code{class Object} get the following properties.
-@itemize @bullet
-@item the ns-3 type and attribute system (see @ref{Attributes})
-@item an object aggregation system
-@item a smart-pointer reference counting system (class Ptr)
-@end itemize
-
-Classes that derive from @code{class ObjectBase} get the first two
-properties above, but do not get smart pointers. Classes that
-derive from @code{class SimpleRefCount} get only the smart-pointer
-reference counting system.
-
-In practice, @code{class Object} is the variant of the three above that
-the ns-3 developer will most commonly encounter.
-
-@node Memory management and class Ptr
-@section Memory management and class Ptr
-
-Memory management in a C++ program is a complex process, and is
-often done incorrectly or inconsistently. We have settled on
-a reference counting design described as follows.
-
-All objects using reference counting maintain an internal reference
-count to determine when an object can safely delete itself.
-Each time that a pointer is obtained to an interface, the object's
-reference count is incremented by calling @code{Ref()}.
-It is the obligation of the
-user of the pointer to explicitly @code{Unref()} the pointer when done.
-When the reference count falls to zero, the object is deleted.
-
-@itemize @bullet
-@item When the client code obtains a pointer from the object itself
-through object creation, or via GetObject, it does not have
-to increment the reference count.
-@item When client code obtains a pointer from another source (e.g.,
-copying a pointer) it must call @code{Ref()} to increment the
-reference count.
-@item All users of the object pointer must call @code{Unref()} to
-release the reference.
-@end itemize
-
-The burden for calling @code{Unref()} is somewhat relieved by the
-use of the reference counting smart pointer class described below.
-
-Users using a low-level API who wish to explicitly allocate
-non-reference-counted objects on the heap, using operator new,
-are responsible for deleting such objects.
-
-@subsection Reference counting smart pointer (Ptr)
-
-Calling @code{Ref()} and @code{Unref()} all the time would be cumbersome,
-so ns-3 provides a smart pointer @code{class Ptr} similar to
-@code{Boost::intrusive_ptr}.
-This smart-pointer class assumes that the underlying type provides
-a pair of Ref and Unref methods that are expected to increment and
-decrement the internal refcount of the object instance.
-
-This implementation allows you to manipulate the smart pointer
-as if it was a normal pointer: you can compare it with zero,
-compare it against other pointers, assign zero to it, etc.
-
-It is possible to extract the raw pointer from this
-smart pointer with the GetPointer and PeekPointer methods.
-
-If you want to store a newed object into a smart pointer,
-we recommend you to use the CreateObject template functions
-to create the object and store it in a smart pointer to avoid
-memory leaks. These functions are really small convenience
-functions and their goal is just to save you a small
-bit of typing.
-
-@subsection CreateObject and Create
-
-Objects in C++ may be statically, dynamically, or automatically created.
-This holds true for ns-3 also, but some objects in the system
-have some additional frameworks
-available. Specifically, reference counted objects are usually
-allocated using a templated Create or CreateObject method, as follows.
-
-For objects deriving from @code{class Object}:
-@verbatim
- Ptr<WifiNetDevice> device = CreateObject<WifiNetDevice> ();
-@end verbatim
-Please do not create such objects using @code{operator new}; create them
-using @code{CreateObject()} instead.
-
-For objects deriving from @code{class SimpleRefCount}, or other
-objects that support usage of the smart pointer class,
-a templated helper function is available and recommended to be used:
-@verbatim
- Ptr<B> b = Create<B> ();
-@end verbatim
-This is simply a wrapper around operator new that correctly handles
-the reference counting system.
-
-In summary, use @code{Create<B>} if B is not an object but just uses
-reference counting (e.g. @code{class Packet}), and use @code{CreateObject<B>}
-if B derives from @code{ns3::Object}.
-
-@subsection Aggregation
-
-The ns-3 object aggregation system is motivated in strong part by
-a recognition that a common use case for ns-2 has been the use of
-inheritance and polymorphism to extend protocol models. For instance,
-specialized versions of TCP such as RenoTcpAgent derive from (and override
-functions from) class TcpAgent.
-
-However, two problems that have arisen in the ns-2 model are downcasts
-and ``weak base class.'' Downcasting refers to the procedure of using
-a base class pointer to an object and querying it at run time to
-find out type information, used to explicitly cast the pointer to
-a subclass pointer so that the subclass API can be used.
-Weak base class refers to the problems that arise when a class
-cannot be effectively reused (derived from) because it lacks necessary
-functionality, leading the developer to have to modify the
-base class and causing proliferation of base class API calls, some
-of which may not be semantically correct for all subclasses.
-
-ns-3 is using a version of the query interface design pattern
-to avoid these problems. This design is based on elements of the
-@uref{http://en.wikipedia.org/wiki/Component_Object_Model,,Component Object Model}
-and @uref{http://en.wikipedia.org/wiki/Bonobo_(component_model),,GNOME Bonobo}
-although full binary-level compatibility of replaceable components
-is not supported and we have tried to simplify the syntax and impact
-on model developers.
-
-@subsubsection Aggregation example
-
-@code{class Node} is a good example of the use of aggregation in ns-3.
-Note that there are not derived classes of Nodes in ns-3 such as
-class InternetNode. Instead, components (protocols) are aggregated to
-a node. Let's look at how some Ipv4 protocols are added to a node.
-
-@verbatim
-static void
-AddIpv4Stack(Ptr<Node> node)
-{
- Ptr<Ipv4L3Protocol> ipv4 = CreateObject<Ipv4L3Protocol> ();
- ipv4->SetNode (node);
- node->AggregateObject (ipv4);
- Ptr<Ipv4Impl> ipv4Impl = CreateObject<Ipv4Impl> ();
- ipv4Impl->SetIpv4 (ipv4);
- node->AggregateObject (ipv4Impl);
-}
-@end verbatim
-
-Note that the Ipv4 protocols are created using @code{CreateObject()}.
-Then, they are aggregated to the node. In this manner, the Node base
-class does not need to be edited to allow users with a base class Node
-pointer to access the Ipv4 interface; users may ask the node for a pointer
-to its Ipv4 interface at runtime. How the user asks the node is described
-in the next subsection.
-
-Note that it is a programming error to aggregate more than one object of
-the same type to an ns3::Object. So, for instance, aggregation is not
-an option for storing all of the active sockets of a node.
-
-@subsubsection GetObject example
-GetObject is a type-safe way to achieve a safe downcasting
-and to allow interfaces to be found on an object.
-
-Consider a node pointer @code{m_node} that points to a Node object
-that has an implementation of IPv4 previously aggregated to it. The
-client code wishes to configure
-a default route. To do so, it must access an object within
-the node that has an interface to the IP forwarding configuration.
-It performs the following:
-@verbatim
- Ptr<Ipv4> ipv4 = m_node->GetObject<Ipv4> ();
-@end verbatim
-
-If the node in fact does not have an Ipv4 object aggregated to it, then
-the method will return null. Therefore, it is good practice to check
-the return value from such a function call. If successful, the user can
-now use the Ptr to the Ipv4 object that was previously aggregated to
-the node.
-
-Another example of how one might use aggregation is to add optional
-models to objects.
-For instance, an existing Node object may have an ``Energy Model''
-object aggregated to it at run time (without modifying
-and recompiling the node class). An existing model (such as a wireless
-net device) can then later "GetObject" for the energy model and act
-appropriately if the interface has been either built in to the underlying
-Node object or aggregated to it at run time. However, other nodes need
-not know anything about energy models.
-
-We hope that this mode of programming will require much less
-need for developers to modify the base classes.
-
-@node Object factories
-@section Object factories
-
-A common use case is to create lots of similarly configured objects.
-One can repeatedly call @code{CreateObject} but there is also a
-factory design pattern in use in the ns-3 system. It is heavily
-used in the "helper" API.
-
-Class @code{ObjectFactory} can be used to instantiate objects and
-to configure the attributes on those objects
-
-@verbatim
- void SetTypeId (TypeId tid);
- void Set (std::string name, const AttributeValue &value);
- Ptr<T> Create (void) const;
-@end verbatim
-
-The first method allows one to use the ns-3 TypeId system to specify
-the type of objects created. The second allows one to set
-attributes on the objects to be created, and the third allows one
-to create the objects themselves.
-
-For example:
-@verbatim
- ObjectFactory factory;
- // Make this factory create objects of type FriisPropagationLossModel
- factory.SetTypeId ("ns3::FriisPropagationLossModel")
- // Make this factory object change a default value of an attribute, for
- // subsequently created objects
- factory.Set ("SystemLoss", DoubleValue (2.0));
- // Create one such object
- Ptr<Object> object = m_factory.Create ();
- factory.Set ("SystemLoss", DoubleValue (3.0));
- // Create another object
- Ptr<Object> object = m_factory.Create ();
-@end verbatim
-
-@node Downcasting
-@section Downcasting
-
-A question that has arisen several times is, "If I have a base class
-pointer (Ptr) to an object and I want the derived class pointer, should
-I downcast (via C++ dynamic cast) to get the derived pointer, or should
-I use the object aggregation system to @code{GetObject<> ()} to find
-a Ptr to the interface to the subclass API?"
-
-The answer to this is that in many situations, both techniques will work.
-ns-3 provides a templated function for making the syntax of Object
-dynamic casting much more user friendly:
-@verbatim
-template <typename T1, typename T2>
-Ptr<T1>
-DynamicCast (Ptr<T2> const&p)
-{
- return Ptr<T1> (dynamic_cast<T1 *> (PeekPointer (p)));
-}
-@end verbatim
-
-DynamicCast works when the programmer has a base type pointer and is
-testing against a subclass pointer. GetObject works when looking for
-different objects aggregated, but also works with subclasses, in the same
-way as DynamicCast. If unsure, the programmer should use GetObject, as it
-works in all cases. If the programmer knows the class hierarchy of the
-object under consideration, it is more direct to just use DynamicCast.
--- a/doc/manual/organization.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,55 +0,0 @@
-@node Organization
-@chapter Organization
-
-This manual is organized into several parts with several chapters per part.
-This chapter describes the overall software organization and the
-corresponding organization of this manual.
-
-ns-3 is a discrete-event network simulator in which the simulation core
-and models are implemented in C++. ns-3 is built as a library which
-may be statically or dynamically linked to a C++ main program that
-defines the simulation topology and starts the simulator. ns-3 also
-exports nearly all of its API to Python, allowing Python programs to
-import an "ns3" module in much the same way as in C++.
-
-@float Figure,fig:organization
-@caption{Software organization of ns-3}
-@center @image{figures/software-organization, 5in}
-@end float
-
-The source code for ns-3 is mostly organized in the @code{src/}
-directory and can be described by the diagram in @ref{fig:organization}.
-We will work our way from the bottom up; in general, modules
-only have dependencies on modules beneath them in the figure.
-
-We first describe Part 1 of the manual.
-The simulation core is implemented in @code{src/core}, and the core is
-used to build the simulation engine @code{src/simulator}. Packets are
-fundamental objects in a network simulator and are implemented in
-@code{src/packet}. These three simulation modules by themselves
-are intended to comprise a generic simulation core that can be used
-by different kinds of networks, not just Internet-based networks.
-The above modules of ns-3 are independent of specific network and
-device models, which are covered in later parts of this manual.
-
-In addition to the above ns-3 core, we describe also in Part 1 two
-other modules that supplement the core C++-based API. ns-3 programs
-may access all of the API directly or may make use of a so-called
-``helper API'' that provides convenient wrappers or encapsulation of
-low-level API calls. The fact that ns-3 programs can be written to
-two APIs (or a combination thereof) is a fundamental aspect of the
-simulator and is also covered in Part 1. We also describe how
-Python is supported in ns-3 as the last chapter of Part 1.
-
-The remainder of the manual is focused on documenting the models
-and supporting capabilities. Part 2 focuses on two fundamental
-objects in ns-3: the @code{Node} and @code{NetDevice}. Two
-special NetDevice types are designed to support network emulation
-use cases, and emulation is described in Part 3.
-Part 4 is devoted to Internet-related models, including the sockets
-API used by Internet applications. Part 5 covers applications, and
-Part 6 describes additional support for simulation, such as animators.
-
-The project maintains a separate manual devoted to testing and
-validation of ns-3 code (see the
-@uref{http://www.nsnam.org/tutorials.html,, ns-3 Testing and Validation manual}).
--- a/doc/manual/other.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,2189 +0,0 @@
-@c ========================================================================
-@c Other Network Topologies
-@c ========================================================================
-
-@node Other-network-topologies
-@chapter Other Network Topologies
-@cindex topology
-@cindex Channel
-@cindex NetDevice
-@cindex topology!bus
-@cindex topology!point-to-point
-@cindex PointToPointChannel
-@cindex PointToPointNetDevice
-
-@emph{Network topology} is the study of the arrangement of of the elements
-(in @command{ns-3} represented by the classes @code{Channel} and @code{Node})
-of a network. Two fundamental types of physical topologies are the
-@emph{point-to-point} and @emph{bus} topologies. We have already been exposed
-to the @command{ns-3} channel specialization named @code{CsmaChannel}. This is
-a simulation of a bus network. We also provide a simulation of a
-point-to-point channel with associated net devices. As described previously,
-the associated C++ classes specialize the @command{ns-3} base classes
-@code{NetDevice} and @code{Channel} and are called @code{PointToPointNetDevice}
-and @code{PointToPointChannel} respectively.
-
-We will use combinations of these bus and point-to-point topology elements
-to show how to create several commonly seen network topologies.
-
-@section A Point-to-Point Network
-We're going to take what might be seen as a step backward and look at a simple
-point-to-point network. We will be building the simplest network you can
-imagine. A serial link (point to point) between two computers. When you
-see this point-to-point network, you can think of an RS-422 (or RS-232 for
-you old-timers) cable. This topology is shown below.
-
-@sp 1
-@center @image{figures/pp,,,,png}
-
-@cindex CreateObject
-@cindex InternetNode
-We have provided a file for you in the @code{tutorial}
-directory called @code{tutorial-point-to-point.cc}. You should now be
-familiar enough with the system to pick out fairly easily what has been
-changed. Let's focus on the following lines:
-
-@verbatim
- Ptr<Node> n0 = CreateObject<InternetNode> ();
- Ptr<Node> n1 = CreateObject<InternetNode> ();
-
- Ptr<PointToPointChannel> link = PointToPointTopology::AddPointToPointLink (
- n0, n1, DataRate (38400), MilliSeconds (20));
-
- PointToPointTopology::AddIpv4Addresses (link, n0, "10.1.1.1",
- n1, "10.1.1.2");
-@end verbatim
-
-You can see that we created two @code{InternetNode} objects in the usual way.
-Then, instead of creating a @code{CsmaChannel} we create a
-@code{PointToPointChannel}. This point-to-point channel, which we call
-@code{link}, connects node zero (@code{n0}) and node one (@code{n1}) over a
-simulated link that runs at 38400 bits per second and has a 20 millisecond
-simulated speed-of-light delay. This call also creates appropriate net devices
-and attaches them to nodes zero and one.
-
-We then add IP addresses to the net devices we just created using the topology
-helper @code{AddIpv4Addresses}. Node zero gets the IP address 10.1.1.1 and
-node one gets the IP address 10.1.1.2 assigned.
-
-The alert tutorial user may wonder what the network number or prefix is of
-those IP addresses. The point-to-point topology assumes that you want a
-@code{/30} subnet and assigns an appropriate net mask for you. It then then
-@emph{asserts} that the network numbers of the two net devices match. So there
-is an implicit network mask created down in the topology code that looks like,
-
-@verbatim
- Ipv4Mask netmask("255.255.255.252");
-@end verbatim
-
-The rest of the code you should recognize and understand. We are just going
-to echo one packet across the point-to-point link. You should be now be able
-to build and run this example and to locate and interpret the ASCII trace
-file. This is left as an exercise for you.
-
-The file @code{tutorial-point-to-point.cc} is reproduced here for your
-convenience:
-
-@verbatim
-/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
-/*
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2 as
- * published by the Free Software Foundation;
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
-#include "ns3/log.h"
-#include "ns3/ptr.h"
-#include "ns3/internet-stack.h"
-#include "ns3/point-to-point-channel.h"
-#include "ns3/mac48-address.h"
-#include "ns3/point-to-point-net-device.h"
-#include "ns3/point-to-point-topology.h"
-#include "ns3/udp-echo-client.h"
-#include "ns3/udp-echo-server.h"
-#include "ns3/simulator.h"
-#include "ns3/nstime.h"
-#include "ns3/ascii-trace.h"
-#include "ns3/pcap-trace.h"
-#include "ns3/global-route-manager.h"
-
-NS_LOG_COMPONENT_DEFINE ("PointToPointSimulation");
-
-using namespace ns3;
-
-// Network topology
-//
-// point to point
-// +--------------+
-// | |
-// n0 n1
-//
-int
-main (int argc, char *argv[])
-{
- LogComponentEnable ("PointToPointSimulation", LOG_LEVEL_INFO);
-
- NS_LOG_INFO ("Point to Point Topology Simulation");
-
- Ptr<Node> n0 = CreateObject<InternetNode> ();
- Ptr<Node> n1 = CreateObject<InternetNode> ();
-
- Ptr<PointToPointChannel> link = PointToPointTopology::AddPointToPointLink (
- n0, n1, DataRate (38400), MilliSeconds (20));
-
- PointToPointTopology::AddIpv4Addresses (link, n0, "10.1.1.1",
- n1, "10.1.1.2");
-
- uint16_t port = 7;
-
- Ptr<UdpEchoClient> client = CreateObject<UdpEchoClient> (n0, "10.1.1.2",
- port, 1, Seconds(1.), 1024);
-
- Ptr<UdpEchoServer> server = CreateObject<UdpEchoServer> (n1, port);
-
- server->Start(Seconds(1.));
- client->Start(Seconds(2.));
-
- server->Stop (Seconds(10.));
- client->Stop (Seconds(10.));
-
- AsciiTrace asciitrace ("tutorial.tr");
- asciitrace.TraceAllQueues ();
- asciitrace.TraceAllNetDeviceRx ();
-
- Simulator::Run ();
- Simulator::Destroy ();
-}
-@end verbatim
-
-@section A Star Network
-A point-to-point network is considered a special case of a star network. As
-you might expect, the process of constructing a star network is an extension
-of the very simple process used for a point-to-point link. We have provided
-a file for you in the @code{tutorial} directory called @code{tutorial-star.cc}
-that implements a simple star network as seen below.
-
-@sp 1
-@center @image{figures/star,,,,png}
-
-In order to create a star network, we need to be able to instantiate some
-number (greater than one) of net devices on a node. In the name of simplicity
-of use, the @code{PointToPointTopology} topology helper does not allow one to
-do this. We provided a separate topology helper class, the
-@code{PointToPointIpv4Topology} helper class that provides the slightly finer
-granularity we need to accomplish a star network. In order to use this new
-helper we have to load the definitions by including the appropriate file.
-
-@verbatim
- #include "ns3/point-to-point-ipv4-topology.h"
-@end verbatim
-
-The star that we're going to create has a node in the center (@code{n0}) with
-six nodes surrounding (@code{n1} - @code{n6}). You should be able to easily
-find and understand the code that creates these nodes.
-
-@verbatim
- Ptr<Node> n0 = CreateObject<InternetNode> ();
- Ptr<Node> n1 = CreateObject<InternetNode> ();
- Ptr<Node> n2 = CreateObject<InternetNode> ();
- Ptr<Node> n3 = CreateObject<InternetNode> ();
- Ptr<Node> n4 = CreateObject<InternetNode> ();
- Ptr<Node> n5 = CreateObject<InternetNode> ();
- Ptr<Node> n6 = CreateObject<InternetNode> ();
-@end verbatim
-
-Next, we get into the differences between the @code{PointToPointTopology}
-helper and the @code{PointToPointIpv4Topology} helper. The
-@code{PointToPointIpv4Topology} helper looks and feels a little like the
-@code{CsmaIpv4Topology} helper. Just like you created a CSMA channel
-previously, you need to create a point-to-point channel. The following
-code creates a @code{PointToPointChannel} and calls it @code{link01}. You can
-interpret this name as being the channel (or @emph{link}) from node zero to
-node one.
-
-@verbatim
- Ptr<PointToPointChannel> link01 =
- PointToPointIpv4Topology::CreateChannel (DataRate (38400),
- MilliSeconds (20));
-@end verbatim
-
-You need to provide a data rate for the channel which we set at 38400 bits
-per second. You must also provide a speed-of-light delay which we set at
-20 milliseconds.
-
-Just as you added a net device to the nodes in the CSMA tutorial section, you
-do the same here but with a point-to-point net device. The following code
-illustrates how we do that:
-
-@verbatim
- uint32_t nd01 = PointToPointIpv4Topology::AddNetDevice (n0,
- link01);
-@end verbatim
-
-We call the @code{PointToPointIpv4Topology} helper and ask it to add a net
-device to node zero (@code{n0}) and connect it to the appropriate
-point-to-point link (@code{link01}) which you will recall is the serial link
-from node zero to node one.
-
-If you look at the following code, you will see the same calls are repeated
-to create the remaining five point-to-point channels and connect them
-to net devices on node zero.
-
-The next new code is found after the ``spokes'' of the star have been created.
-It looks like the following:
-
-@verbatim
- uint32_t nd1 = PointToPointIpv4Topology::AddNetDevice (n1, link01);
- uint32_t nd2 = PointToPointIpv4Topology::AddNetDevice (n2, link02);
- uint32_t nd3 = PointToPointIpv4Topology::AddNetDevice (n3, link03);
- uint32_t nd4 = PointToPointIpv4Topology::AddNetDevice (n4, link04);
- uint32_t nd5 = PointToPointIpv4Topology::AddNetDevice (n5, link05);
- uint32_t nd6 = PointToPointIpv4Topology::AddNetDevice (n6, link06);
-@end verbatim
-
-Here we are creating the net devices on the nodes surrounding the center node.
-In the first call, we are adding a net device on node one (@code{n1}) and
-connecting that net device to the channel named @code{link01}. Remember that
-we created the channel @code{link01} as the channel connecting node zero and
-node one. We previously created a net device on node zero and attached that
-device to @code{link01}. Here we are connecting the other side of that link
-to node one. The return value from this call is the net device index of the
-created net device.
-
-The next section of code adds addresses to the net devices we just created.
-The first call adds the IP address 10.1.1.1 to the net device going from
-node zero to node one. Recall that we first created a node named @code{n0}
-and a channel called @code{link01}. We added a net device to @code{n0} and
-remembered the net device index as the @code{uint32_t nd01}. This meant
-the net device @emph{nd} on node @emph{0} that we connected to node @emph{1}.
-We call @code{AddAddress} to add an IP address (10.1.1.1) to the net device
-on node zero identified by the net device index @code{nd01}. We provide a
-net mask suitable for a point to point network. This is typically a /30
-address but we don't force that in this API.
-
-After setting up the address on node zero, we do the same for the node on
-the other end of the ``spoke'' --- in this case node one, with its single
-net device. Note that the network number is the same on both sides of this
-network.
-
-@verbatim
- PointToPointIpv4Topology::AddAddress (n0, nd01, "10.1.1.1",
- ``255.255.255.252'');
-
- PointToPointIpv4Topology::AddAddress (n1, nd1, "10.1.1.2",
- ``255.255.255.252'');
-@end verbatim
-
-The following code repeats this pattern assining similar IP addresses to the
-remaining net devices. Note that there are no @code{Mac48Address} address
-assignments --- they are not required.
-
-The rest of the code you should recognize and understand. We are just going
-to echo one packet across the point-to-point link. You should be now be able
-to build and run this example and to locate and interpret the ASCII trace
-file. This is left as an exercise for you.
-
-The file @code{tutorial-star.cc} is reproduced here for your convenience:
-
-@verbatim
-/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
-/*
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2 as
- * published by the Free Software Foundation;
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
-#include "ns3/log.h"
-#include "ns3/ptr.h"
-#include "ns3/internet-stack.h"
-#include "ns3/point-to-point-channel.h"
-#include "ns3/mac48-address.h"
-#include "ns3/point-to-point-net-device.h"
-#include "ns3/point-to-point-ipv4-topology.h"
-#include "ns3/udp-echo-client.h"
-#include "ns3/udp-echo-server.h"
-#include "ns3/simulator.h"
-#include "ns3/nstime.h"
-#include "ns3/ascii-trace.h"
-#include "ns3/pcap-trace.h"
-#include "ns3/global-route-manager.h"
-
-NS_LOG_COMPONENT_DEFINE ("StarSimulation");
-
-using namespace ns3;
-
-// Network topology
-//
-// n3 n2
-// | /
-// | /
-// n4 --- n0 --- n1
-// / |
-// / |
-// n5 n6
-
-int
-main (int argc, char *argv[])
-{
- LogComponentEnable ("StarSimulation", LOG_LEVEL_INFO);
-
- NS_LOG_INFO ("Star Topology Simulation");
-
- Ptr<Node> n0 = CreateObject<InternetNode> ();
- Ptr<Node> n1 = CreateObject<InternetNode> ();
- Ptr<Node> n2 = CreateObject<InternetNode> ();
- Ptr<Node> n3 = CreateObject<InternetNode> ();
- Ptr<Node> n4 = CreateObject<InternetNode> ();
- Ptr<Node> n5 = CreateObject<InternetNode> ();
- Ptr<Node> n6 = CreateObject<InternetNode> ();
-
- Ptr<PointToPointChannel> link01 =
- PointToPointIpv4Topology::CreateChannel (DataRate (38400),
- MilliSeconds (20));
-
- uint32_t nd01 = PointToPointIpv4Topology::AddNetDevice (n0,
- link01);
-
- Ptr<PointToPointChannel> link02 =
- PointToPointIpv4Topology::CreateChannel (DataRate (38400),
- MilliSeconds (20));
-
- uint32_t nd02 = PointToPointIpv4Topology::AddNetDevice (n0,
- link02);
-
- Ptr<PointToPointChannel> link03 =
- PointToPointIpv4Topology::CreateChannel (DataRate (38400),
- MilliSeconds (20));
-
- uint32_t nd03 = PointToPointIpv4Topology::AddNetDevice (n0,
- link03);
-
- Ptr<PointToPointChannel> link04 =
- PointToPointIpv4Topology::CreateChannel (DataRate (38400),
- MilliSeconds (20));
-
- uint32_t nd04 = PointToPointIpv4Topology::AddNetDevice (n0,
- link04);
-
- Ptr<PointToPointChannel> link05 =
- PointToPointIpv4Topology::CreateChannel (DataRate (38400),
- MilliSeconds (20));
-
- uint32_t nd05 = PointToPointIpv4Topology::AddNetDevice (n0,
- link05);
-
- Ptr<PointToPointChannel> link06 =
- PointToPointIpv4Topology::CreateChannel (DataRate (38400),
- MilliSeconds (20));
-
- uint32_t nd06 = PointToPointIpv4Topology::AddNetDevice (n0, link06);
-
- uint32_t nd1 = PointToPointIpv4Topology::AddNetDevice (n1, link01);
- uint32_t nd2 = PointToPointIpv4Topology::AddNetDevice (n2, link02);
- uint32_t nd3 = PointToPointIpv4Topology::AddNetDevice (n3, link03);
- uint32_t nd4 = PointToPointIpv4Topology::AddNetDevice (n4, link04);
- uint32_t nd5 = PointToPointIpv4Topology::AddNetDevice (n5, link05);
- uint32_t nd6 = PointToPointIpv4Topology::AddNetDevice (n6, link06);
-
- PointToPointIpv4Topology::AddAddress (n0, nd01, "10.1.1.1",
- "255.255.255.252");
-
- PointToPointIpv4Topology::AddAddress (n1, nd1, "10.1.1.2",
- "255.255.255.252");
-
- PointToPointIpv4Topology::AddAddress (n0, nd02, "10.1.2.1",
- "255.255.255.252");
-
- PointToPointIpv4Topology::AddAddress (n2, nd2, "10.1.2.2",
- "255.255.255.252");
-
- PointToPointIpv4Topology::AddAddress (n0, nd03, "10.1.3.1",
- "255.255.255.252");
-
- PointToPointIpv4Topology::AddAddress (n3, nd3, "10.1.2.2",
- "255.255.255.252");
-
- PointToPointIpv4Topology::AddAddress (n0, nd04, "10.1.4.1",
- "255.255.255.252");
-
- PointToPointIpv4Topology::AddAddress (n4, nd4, "10.1.4.2",
- "255.255.255.252");
-
- PointToPointIpv4Topology::AddAddress (n0, nd05, "10.1.5.1",
- "255.255.255.252");
-
- PointToPointIpv4Topology::AddAddress (n5, nd5, "10.1.5.2",
- "255.255.255.252");
-
- PointToPointIpv4Topology::AddAddress (n0, nd06, "10.1.6.1",
- "255.255.255.252");
-
- PointToPointIpv4Topology::AddAddress (n6, nd6, "10.1.6.2",
- "255.255.255.252");
-
- uint16_t port = 7;
-
- Ptr<UdpEchoClient> client = CreateObject<UdpEchoClient> (n0, "10.1.1.2",
- port, 1, Seconds(1.), 1024);
-
- Ptr<UdpEchoServer> server = CreateObject<UdpEchoServer> (n1, port);
-
- server->Start(Seconds(1.));
- client->Start(Seconds(2.));
-
- server->Stop (Seconds(10.));
- client->Stop (Seconds(10.));
-
- AsciiTrace asciitrace ("tutorial.tr");
- asciitrace.TraceAllQueues ();
- asciitrace.TraceAllNetDeviceRx ();
-
- Simulator::Run ();
- Simulator::Destroy ();
-}
-@end verbatim
-
-@subsection Routing
-If you are really excited about this simulator you may have already tried to
-modify the scripts outside the tutorial. I know that one of the first things
-that would have occurred to me when I saw the star network would have been to
-start trying to add applications to echo packets from nodes other than zero.
-If you tried, for example, to start the echo client on node one instead of
-node zero, you would have found an empty trace file. The reason for this
-is that you have now created an internetwork. This means you will need to
-enable internetwork routing.
-
-We have provided a file for you in the @code{tutorial} directory called
-@code{tutorial-star-routing.cc} to show you how this is done. This extremely
-tricky and difficult change is shown below:
-
-@verbatim
- GlobalRouteManager::PopulateRoutingTables ();
-@end verbatim
-
-This one-line addition, located just before the simulation runs, tells the
-@command{ns-3} @emph{global route manager} to walk the topology you created and
-build internetwork routing tables for all of the nodes in the simulation.
-We changed the client application so that it runs on node four:
-
-@verbatim
- Ptr<UdpEchoClient> client = CreateObject<UdpEchoClient> (n4, "10.1.1.2",
- port, 1, Seconds(1.), 1024);
-@end verbatim
-
-Now if you build and run @code{tutorial-star-routing.cc} you can examine the
-@code{tutorial.tr} file and see that your UDP echo packets are now correctly
-routed through the topology.
-
-@section A Dumbbell Network
-One of the most interesting simple topologies (from a phenomenological point of
-view) is commonly called a dumbbell network. The name derives from a
-superficial similarity in form to a piece of exercise equipment.
-
-The dumbbell model is typically composed of two bus or star network elements
-connected via a point-to-point link. The point-to-point link is usually
-configured with a lower bandwidth than the bus elements to provide a
-@emph{choke point}.
-
-The following is a representation of the topology.
-
-@sp 1
-@center @image{figures/dumbbell,,,,png}
-
-We have provided a file that constructs this dumbbell network and creates
-enough data flowing across the choke point that some packets will be dropped.
-The file is called @code{tutorial-linear-dumbbell.cc} and is located in the
-@code{tutorial} directory. We have already covered all of the code used to
-create this network, so we will just quickly go over the main sections of the
-script.
-
-The first section creates a CSMA LAN that will become the left side of the
-dumbbell network. This code should be very familiar since we used the same
-process to create our first example.
-
-@verbatim
-//
-// Create the lan on the left side of the dumbbell.
-//
- Ptr<Node> n0 = CreateObject<InternetNode> ();
- Ptr<Node> n1 = CreateObject<InternetNode> ();
- Ptr<Node> n2 = CreateObject<InternetNode> ();
- Ptr<Node> n3 = CreateObject<InternetNode> ();
-
- Ptr<CsmaChannel> lan1 =
- CsmaTopology::CreateCsmaChannel (DataRate (10000000), MilliSeconds (2));
-
- uint32_t nd0 = CsmaIpv4Topology::AddIpv4CsmaNetDevice (n0, lan1,
- "08:00:2e:00:00:00");
-
- uint32_t nd1 = CsmaIpv4Topology::AddIpv4CsmaNetDevice (n1, lan1,
- "08:00:2e:00:00:01");
-
- uint32_t nd2 = CsmaIpv4Topology::AddIpv4CsmaNetDevice (n2, lan1,
- "08:00:2e:00:00:02");
-
- uint32_t nd3 = CsmaIpv4Topology::AddIpv4CsmaNetDevice (n3, lan1,
- "08:00:2e:00:00:03");
-
- CsmaIpv4Topology::AddIpv4Address (n0, nd0, "10.1.1.1", "255.255.255.0");
- CsmaIpv4Topology::AddIpv4Address (n1, nd1, "10.1.1.2", "255.255.255.0");
- CsmaIpv4Topology::AddIpv4Address (n2, nd2, "10.1.1.3", "255.255.255.0");
- CsmaIpv4Topology::AddIpv4Address (n3, nd3, "10.1.1.4", "255.255.255.0");
-@end verbatim
-
-The code to generate the CSMA LAN on the right side is similar; only the names
-have been changed.
-
-@verbatim
-//
-// Create the lan on the right side of the dumbbell.
-//
- Ptr<Node> n4 = CreateObject<InternetNode> ();
- Ptr<Node> n5 = CreateObject<InternetNode> ();
- Ptr<Node> n6 = CreateObject<InternetNode> ();
- Ptr<Node> n7 = CreateObject<InternetNode> ();
-
- Ptr<CsmaChannel> lan2 =
- CsmaTopology::CreateCsmaChannel (DataRate (10000000), MilliSeconds (2));
-
- uint32_t nd4 = CsmaIpv4Topology::AddIpv4CsmaNetDevice (n4, lan2,
- "08:00:2e:00:00:04");
-
- uint32_t nd5 = CsmaIpv4Topology::AddIpv4CsmaNetDevice (n5, lan2,
- "08:00:2e:00:00:05");
-
- uint32_t nd6 = CsmaIpv4Topology::AddIpv4CsmaNetDevice (n6, lan2,
- "08:00:2e:00:00:06");
-
- uint32_t nd7 = CsmaIpv4Topology::AddIpv4CsmaNetDevice (n7, lan2,
- "08:00:2e:00:00:07");
-
- CsmaIpv4Topology::AddIpv4Address (n4, nd4, "10.1.2.1", "255.255.255.0");
- CsmaIpv4Topology::AddIpv4Address (n5, nd5, "10.1.2.2", "255.255.255.0");
- CsmaIpv4Topology::AddIpv4Address (n6, nd6, "10.1.2.3", "255.255.255.0");
- CsmaIpv4Topology::AddIpv4Address (n7, nd7, "10.1.2.4", "255.255.255.0");
-@end verbatim
-
-Next, we create a point to point link to connect the two LANs. We connect
-the point-to-point channel between nodes three (on the left LAN) and four
-(on the right LAN). You should recognize this as substantially similar to
-the link setup from the @code{point-to-point} example.
-
-@verbatim
-//
-// Create the point-to-point link to connect the two lans.
-//
- Ptr<PointToPointChannel> link = PointToPointTopology::AddPointToPointLink (
- n3, n4, DataRate (38400), MilliSeconds (20));
-
- PointToPointTopology::AddIpv4Addresses (link, n3, "10.1.3.1",
- n4, "10.1.3.2");
-@end verbatim
-
-Then we configure data flows. We create four echo clients that send UDP
-packets from the left side LAN to servers created on the right side LAN.
-Notice that we send 100 packets with an inter-packet gap of ten milliseconds
-instead of the single packet we have previously used. This data rate is
-sufficient to saturate the point-to-point link and will cause packets to be
-dropped when the queue on the link net devices overflows (the default maximum
-queue depth is 100 packets). Note that we stagger the start of the echo
-clients to slowly bring up the data rates.
-
-@verbatim
-//
-// Create data flows across the link:
-// n0 ==> n4 ==> n0
-// n1 ==> n5 ==> n1
-// n2 ==> n6 ==> n2
-// n3 ==> n7 ==> n3
-//
- uint16_t port = 7;
-
- Ptr<UdpEchoClient> client0 = CreateObject<UdpEchoClient> (n0, "10.1.2.1",
- port, 100, Seconds(.01), 1024);
- Ptr<UdpEchoClient> client1 = CreateObject<UdpEchoClient> (n1, "10.1.2.2",
- port, 100, Seconds(.01), 1024);
- Ptr<UdpEchoClient> client2 = CreateObject<UdpEchoClient> (n2, "10.1.2.3",
- port, 100, Seconds(.01), 1024);
- Ptr<UdpEchoClient> client3 = CreateObject<UdpEchoClient> (n3, "10.1.2.4",
- port, 100, Seconds(.01), 1024);
-
- Ptr<UdpEchoServer> server4 = CreateObject<UdpEchoServer> (n4, port);
- Ptr<UdpEchoServer> server5 = CreateObject<UdpEchoServer> (n5, port);
- Ptr<UdpEchoServer> server6 = CreateObject<UdpEchoServer> (n6, port);
- Ptr<UdpEchoServer> server7 = CreateObject<UdpEchoServer> (n7, port);
-
- server4->Start(Seconds(1.));
- server5->Start(Seconds(1.));
- server6->Start(Seconds(1.));
- server7->Start(Seconds(1.));
-
- client0->Start(Seconds(2.));
- client1->Start(Seconds(2.1));
- client2->Start(Seconds(2.2));
- client3->Start(Seconds(2.3));
-
- server4->Stop (Seconds(10.));
- server5->Stop (Seconds(10.));
- server6->Stop (Seconds(10.));
- server7->Stop (Seconds(10.));
-
- client0->Stop (Seconds(10.));
- client1->Stop (Seconds(10.));
- client2->Stop (Seconds(10.));
- client3->Stop (Seconds(10.));
-@end verbatim
-
-The remainder of the file should be quite familiar to you. Go ahead and
-run @code{tutorial-linear-dumbbell}. Now take a look at the trace
-(@code{tutorial.tr}) file. You will now see trace lines that begin with
-@code{d}. Alternatively you can search for the string ``queue-drop'' which
-is the expansion of the drop code ('d').
-
-Interpretation of a dropped packet is straightforward. We have expanded
-the first @code{queue-drop} trace for you below. See the section on ASCII
-tracing for details.
-
-@verbatim
- 00 d
- 01 2.40938
- 02 nodeid=3
- 03 device=1
- 04 queue-drop
- 05 pkt-uid=124
- 06 LLCSNAP(type 0x800)
- 07 IPV4(
- 08 tos 0x0
- 09 ttl 63
- 10 id 20
- 11 offset 0
- 12 flags [none]
- 13 length: 1052) 10.1.1.3 > 10.1.2.3
- 14 UDP(length: 1032)
- 15 49153 > 7
- 16 DATA (length 1024)
-@end verbatim
-
-We leave it as an exercise to examine the trace files in more detail.
-
-@c ========================================================================
-@c Nonlinear Thinking
-@c ========================================================================
-
-@node Nonlinear-Thinking
-@chapter Nonlinear Thinking
-
-One thing that all of our examples so far have in common is that they are
-composed of a linear collection of calls into the @command{ns-3} system. The
-programmers among the readers may have wondered why there is not as much
-as a for-loop in all of the examples. The answer is that we wanted to
-introduce you to @command{ns-3} scripting with a minimum of conceptual
-overhead. We're going to remedy that situation shortly.
-
-We have written a number of @command{ns-3} scripts in C++. Although we have
-been perfectly linear in our script implementations, just like any other C++
-program, an @command{ns-3} script can use any features of the language you
-desire. If you will look back at the @code{tutorial-linear-dumbbell.cc}
-example, you may notice that the code to create the left and right sides of
-the dumbbell is operationally identical --- only the names change. An obvious
-improvement of this program would be to use subroutines to create the sides.
-Since we are working with C++, we should probably do this in an
-object-oriented way. Since object-oriented design is somewhat of a black art
-to some people, we'll take some time here and outline a simple methodology
-you can follow.
-
-@section Object Design 101 --- Class IPv4BusNetwork
-If you are a master of object oriented design, feel free to skip or skim this
-section, in which we derive a simplistic but fully operational bus network
-class.
-
-So you want to create a BusNetwork class. Often the biggest hurdle in a
-design is figuring out how to get started. One of the simplest and most
-straightforward ways to do an object decomposition of a problem is to simply
-write down a description of the problem and take a look at the words
-you used. Let's take some time and do that, first at a very high level.
-
-@example
-A bus network is an implementation of a particular network topology that
-contains some number of nodes. Each of these nodes is attached to a single
-multi-drop channel. The network itself has some attributes independent of
-the topology such as a network mask, network number (prefix) and base IP
-address.
-@end example
-
-The first thing to do is to focus on the nouns and adjectives. These will
-give you a starting point for required classes and member variables.
-
-Immediately we can notice that at the highest level we are talking about the
-noun @emph{network}. This probably won't surprise you. We also have an
-adjective that modifies the noun --- @emph{bus}. This should lead us to our
-first class definition. Usually class names are constructed in the same way
-as an English language sentence would be spoken. For example, one would speak
-of a @emph{bus network} in conversation, so we would normally create a
-@code{class BusNetwork} to represent it.
-
-One thing to note is that we have used two words in our description quite
-naturally: @emph{is} and @emph{has}. When you see these words should should
-immediately think of the object-oriented concepts of @emph{ISA} (inheritance)
-and @emph{HASA} (containment) respectively. We wrote that a bus network
-@emph{is} an implementation of a particular network topology. Perhaps you
-will agree that there is a natural base class called @code{Network} that
-@emph{has} the attributes discussed above. The fact that a @code{BusNetwork}
-@emph{ISA} kind of @code{Network} suggests inheritance. Let's capture that
-thought right away remembering that we're focused on IP version four here:
-
-@verbatim
- class Ipv4Network
- {
- public:
- Ipv4Address m_network;
- Ipv4Mask m_mask;
- Ipv4Address m_baseAddress;
- };
-
- class Ipv4BusNetwork : public Ipv4Network
- {
- };
-@end verbatim
-
-Let's take a look at the @emph{HASA} relationships of the bus network. Clearly
-it will @emph{have} a reference to the underlying channel that implements the
-actual communications medium. We use smart pointers for those references, so
-one member variable is obvious:
-
-@verbatim
- Ptr<CsmaChannel> m_channel;
-@end verbatim
-
-A bus network will also need to contain references to all of the nodes we
-eventually want to create. If you are working in C++ and see the words contain
-or container, you should immediately think of the Standard Template Library
-or STL. A quick search of the available containers there will probably lead
-you to consider the vector class. A vector is a container that looks like an
-array. This is just what we need here. Again, we want to use smart pointers
-to reference our nodes, so the declaration of the vector would look like,
-
-@verbatim
- std::vector<Ptr<Node> > m_nodes;
-@end verbatim
-
-It will save you headaches in the future if you notice that the space between
-the two right brackets is required to differentiate this situation from a
-right-shift operator. So we have a pretty good start already after just a
-little work. Now we need to turn our attention to actions. Let's write
-another little description of the things you consider doing to a Bus network.
-
-@example
-We need to be able to create a bus network. We need to be able to delete a
-bus network. We need to be able to get a handle to a node in order to add
-applications. We need to be able to set the network, mask and base address
-somehow, specify how many nodes to create and provide the underlying channel
-its required bandwidth and delay parameters.
-@end example
-
-We now look at the @emph{verbs} in that sentence. These will give a good
-starting point for the methods of the classes. For example, the verbs
-@emph{create} and @emph{delete} should suggest @emph{constructor} and
-@emph{destructor}. The verb @emph{get} leads us to providing a method called
-@code{GetNode}. We have to provide a number of parameters so we can either
-provide @emph{setters} or we can simply pass them in as parameters to our
-constructors. Since this is a simple example, we won't bother to implement
-getters and setters (methods to get and set member variables to enhance data
-hiding). Let's use this guidance to finish up our class declarations:
-
-@verbatim
- class Ipv4Network
- {
- public:
- Ipv4Network (Ipv4Address network, Ipv4Mask mask, Ipv4Address address);
- virtual ~Ipv4Network ();
-
- Ipv4Address m_network;
- Ipv4Mask m_mask;
- Ipv4Address m_baseAddress;
- };
-
- class Ipv4BusNetwork : public Ipv4Network
- {
- public:
- Ipv4BusNetwork (
- Ipv4Address network,
- Ipv4Mask mask,
- Ipv4Address startAddress,
- DataRate bps,
- Time delay,
- uint32_t n);
-
- virtual ~Ipv4BusNetwork ();
-
- Ptr<Node> GetNode (uint32_t n);
-
- private:
- std::vector<Ptr<Node> > m_nodes;
- Ptr<CsmaChannel> m_channel;
- };
-@end verbatim
-
-That's it. We have actually already walked through almost all of the code
-required to construct a bus network in our @code{tutorial-csma-echo.cc}
-example, so let's just jump forward and take a look at an implementation
-of this thing. We provide an implementation for you in the files
-@code{ipv4-bus-network.h} and @code{ipv4-bus-network.cc} located in the
-@code{tutorial} directory. We also provide an example that uses the new
-class in the file @code{tutorial-bus-network.cc}.
-
-The interesting method from our current perspective is the Ipv4BusNetwork
-constructor, shown below:
-
-@verbatim
- Ipv4BusNetwork::Ipv4BusNetwork (
- Ipv4Address network,
- Ipv4Mask mask,
- Ipv4Address baseAddress,
- DataRate bps,
- Time delay,
- uint32_t n)
- :
- Ipv4Network (network, mask, baseAddress)
- {
- Ipv4AddressGenerator::SeedNetwork (mask, network);
- Ipv4AddressGenerator::SeedAddress (mask, baseAddress);
-
- m_channel = CsmaTopology::CreateCsmaChannel (bps, delay);
-
- for (uint32_t i = 0; i < n; ++i)
- {
- Ptr<Node> node = CreateObject<InternetNode> ();
- uint32_t nd = CsmaIpv4Topology::AddIpv4CsmaNetDevice (node, m_channel,
- Mac48Address::Allocate ());
- Ipv4Address address = Ipv4AddressGenerator::AllocateAddress (mask,
- network);
- CsmaIpv4Topology::AddIpv4Address (node, nd, address, mask);
- m_nodes.push_back (node);
- }
- }
-@end verbatim
-
-Notice that we do the simple and straightforward thing and pass all of our
-parameters to the constructor. For those unfamiliar with C++, the line after
-the colon and before the opening brace (shown below),
-
-@verbatim
- :
- Ipv4Network (network, mask, baseAddress)
- {
-@end verbatim
-
-Passes the appropriate parameters to the constructor of the base class
-@code{Ipv4Network}. There are two new calls that we haven't seen immediately
-after this initialization. They are:
-
-@verbatim
- Ipv4AddressGenerator::SeedNetwork (mask, network);
- Ipv4AddressGenerator::SeedAddress (mask, baseAddress);
-@end verbatim
-
-We provide an IP address generator class to allow us to programmatically
-allocate IP addresses. The first call to @code{SeedNetwork} gives the
-address generator a starting network number to use when generating addresses.
-The second call to @code{SeedAddress} gives the address generator a starting
-IP address to use. There is a starting network and starting address for each
-of the 32 possible network masks. Later in the for loop, you will see a
-call to @code{AllocateAddress} in which the IP address for each node created
-in the loop is actually generated.
-
-The only unfamiliar call in the reset of the constructor will be:
-
-@verbatim
- m_nodes.push_back (node);
-@end verbatim
-
-This is the STL code to add the newly created node to the vector of nodes
-attached to the bus.
-
-For your convenience, we reproduce the entire bus network implementation below:
-
-@verbatim
- /* -*- Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*- */
- /*
- * Copyright (c) 2007 University of Washington
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2 as
- * published by the Free Software Foundation;
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
- #include "ns3/mac48-address.h"
- #include "ns3/csma-net-device.h"
- #include "ns3/csma-topology.h"
- #include "ns3/csma-ipv4-topology.h"
-
- #include "ipv4-bus-network.h"
- #include "ipv4-address-generator.h"
-
- namespace ns3 {
-
- Ipv4Network::Ipv4Network (
- Ipv4Address network,
- Ipv4Mask mask,
- Ipv4Address address)
- :
- m_network (network), m_mask (mask), m_baseAddress (address)
- {
- }
-
- Ipv4Network::~Ipv4Network ()
- {
- }
-
- Ipv4BusNetwork::Ipv4BusNetwork (
- Ipv4Address network,
- Ipv4Mask mask,
- Ipv4Address baseAddress,
- DataRate bps,
- Time delay,
- uint32_t n)
- :
- Ipv4Network (network, mask, baseAddress)
- {
- Ipv4AddressGenerator::SeedNetwork (mask, network);
- Ipv4AddressGenerator::SeedAddress (mask, baseAddress);
-
- m_channel = CsmaTopology::CreateCsmaChannel (bps, delay);
-
- for (uint32_t i = 0; i < n; ++i)
- {
- Ptr<Node> node = CreateObject<InternetNode> ();
- uint32_t nd = CsmaIpv4Topology::AddIpv4CsmaNetDevice (node, m_channel,
- Mac48Address::Allocate ());
- Ipv4Address address = Ipv4AddressGenerator::AllocateAddress (mask,
- network);
- CsmaIpv4Topology::AddIpv4Address (node, nd, address, mask);
- m_nodes.push_back (node);
- }
- }
-
- Ipv4BusNetwork::~Ipv4BusNetwork ()
- {
- }
-
- Ptr<Node>
- Ipv4BusNetwork::GetNode (uint32_t n)
- {
- return m_nodes[n];
- }
-
- }; // namespace ns3
-@end verbatim
-
-@section Using Ipv4BusNetwork
-If all you ever want to do with a bus network can be captured in a topology
-with four nodes on the bus, the preceding section may seem like a colossal
-waste of time. This is probably not the case, though. Now that we have a
-relatively abstract bus class, we can create bus networks with 4, 40 or 4000
-nodes with no additional effort.
-
-A use of the bus network class is shown in the file
-@code{bus-network.cc} located in the @code{tutorial} directory. The
-interesting code is,
-
-@verbatim
- Ipv4BusNetwork bus ("10.1.0.0", "255.255.0.0", "0.0.0.3",
- DataRate(10000000), MilliSeconds(20), 10);
-@end verbatim
-
-Here we create a bus network with the network number ``10.1.0.0'' and the
-network mask ``255.255.0.0'' that completes the IP network definition. You
-can consider these together as ``10.1.0.0/16'' if you prefer. The next
-parameter tells the bus to start numbering IP addresses of contained nodes at
-``10.1.0.3'' (remember the network number will be combined). We provided a
-data rate of 10 megabits per second and a latency of 20 milliseconds.
-Finally, we ask the @code{Ipv4BusNetwork} object to create ten nodes in the
-network.
-
-If you are feeling brave, go ahead and change the number of nodes to be 100,
-1000, 10,000 or more to generate larger and larger networks. Before you go
-too far, remember that a trace file will be generated when you run your
-resulting program and ee asked the trace facility to trace all net device
-receive events. This will include the reception of the broadcast ARP request
-by all of the nodes in the simulation, so this can add up quickly.
-
-@c ========================================================================
-@c Summary
-@c ========================================================================
-
-@node Summary
-@chapter Summary
-
-This concludes the first part of the tutorial. We have focused on
-using the @command{ns-3} system to construct various network topologies and to
-simulate sending data across the networks; and we've shown you how to use the
-trace facility to get access to simulation results.
-
-We now encourage you to play with the system a little. Experiment with what
-we have provided. Build a hierarchical network simulation. Perhaps exercise
-your object design skills and create a new @code{Ipv4DumbbellNetwork} class
-to create dumbbell networks using the Ipv4BusNetwork class we just created.
-Hint: An Ipv4DumbbellNetwork @emph{has} two @code{Ipv4BusNetwork} objects;
-a left side and a right side.
-
-In the next part of the tutorial we are going to drop down a level and begin
-examining the lower levels of the system in more detail. We are going to
-explain how to change the behavior of the system and eventually how to write
-new models and applications. This is a good time to make sure that you
-thoroughly understand what we've gone over so far.
-
-@c ========================================================================
-@c Object Model
-@c ========================================================================
-
-@node Object-Model
-@chapter Object Model
-
-@cindex Object Model
-There are two distinctly different meanings associated with the term Object
-Model. The first speaks to the implementation of an object system --- a system
-view; and the second speaks to the application programming interface (classes
-or objects) one uses to access some service or system --- an application view.
-
-As an example of the system view sense of the term, the C++ language has an
-associated object model that describes how objects are laid out in memory,
-how virtual functions work, how inheritance is implemented, constructor and
-destructor execution ordering, template instantiation, etc.
-
-@cindex API
-@cindex DOM
-@cindex Document Object Model
-In the case of the application view, the Document Object Model is a good
-example. In the words of W3C, the Document Object Model (DOM) is an
-application programming interface (API) for HTML and XML documents. It defines
-the logical structure of documents and the way a document is accessed and
-manipulated.
-
-@cindex API
-@cindex COM
-@cindex Component Object Model
-The Component Object Model (COM) from Microsoft actually spans both meanings
-of the term and extends further into policy statements. From a system
-perspective, COM specifies an interface definition language, the layout of
-objects virtual function tables, the formats of Globally Unique Identifiers
-and also specifies lifetime management mechanisms for objects via reference
-counting. From the point of view of the API, COM specifies a number of
-Interfaces as well as functions such as CoCreateInstance and various
-threading models. The COM specification extends to policy by disallowing
-implementation inheritance.
-
-@cindex Feynman
-The @command{ns-3} object model takes the C++ language (system level) object
-model as its basis, and extends that model by providing an API for software
-componentry. You may find terms like Component, Interface and QueryInterface
-in the following discussion, or used informally in other discussions about
-@command{ns-3}. It is important to understand from the outset that this is
-the @command{ns-3} object model, and not any other object model.
-Richard Feynman (an American physicist) once described the behavior of matter
-and light on a very small scale in the following way,
-
-@quotation
-``They do not behave like waves, they do not behave like particles, they do
-not behave like clouds, or billiard balls, or weights on springs, or like
-anything that you have ever seen.''
-@end quotation
-
-Just as students of quantum mechanics must rid themselves of preconceptions
-regarding the behavior of matter at small scales, you should rid yourself of
-any preconceptions you may have about components, interfaces and APIs for
-software componentry before continuing. To paraphrase Feynman, @command{ns-3}
-components do not behave like COM Components, or Java Beans, or CORBA
-objects, or clouds or weights on springs, or like anything that you have
-ever seen --- they are @command{ns-3} components.
-
-@section The C++ Object Model is the Root of all Things
-@command{Ns-3} is primarily a C++ system. The system is written in C++ and
-one can use standard C++ mechanisms for creating and using ns-3 objects. We
-do not change this at all, nor do we make any pronouncements about the
-superiority of one mechanism or another. What we will do is provide
-convenience functions that we think will make creating and managing simulation
-objects easier.
-
-@cindex CreateObject
-Previously, you have seen objects created using the template function
-@code{CreateObject} as in the following example:
-
-@verbatim
- Ptr<Node> n0 = CreateObject<InternetNode> ();
-@end verbatim
-
-This line of code, while it may be unfamiliar to some, is pure C++. If you
-were to look in the header file ptr.h, you would find the following definition
-of the @code{CreateObject} template.
-
-@verbatim
- template <typename T>
- Ptr<T> CreateObject (void)
- {
- Ptr<T> p = Ptr<T> (new T (), false);
- p->SetTypeId (T::GetTypeId ());
- return p;
- }
-@end verbatim
-
-@cindex template
-As you can see, this template creates objects of type @code{T} using the
-operator @code{new}. Its a little harder to find the corresponding delete ---
-it's in the file @code{object.cc} inside the method @code{Object::MaybeDelete},
-but when that @code{Ptr} which you see above goes out of scope it will call
-@code{Unref} and ultimately the C++ @code{delete} operator will be called.
-
-@cindex new
-@cindex delete
-The ns-3 system uses the C++ @code{new} and @code{delete} operators, so there
-is really no reason that you as a user of the ns-3 system are forbidden from
-using these or any other C++ mechanism. If you so desire, you can take on
-the responsibility for managing object lifetime (i.e., do not use the
-@code{Ptr} smart pointer), work directly with the @code{new} and @code{delete}
-operators and call methods like any C++ object as in the following example:
-
-@verbatim
- MyClass *obj = new MyClass ();
- obj->Method();
- delete obj;
-@end verbatim
-
-@cindex model
-You, as a competent model author, are encouraged to use whatever methods you
-think are appropriate in your private code. Remember, however, that the
-public ns-3 APIs do use smart pointers to pass objects around in an effort to
-reduce the burden of object lifetime management. If you do intend to export
-an API publicly, you should use the same object lifetime management approaches
-as those found in the ns-3 public API if only for consistency.
-
-These APIs are there for convenience and consistency, but do not change the
-fact that in ns-3 all of the objects are really just C++ objects, ultimately
-created using the C++ new operator with C++ constructor semantics and are
-ultimately deleted using the C++ delete operator, following C++ destructor
-semantics. Although it may sometimes appear so, there is really no system-
-level magic going on in ns-3. Ns-3 components and interfaces are C++ objects
-just like any other object and our object model is simply a collection of APIs
-built on the normal C++ object model.
-
-@cindex Interface
-@cindex Abstract Data Type
-@cindex ADT
-@cindex Abstract Base Class
-@cindex ABC
-@section Interface
-There are many different ideas floating around of what exactly the term
-@emph{interface} means. Originally an interface just meant a communication
-boundary between two entities. As the concepts of object oriented programming
-(OOP) were surfacing in the 1980s, the term interface was applied to the
-collection of access methods for the modular entities that were being defined.
-
-@cindex OOP
-@cindex Object Oriented Programming
-Two distinct approaches developed regarding specifying access mechanisms for
-objects. The OOP purists were very concerned about object reuse and were led
-to Abstract Data Types (ADT). These were eventually implemented in the case
-of C++, as pure virtual methods in Abstract Base Classes (ABC). Another group
-of folks was more interested in simply specifying object access methods in one
-place and using inheritance as the primary reuse mechanism.
-
-Bjarne Stroustroup, the creator of C++, embraced both approaches. He makes
-the following interesting observation:
-
-@quotation
-``Many classes [@dots{}] are useful both as themselves and also as bases for
-derived classes. [@dots{}] Some classes, such as class @strong{Shape},
-represent abstract concepts for which objects cannot exist.''
-@end quotation
-
-@cindex PIMPL
-@command{Ns-3} does not pick and enforce a particular approach. In
-@command{ns-3} an interface is determined completely by a class declaration
-just as any C++ object interface is declared. If you think of an object as
-an abstract concept that should be implemented by derived classes, by all
-means, use the Abstract Base Class approach to interface declaration. If you
-think that an object should be completely concrete and you foresee no need
-to ever modify its behavior, feel free to avoid declaring any methods virtual.
-If you think that an object could be useful as a base class, feel free to
-declare its methods virtual. If you like to use the PIMPL idiom, again, feel
-free. If you want to use any combination of these techniques, feel free.
-We make no restrictions.
-
-@cindex API
-When we speak of an ns-3 interface, we do not worry about interface definition
-languages, or pure virtual classes, or registries we just think about C++
-object declarations and their associated methods. We tend to think of
-interfaces to objects as simply a private or public API. When we instantiate
-an @command{ns-3} interface, it is the C++ object model that dictates how that
-object is brought into existence. When a method is called on an @command{ns-3}
-Interface, it is the C++ object model that dictates how that method is
-dispatched.
-
-We do, however, provide a base class that endows vanilla C++ objects with
-capabilities that can be seen as conceptually similar to those provided by
-Microsoft Component Model @emph{Interfaces}.
-
-@section The Ns-3 Object and GetObject
-@cindex Component Object Model
-One thing that Microsoft arguably got right in the Component Object Model was
-the idea of Interface aggregation and discovery via QueryInterface. We have
-embraced these ideas in @command{ns-3}. This was done primarily to address a
-common problem in large software systems. A good example of this problem
-happens in the @command{ns-3} Node class.
-
-@cindex OOP
-@cindex weak base class
-@cindex base class bloat
-@cindex Swiss Army Knife class
-@cindex Node
-If one were to take the standard OOP view of specializing a @code{Node} into
-an internet host, for example, one would typically inherit from the @code{Node}
-base class and include functionality to implement such things as internet
-routing and a TCP/IP protocol stack. Other types of @code{Node}s might
-inherit from the node class and specialize in different ways, or further
-specialize the internet host class, treating it as a base class. This can
-result in a complicated inheritance tree in which some specializations are
-simply not available to other branches of the tree which can make reuse
-difficult or impossible. This is known as the @emph{weak base class} problem
-and creates pressure to drive functionality up the inheritance tree into the
-base classes. This, in turn, results in @emph{base class bloat} and the
-resulting @emph{swiss army knife} base classes which end up trying to do
-everything in one place.
-
-Even if one successfully avoided these swiss army knife base classes, one
-would also want to be able to treat new specializations of @code{Node}
-generically in the system. This means one would pass references to the base
-class (@code{Node}) across public APIs. This introduces @emph{upcasts} prior
-to passing across public APIs and corresponding @emph{downcasts} on the other
-side in order to gain access to required specialized functions. As the
-inheritance tree becomes more complicated, this approach can cause another
-related problem known as the @emph{fragile base class} problem. This happens
-when changes to the base class cause unexpected problems in the various and
-sundry subclasses.
-
-These effects seem always to result in a positive feedback loop driving
-everything into the base class and destroying much of the encapsulation which
-is a hallmark of the object oriented approach.
-
-@subsection Interface Composition
-@cindex Node
-There is a completely different way to address the Node specialization
-problem. Instead of approaching the situation using inheritance, one can
-look at the problem as one of composition. We can look at the @code{Node}
-class as a container of sorts that holds other objects. In this case, the
-objects would be instances of the classes implementing the internetwork
-routing code, or the TCP/IP protocol stack described above. This approach
-preserves the encapsulation and solves the weak base class, base class bloat
-and fragile base class problems; but the question of method dispatch
-immediately comes to mind.
-
-@cindex delegation
-In many systems, @emph{delegation} is used. The base class, @code{Node},
-in this approach would provide methods that simply forward to the objects
-implementing the desired functionality. This situation clearly does not
-address the base class bloat problem since dispatch methods must be added
-to the base class. The situation is mitigated somewhat by pushing the
-implementation of the dispatch methods to contained objects, but the
-fundamental problems are still present. What is really needed is a way
-to compose objects but at the same time keep the interfaces to those
-objects separated.
-
-@cindex aggregation
-Composition, usually called @emph{aggregation}, along with runtime Interface
-discovery is the solution that Microsoft originally championed and that
-@command{ns-3} has adopted --- albeit with many simplifications and a few name
-changes.
-
-@subsection Objects and Interfaces
-@cindex COM
-@cindex QueryInterface
-Now that we have mentioned Microsoft COM and are almost obligated to mention
-the terms Interface and QueryInterface. For those familiar with COM, loosely
-speaking, QueryInterface is to COM as GetObject is to @command{ns-3}.
-The analogy, while good conceptually, is superficial from an implementation
-point of view.
-
-@cindex Node
-Addressing our current example of a @code{Node}, generically speaking, each
-node needs to aggregate an object that will implement internetwork routing
-and TCP/IP. The system will need to provide a mechanism for locating the
-aggregated objects and allow a client to discover them.
-
-@cindex aggregation
-@cindex Object
-These aggregated objects have interfaces in the C++ sense of collections of
-method signatures. In @command{ns-3}, when objects are capable of
-participating in this aggregation process, they are called @command{ns-3}
-@code{Objects}. @code{Objects} receive the functionality required for this
- participation by inheriting from the @command{ns-3} base class @code{Object}.
-
-Note well that when we write the word @code{Object} (note the uppercase 'O' in
-the spelling and the change of font) we are referring to a kind of C++ object
-that has inherited the capability of participating in an aggregation. The
-@command{ns-3}-specific word @code{Object} can have a significantly different
-meaning than that of a vanilla C++ object outside the aforementioned
-inheritance tree, and the difference is only readily apparent via context.
-In this tutorial we will always write the @command{ns-3}-specific kind of
-@code{Object} in a fixed font; and will write the vanilla C++ term object in
-normal font. In conversation, you will need to be careful to understand which
-term is meant: object or @code{Object}.
-
-Once an object has inherited from class @code{Object} it has the ability to
-@emph{host} an aggregation. This means that it has the ability to add other
-@code{Objects} to its aggregation via the method @code{AggregateObject}. It
-also means that it can provide a service to @emph{discover} other objects in
-its aggregation via the method @code{GetObject}.
-
-@cindex base class
-Technically, the class named @code{Object} is simply a base class that you
-will inherit from if you want your @code{Objects} to support aggregation and
-discovery. Many systems have a base class that implements common
-functionality and these base classes are typically called something like
-Object. The @command{ns-3} version of this base class relates primarily to
-@code{Object} aggregation and discovery, although it does also provide methods
-to help with intrusive reference counting and tracing as well.
-
-When a C++ object inherits from the ns-3 Object base class, it is conceptually
-promoted to an ns-3 @code{Object} irrespective of how the object was declared
-(e.g., as an abstract base class, concrete class, with virtual methods, etc.).
-In ns-3, you should associate inheritance from the class named @code{Object}
-with promotion of an object to the status of some locatable @code{Object}
-rather than with the form of the class declaration.
-
-@cindex COM
-@cindex CORBA
-@cindex ORBit
-For those of you unfamiliar with Microsoft COM, CORBA or ORBit, this might
-sound obvious. For those of with such a background, the point we are making
-is that there is no such thing in @command{ns-3} as a separate Interface
-declaration, no such thing as an Interface Definition Language, no such thing
-as a UUID or GUID, etc. In @command{ns-3} we just work with C++ objects that
-may be given some very useful abilities by inheriting from the @command{ns-3}
-base class @code{Object}. @command{Ns-3} @code{Objects} are not required to
-inherit from classes composed of pure virtual methods in order to define an
-Interface. It's all really just ``plain old C++.''
-
-To summarize, when you instantiate an object that inherits from the
-@code{Object} class, you will have a C++ object that has four important
-properties:
-
-@cindex AggregateObject
-@cindex GetObject
-@itemize @bullet
-@item The @code{Object} has a C++ interface defined by the collection of method signatures in its inheritance tree;
-@item The @code{Object} has some way to identify its underlying class uniquely;
-@item The @code{Object} is a kind of container that has the ability to aggregate other @code{Objects} using the method @code{AggregateObject};
-@item The @code{Object} exports a method called @code{GetObject} that allows for discovery of other aggregated @code{Objects}.
-@end itemize
-
-@cindex base class
-@cindex Object
-It is crucially important to understand what we have described here
-(especially for those coming from other systems that provide similar
-functionality). A given C++ class has an object access interface that is
-essentially the collection of method signatures specified in its inheritance
-tree. This is a C++ object model thing. Ns-3 provides a base class from
-which the class in question can inherit and be promoted to the status of
-@code{Object}. Once a class becomes an @code{Object} it has inherited the
-ability to aggregate and search for other @code{Objects} that are added to
-its aggregation.
-
-That last detail is important. In @command{ns-3} @code{Objects} are both
-containers and specifications for a object method access. We have previously
-mentioned that the @code{Node} class acts as a container. In fact, the
-@code{Node} class inherits from @code{Object} and is itself an @command{ns-3}
-@code{Object}. So, when the @code{Node} object is created it is really an
-aggregation of one @code{Object} and you can call @code{AggregateObject} or
-@code{GetObject} on the resulting @code{Node} object. Along with being an
-aggregation, the @code{Node} class also describes a public interface. This
-public interface (API) is declared just as any C++ object is declared, via its
-class methods as specified in the inheritance tree. For those steeped in
-COM or CORBA, this is where the concept of Interface works in @command{ns-3}.
-Remember that it is generally true that @code{Objects} are both aggregations
-and APIs.
-
-@subsection Aggregations
-@cindex aggregate
-The figure below shows how an @code{Object} could be illustrated in detail.
-The line with the circle at the top of the diagram represents the appearance
-of the @code{Object} API to the external world. This circle and line are
-together called a lollipop because of its superficial similarity to a kind of
-child's candy.
-
-@sp 1
-@center @image{oneobj,,,,png}
-
-@cindex API
-You could declare this API and associated @code{Object} quite simply using a
-non-virtual class as follows,
-
-@verbatim
- class A : public Object {
- public:
- static ns3::TypeId GetTypeId (void)
- {
- static ns3::TypeId tid = ns3::TypeId ("A")
- .SetParent (Object::GetTypeId ())
- .AddConstructor<A> ();
- return tid;
- }
-
- A ()
- {
- }
-
- void MethodA (void);
- };
-@end verbatim
-
-The methods that are then available via the API labeled @code{A} in the
-figure above are the methods inherited from the @code{Object} base class
-(@code{GetObject}, @code{Ref}, and @code{Unref}) and those from class
-@code{A} (@code{MethodA}).
-
-Note that you must declare a @code{TypeId} in your @code{Object} class, and
-it must be declared static to make it class-wide in scope. This @code{TypeId}
-is a unifying element in the @command{ns-3} object model and uniquely
-identifies @code{Objects} at run-time as being instantiated from a particular
-class. We'll have much more to say about @code{TypiId} shortly.
-
-You can think of the arc and arrow device coming off each side of the
-illustrated @code{Objects} as part of a connector. These connectors allow
-@code{GetObject} to search aggregations for an instance of a class type.
-The figure below shows an aggregation of three @code{Objects}: A, B and C.
-The class declarations for classes @code{B} and @code{C} are substantially
-similar to that of class @code{A}.
-
-@sp 1
-@center @image{threeobj,,,,png}
-
-You can visualize these @code{Objects} as being snapped together like Lego
-building blocks if you like. When @code{Objects} are aggregated, a
-@code{GetObject} search path is formed through the connectors. In order
-to create this aggregation you will first need to create the @code{Objects}.
-These are just normal, everyday C++ objects that we can create using the
-@code{CreateObject} template function and manage using smart pointers. The
-following code should be obvious to you by now:
-
-@verbatim
- Ptr<A> a = CreateObject<A> ();
- Ptr<B> b = CreateObject<B> ();
- Ptr<C> c = CreateObject<C> ();
-@end verbatim
-
-@cindex aggregation
-When you create an aggregation, you pick one of the @code{Objects} of the
-aggregation to think of as the container. In this case well pick @code{Object}
-A. In order to aggregate an @code{Object}, you simply call the method
-@code{AggregateObject} that your class has inherited from class @code{Object}.
-The following code will aggregate @code{Object B} and @code{Object C} onto
-the @code{Object} (and container/aggregation) @code{A}.
-
-@cindex AggregateObject
-@cindex GetObject
-@cindex Object
-@verbatim
- a->AggregateObject (b);
- a->AggregateObject (c);
-@end verbatim
-
-That's all there is to it. Now that you have those connectors snapped
-together, you can ask each of the @code{Objects} in the aggregation for any of
-the other @code{Objects} in the aggregation. Lets look at a simple example:
-
-@verbatim
- Ptr<B> newB = a->GetObject<B> ();
-@end verbatim
-
-Now, the explanation of what this snippet does is not as simple as writing it.
-The left hand side of this assignment declares a smart pointer to the class
-@code{B} to help with memory management of the returned @code{Object} pointer.
-You should be very familiar with smart pointers at this stage of the tutorial.
-
-The right hand side illustrates how @code{GetObject} is actually used.
-The method @code{GetObject} is templated. The associated template parameter
-(between the brackets) specifies the @emph{class} that is being requested.
-This is important. Since it is the class type that specifies the search
-criterion, there can be only one instance of a particular class present in an
-aggregation. Looking back a little, although the parameter to
-@code{AggregateObject} appears to be a vanilla C++ object (@code{b} or @code{c}
-above), it actually represents (is an instance of) a class that has an
-associated @code{TypeId} and inherits from @code{Object}. When you call
-@code{GetObject} you specify the search criterion (using the template
-parameter) as a class name. This referenced class must also have an
-associated @code{TypeId} and must also have inherited from @code{Object}.
-
-This may be summarized by saying that @code{AggregateObject} takes an
-@emph{instance} of an object of a particular class that inherits from
-@code{Object}. GetObject looks for a @emph{class} of a particular type
-(that again inherits from @code{Object}) and possibly returns an aggregated
-object instance of that type.
-
-Now that you have those conceptual connectors snapped together, you can ask
-each of the @code{Objects} in the aggregation for any of the @code{Objects}
-in the aggregation. For example we could walk the @code{Objects} asking each
-for the next in the aggregation. First we would ask the @code{Object} pointed
-to by the smart pointer @code{a} to look for the @code{Object} @code{class B}:
-
-@verbatim
- Ptr<B> newB = a->GetObject<B> ();
-@end verbatim
-
-Next, we can ask the @code{Object} pointed to by the smart pointer @code{newB}
-to look for the @code{Object} representing @code{class C}:
-
-@verbatim
- Ptr<C> newC = newB->GetObject<C> ();
-@end verbatim
-
-@cindex Object
-Then, we can ask the @code{Object} pointed to by the smart pointer @code{newC}
-to look for the @code{Object} representing @code{class A} and complete our
-circuit of the aggregation:
-
-@verbatim
- Ptr<A> newA = newC->GetObject<A> ();
-@end verbatim
-
-@cindex GetObject
-@code{GetObject} has some important properties that we need to go over.
-Technically, @code{GetObject} is a @emph{symmetric}, @emph{reflexive} and
-@emph{transitive} operation with respect to the set of aggregated
-@code{Objects}.
-
-@subsubsection Symmetry
-@cindex symmetry
-The symmetric nature of @code{GetObject} guarantees that if one performs a
-@code{GetObject} on a given @code{Object} for the class of that same
-@code{Object}, that @code{GetObject} must succeed. In other words, the
-fact that you accessed the aggregation via an instance of an @code{Object A}
-in the aggregation implies the reachability of that @code{Object} in the
-aggregation. This is usually written (by Microsoft) as,
-
-@center must succeed (A >> A)
-
-We can illustrate this property with the code snippet,
-
-@verbatim
- Ptr<A> symmetricA = a->GetObject<A> ();
- NS_ASSERT (symmetricA);
-@end verbatim
-
-Here we take as given an interface (smart) pointer --- named @code{a} --- on
-which we perform a @code{GetObject} looking for the class that represents that
-same @code{Object}. This call must always succeed and a smart pointer to the
-aggregated instance of that class is returned.
-
-@subsubsection Reflexivity
-@cindex reflexivity
-Calls to @code{GetObject} must also be reflexive. This means that if you
-successfully @code{GetObject} for @code{Object B} from @code{Object A}, then
-you must always be able to @code{GetObject} for @code{A} from @code{B}. This
-is usually written as,
-
-@center must succeed (A >> B, then B >> A)
-
-This property can be illustrated with the code snippet,
-
-@verbatim
- Ptr<B> b = a->GetObject<B> ();
- Ptr<A> reflexiveA = b->GetObject<A> ();
- NS_ASSERT (reflexiveA);
-@end verbatim
-
-If the first @code{GetObject} on @code{Object A} looking for @code{Object B}
-succeeds, then a @code{GetObject} on @code{Object B} looking @code{Object A}
-must succeed.
-
-@subsubsection Transitivity
-@cindex transitivity
-@code{GetObject} must also be transitive. This means that if one can
-find @code{Object B} from @code{Object A}, and @code{Object C} from
-@code{Object B}, then one must also be able to find @code{Object C} from
-@code{Object A}. This is usually written as,
-
-@center must succeed (A >> B, and B >> C, then A >> C)
-
-This property can be illustrated with the code snippet,
-
-@verbatim
- Ptr<B> b = a->GetObject<B> ();
- Ptr<C> c = b->GetObject<C> ();
- Ptr<C> transitiveC = a->GetObject<C> ();
- NS_ASSERT (transitiveC);
-@end verbatim
-
-If you can get to @code{Object B} from @code{Object A}, and you can get to
-@code{Object C} from @code{Object B}, then a @code{GetObject} on
-@code{Object A} looking for @code{Object C} must also succeed.
-
-@subsection Creating the TypeId
-@cindex TypeId
-@cindex GetTypeId
-The final piece of this puzzle is the @code{TypeId}. Recall that the
-declaration our example object above included the following code
-
-@verbatim
- static ns3::TypeId GetTypeId (void)
- {
- static ns3::TypeId tid = ns3::TypeId ("A")
- .SetParent (Object::GetTypeId ())
- .AddConstructor<A> ();
- return tid;
- }
-@end verbatim
-
-This is the bit of code that ties this all together. For those unfamiliar
-with the idioms involved, this declaration can be rather dense. First, let's
-examine the function declaration itself. The following code,
-
-@verbatim
- static ns3::TypeId GetTypeId (void) ...
-@end verbatim
-
-declares a function that will be associated with all of the instances of the
-given class. This is a function, not a method, in that it can be accessed
-without a @emph{this} pointer; but it is associated with the class in a
-namespace sense. The use of this kind of declaration allows one to write,
-
-@verbatim
- return A::GetTypeId (void);
-@end verbatim
-
-if the @code{TypeId} is needed for our @code{class A}. More generically the
-class name can be substituted in a template, as is done deep in the
-@command{ns-3} object system.
-
-From this perspective, if you leave out the middle of the function definition,
-the boundaries should make sense to you.
-
-@verbatim
- static ns3::TypeId GetTypeId (void)
- {
- return tid;
- }
-@end verbatim
-
-@cindex function-local variable
-You are obviously looking at a global function associated with your class
-that simply returns a @code{TypeId}. Now, what about the rest. The code
-
-@verbatim
- static ns3::TypeId tid = ns3::TypeId ("A")
- .SetParent (Object::GetTypeId ())
- .AddConstructor<A> ();
-@end verbatim
-
-when found inside the function declaration is called a function-local variable
-with associated initialization. It'll be easier to pick this statement apart
-piece by piece as well. The first line,
-
-@verbatim
- static ns3::TypeId tid = ...
-@end verbatim
-
-is the declaration of the function-local variable tid. This is essentially
-an initialized global variable, the scope of which has been reduced to within
-the enclosing method. You can think of this as a kind of global variable
-that can only be accessed right there where it is created. If the variable
-is initialized, this amounts to the same behavior as if a global static
-initializer was declared in a namespace of the same name as your class.
-Global static initializers are guaranteed by the C++ language definition to
-be executed before your main procedure is entered. So are function-local
-variables.
-
-The variable that is being initialized is of type @code{ns3::TypeId}, is
-named @code{A::tid} since it is inside the class declaration for
-@code{class A}, and is initialized by a call to the constructor for the class
-@code{TypeId}. The constructor for @code{TypeId} takes a @code{std::string}
-that can be used to locate the type information for your class. We usually
-provide the class name as the string.
-
-Hopefully, this much of the declaration is now clear:
-
-@verbatim
- static ns3::TypeId GetTypeId (void)
- {
- static ns3::TypeId tid = ns3::TypeId ("A")
- ...
- return tid;
- }
-@end verbatim
-
-All that is left now are the lines including @code{SetParent} and
-@code{AddConstructor}.
-
-@verbatim
- static ns3::TypeId tid = ns3::TypeId ("A")
- .SetParent (Object::GetTypeId ())
- .AddConstructor<A> ();
-@end verbatim
-
-The last bit may seem quite odd at first glance, but don't let the way the
-code is broken up over several lines throw you. If you saw something like,
-
-@verbatim
- pointer->TypeId()->SetParent()->AddConstructor();
-@end verbatim
-
-you probably wouldn't hesitate at all. Clearly, you would think, a method
-called @code{TypeId} is called using the pointer called @code{pointer} as
-shown below.
-
-@verbatim
- pointer->TypeId()
-@end verbatim
-
-The method @code{TypeId} must further return a pointer to an object that has
-a method called @code{SetParent}. Just as clearly, @code{SetParent} must
-return a pointer to an object that has a method called @code{AddConstructor}.
-The same sort of thing is happening in our code snipped, except we are using
-references instead of pointers. Perhaps if we rearrange this code to live on
-one line it will be clearer.
-
-@verbatim
- ns3::TypeId ("A").SetParent (Object::GetTypeId ()).AddConstructor<A> ();
-@end verbatim
-
-It's just a string of method calls. The remaining question is then, what do
-those three methods do.
-
-The first, @code{ns3::TypeId ("A")}, simply allocates a new type in the system
-and allows you to refer to it in the future by a string. We have mentioned
-inheritance trees often in the previous discussion. The second method,
-@code{SetParent} associates the class being defined with its parents in the
-tree. Finally, the @code{AddConstructor} method allows you to specify a
-constructor to be used when an instance of your class is created using
-@code{CreateObject}.
-
-@verbatim
- AddConstructor<A> ();
-@end verbatim
-
-You can interpret this as explaining to the @command{ns-3} object system that
-you have a constructor named @code{A::A} which takes no parameters. You are
-saying that this constructor should be used when @code{CreateObject} is called
-with no parameters.
-
-By including the structure of the inheritance tree, in @command{ns-3} we can
-use implementation inheritance to easily create new @code{Objects}. You are
-prevented from doing so in Microsoft COM, but this was almost universally
-identified as a problem.
-
-So, looking at the entire @code{GetTypeId} declaration again,
-
-@verbatim
- static ns3::TypeId GetTypeId (void)
- {
- static ns3::TypeId tid = ns3::TypeId ("A")
- .SetParent (Object::GetTypeId ())
- .AddConstructor<A> ();
- return tid;
- }
-@end verbatim
-
-it should be clear what is happening.
-
-@subsection A Very Real Example
-@cindex Node
-@cindex AggregateObject
-@cindex GetObject
-@cindex Object
-At this point you may be asking yourself what the point of all of this is,
-since you already had those pointers laying around when you created the
-objects. The typical case is that one will create and aggregate some number
-of @code{Objects} in a constructor and return only a pointer to a single
-@code{Object} as in our canonical example with @code{class Node}. In this
-case, the @code{Node} would be created and the @code{Node} constructor might
-create and call @code{AggregateObject} to aggregate the @code{Objects} for
-internetwork routing and TCP/IP. From an external point of view, these
-aggregated objects may be discovered at run-time using @code{GetObject}.
-
-Generally one tends to think of one of the @code{Objects} in the aggregation
-as being the container and other @code{Objects} being aggregated to that
-container. In the case of a Node, for example, it is quite natural to think
-of the Node as being the container which contains protocol stacks, internet
-routing, etc. So, lets start thinking about a real example by calling the
-container @code{Object Node} instead of @code{A} as we have been. The
-creation of this @code{Object} is found all over our example programs. For
-example, you will find code like the following in
-@code{samples/simple-point-to-point.cc}:
-
-@verbatim
- Ptr<Node> n = CreateObject<InternetNode> ();
-@end verbatim
-
-It may appear obvious to you now that the @code{InternetNode} class name
-provided to the template function @code{CreateObject} means that
-@code{InternetNode} is an @command{ns-3} @code{Object} and you will be able to
-call @code{GetObject} on the resulting smart pointer. Well, I'm afraid that's
-not entirely true. It's slightly more complicated.
-
-Take a look at @code{src/internet-stack/internet-stack.h} and find the class
-declaration for @code{InternetNode}.
-
-@verbatim
- class InternetNode : public Node
- {
- public:
- InternetNode();
- ...
- };
-@end verbatim
-
-@cindex GetTypeId
-@cindex TypeId
-@cindex Object
-There is no declaration of a @code{static TypeId GetTypeId (void)} in this
-class. This means that the @code{InternetNode} is really not an @code{Object}
-for which you can @code{GetObject}. It turns out that the @code{InternetNode}
-is an @emph{implementation class} of the @code{Node Object}.
-
-You may recall that there can be an implicit cast in a smart pointer
-assignment if the cast is to a visible, unambiguous base class. That is, in
-fact, what is happening here. Now, take a look at @code{src/node/node.h} and
-find the class declaration for @code{class Node}. There you will find,
-
-@verbatim
- class Node : public Object
- {
- public:
- static TypeId GetTypeId (void);
- ...
- };
-@end verbatim
-
-Class @code{InternetNode} inherits from class @code{Node} that, in turn,
-inherits from class @code{Object}. It is @code{Node} that provides a
-@code{GetTypeId} method. Therefore it is @code{Node} that is an
-@command{ns-3} @code{Object}. Note well that @code{InternetNode} is not an
-@code{Object} in the sense that one should call @code{GetObject} on an
-aggregation looking for an @code{InternetNode} class. That is, you should not
-do,
-
-@verbatim
- Ptr<InternetNode> i = node->GetObject<InternetNode> ();
-@end verbatim
-
-since there really is not InternetNode::GetTypeId. It is @code{Node} that is
-the @emph{proper} @code{Object} in this case and you should view
-@code{InternetNode} as an implementation of the @code{Node Object}. This may
-become clearer as we look a little deeper.
-
-We spoke of a protocol stack that is aggregated to a @code{Node} in our
-discussions above, what we see in the real @command{ns-3} code is that this
-is represented by the @code{Ipv4 Object}. If you look in
-@code{src/node/ipv4.h} you will find,
-
-@verbatim
- class Ipv4 : public Object
- {
- public:
- static TypeId GetTypeId (void);
- ...
- };
-@end verbatim
-
-Since class @code{Ipv4} inherits from class @code{Object} and has a
-@code{GetTypeId}, it is an @command{ns-3} @code{Object}. If you look in
-@code{src/node/ipv4.cc} you will find,
-
-@verbatim
-TypeId
-Ipv4::GetTypeId (void)
-{
- static TypeId tid = TypeId ("Ipv4")
- .SetParent<Object> ();
- return tid;
-}
-@end verbatim
-
-After all of this reading you know that this code snippet is asking the
-system to create a unique @code{TypeId} for the @code{Ipv4} class and
-declares that @code{Ipv4} inherits from class @code{Object}. This is what
-makes an @code{Ipv4} an @code{Object}.
-
-@cindex Ipv4
-It turns out that the Ipv4 class is an abstract base class (ABC). There are
-a number of pure virtual methods declared in that class. This means that
-an @code{Ipv4} object may not be instantiated. This is reflected by the fact
-that there are no constructors registered in the @code{GetTypeId} method above.
-What is instantiated in the real system is an implementation class, called
-@code{Ipv4Impl}. This class inherits from @code{Ipv4} and provides the
-required virtual methods. This is where understanding what is an
-@code{Object} and what is not can get tricky. The @code{Object} is the
-@code{Ipv4} class since that is where the @code{GetTypeId} is found. The fact
-that you see @code{GetTypeId} there tells you that the @code{Ipv4} class is
-the class for which you can @code{GetObject}.
-
-@cindex implementation class
-The class @code{Ipv4Impl} provides an implementation for the pure virtual
-methods in @code{Ipv4}. Since class @code{Ipv4} cannot be instantiated, one
-instantiates the @code{Ipv4Impl} class to create an @code{Ipv4} @code{Object}.
-You will use the @code{CreateObject} template function to create an object that
-implements the methods of an @code{Object}. You can probably see how this
-gets even more tricky in conversation.
-
-Once the @code{Ipv4Impl} object is instantiated, the resulting pointer is
-immediately cast to an @code{Ipv4} pointer. Clients will then use the
-methods specified in the @code{Ipv4} class to access the @code{Ipv4 Object}
-methods which are, in turn, implemented in the @code{Ipv4Impl} object.
-
-If you now look in the file, @code{src/internet-stack/internet-stack.cc} you
-will see the following code in @code{InternetNode::Construct} that creates the
-@code{Ipv4} Interface and aggregates it.
-
-@verbatim
- Ptr<Ipv4Impl> ipv4Impl = CreateObject<Ipv4Impl> (ipv4);
- ...
- Object::AggregateObject (ipv4Impl);
-@end verbatim
-
-Note that the parameter @code{ipv4} passed to the @code{CreateObject} template
-function is actually a pointer to an @code{Ipv4L3Protocol} which you can
-ignore at this point --- it doesn't really have anything to do with the
-@code{Ipv4} Interface.
-
-This is exactly the same thing that is happening in the case of the
-@code{InternetNode}.
-
-@verbatim
- Ptr<Node> n = CreateObject<InternetNode> ();
-@end verbatim
-
-@cindex implementation object
-@code{CreateObject} is being called to create an implementation object,
-in this case @code{InternetNode}, which implements the methods of the
-@code{Node Object}. It is the resulting @code{Node Object} which you would
-use as the container and it is the @code{Node} class that you would use as
-the template parameter when calling @code{GetObject}. In the same way, you
-would @emph{not} want to do,
-
-@verbatim
- Ptr<Ipv4> ipv4 = node->GetObject<Ipv4Impl> ();
-@end verbatim
-
-Rather you should understand that the @emph{proper} @code{Object} is the
-@code{Ipv4} not the @code{Ipv4Impl} and do the following,
-
-@verbatim
- Ptr<Ipv4> ipv4 = node->GetObject<Ipv4> ();
-@end verbatim
-
-@cindex CreateObject
-This does illustrate that the fact that whether an object created by
-@code{CreateObject} is or is not an @code{Object} in the usual sense can be
-quite well hidden if you are casually looking at the object creation code.
-The designers of the system had long and involved discussions on this issue
-and in the end decided that mnemonic aids such as Hungarian notation were a
-stylistic thing and you should just refer to the system documentation to
-determine what objects are @command{ns-3} @code{Objects} and what the APIs
-of those @code{Objects} actually are (RTFM --- as in Read the Fine Manual,
-of course).
-
-@cindex AggregateObject
-@cindex Object
-In the case of @code{Ipv4Impl}, you know that the class inherits somehow
-from @code{Object} since there is a call to @code{AggregateObject} that
-refers to an instance of an @code{Ipv4Impl}. You will have to go to
-the header file @code{src/internet-stack/ipv4-impl.h} and find that
-@code{Ipv4Impl} inherits from class @code{Ipv4}. You will then have go to
-the file @code{src/node/ipv4.h} and see that it inherits from @code{Object} and
-defines a @code{GetTypeId}. Thus the @code{Object} for which you can
-@code{GetObject} is really the @code{Ipv4 Object}.
-
-Returning to some real @command{ns-3} example code, lets take a look at
-@code{examples/simple-point-to-point.cc}. You will find the following
-code in this file:
-
-@verbatim
- Ptr<Node> n0 = CreateObject<InternetNode> ();
- ...
- Ptr<Ipv4> ipv4;
- ipv4 = n0->GetObject<Ipv4> ();
- ipv4->SetDefaultRoute (Ipv4Address (``10.1.1.2''), 1);
-@end verbatim
-
-@cindex InternetNode
-@cindex Node
-@cindex Object
-@cindex GetObject
-The first line creates an @code{InternetNode} implementation object and casts
-the resulting smart pointer to a @code{Node} as we have discussed extensively.
-The next line shown declares a smart pointer to an @code{Ipv4 Object}. We
-then do a @code{GetObject} on the @code{Node} looking for the
-@code{Ipv4 Object}. You know since you've read every line of this tutorial
-in detail exactly how that @code{Ipv4 Object} got into every @code{Node}. You
-know that the @code{GetObject} will return a smart pointer to its aggregated
-@code{Ipv4} Interface. Once we have the @code{Ipv4} smart pointer, we simply
-use it as if it were any other C++ object. The last line shows this by
-setting the default route for the node.
-
-@section Caveats
-There are a few things that you should remember but which may not be
-immediately obvious.
-
-@subsection Ns-3 Objects are Associated with Classes not C++ objects
-@cindex Object
-@cindex GetObject
-@cindex iterate
-@cindex aggregation
-@cindex GetNDevices
-Okay, you can see some of the problems with the terminology popping up again.
-We are reminding you that when you do a GetObject you are providing the key
-to the lookup by giving a class name and not anything that is unique to a
-C++ object.
-
-You cannot add more than one @code{Object} of a given type (class name) to an
-aggregation. If you need to contain a number of @code{Objects} of the same
-type in the same aggregation, you will need to provide a separate container
-over which you can iterate. For example, the @code{Node} class provides
-methods,
-
-@verbatim
- uint32_t GetNDevices (void) const;
- Ptr<NetDevice> GetDevice (uint32_t index) const;
-@end verbatim
-
-that are used iterate over the multiple @code{NetDevice} @code{Objects}
-associated with it.
-
-@emph{Remember: Object types do not identify objects.}
-
-@subsection Don't use GetObject to Check Your Own Type.
-@cindex GetObject
-It is tempting to use @code{GetObject} as a form of runtime type
-information. Don't do it. You have no control over what @emph{other}
-object may be added to your aggregation. Someone else may have
-appropriated (reimplemented) your type and aggregated themselves onto the
-aggregation.
-
-Consider a socket factory implementation. Sockets can be either UDP sockets
-or TCP sockets. A socket factory will have a generic @code{SocketFactory}
-Object and either a UDP specific interface for setting UDP parameters or a
-similar TCP-specific interface.
-
-Consider what might happen if you declared your socket factory as a partially
-abstract base class, and then provided separate implementations for UDP and
-TCP specific methods of this factory in separate concrete classes. Now
-consider what might happen if you used @code{GetObject} in your base class
-to determine if you were a UDP or a TCP factory.
-
-If a factory, say the UDP version, were not aggregated to any other
-@code{Object}, the base class could @code{GetObject} on itself for the
-UDP-specific class name. If the @code{GetObject} succeeded, it could then
-infer that it was a UDP implementation and would then do any UDP-specific
-tasks it could. [Experienced C++ folks are cringing about how
-horrible this design is, but bear with me --- its a simple illustration of
-a specific and perhaps not-too-obvious problem.]
-
-If another factory, say the TCP version, were not aggregated to any other
-Interface, the base class could @code{GetObject} on itself for the UDP-specific
-interface. If this failed, it could then infer that it had a TCP
-implementation and would then do any TCP-specific tasks it could.
-
-Now, what happens when these two working objects are aggregated together by
-some innocent end-user. Since the @code{Objects} are conceptually snapped
-together, the TCP implementation would suddenly begin finding the UDP
-Interface from the other class factory and think it was the UPD implementation.
-
-@emph{Objects should not be used as run-time type information.}
-
-@section Connecting the Dots
-@cindex Object
-@cindex GetObject
-@cindex AggregateObject
-@cindex GetTypeId
-@cindex API
-This may all sound very complicated to you if this is your first exposure to
-these concepts. It may be annoying if I tell you that its really not as hard
-as it sounds. Rest assured that if you take some time, look at and understand
-the examples and write a little test code it will all come together for you.
-Grep around the system for @code{AggregateObject} and @code{GetObject} and
-take a look at how we have used them. This will also give you a good idea of
-what our core @code{Objects} and associated APIs are. If you grep for
-@code{GetTypeId} you will find most, if not all of the @code{Object} API
-interface declarations in the system. The more you see this idiom in
-use, the more comfortable you will be with the idea and the more you will see
-how this addresses the weak base class, swiss army knife base class, and
-fragile base class problems I explained at the beginning.
-
-As I alluded to earlier, the developers had long discussions regarding how to
-make navigating the @code{Object} environment easier. The primary issue was
-how we could make it easier to convey to you, the model writer, that an object
-was an @code{Object}. We originally used similar terminology as Microsoft
-COM and used QueryInterface instead of @code{GetObject}. One suggestion was
-to adopt the convention that classes that implemented Interfaces must begin
-with the letter I. Microsoft does this, as exemplified by the class IUnknown.
-We also toyed with the idea of beginning our header files with ``i-'' as in
-``i-ipv4.h.'' We considered forcing some structure on Interfaces with a pure
-virtual class specification, the names of which begin with an I; and
-corresponding implementations, the names of which begin with a C. This all
-got out of hand fairly quickly.
-
-In the end we decided that we were really discussing issues of programming
-style, and we really could not come up with a strong reason to impose any
-particular solution. No matter what direction we took, we ended up with some
-form of extra confusion or extra complexity somewhere in the system. The
-resulting system is extremely flexible and easy to use. It is, unfortunately,
-sometimes hard to document and talk about.
-
-@cindex Feynman
-If it helps you to think in terms of Microsoft COM and Interfaces, by all means
-do so, just be aware that even though @command{ns-3} @code{Objects} descend
-from COM in some sense, there are subtle differences that may get you lost or
-into trouble. So to paraphrase Feynman one more time,
-
-@quotation
-``@command{Ns-3} @code{Objects} do not behave like COM Components, or Java
-Beans, or CORBA objects, or clouds or weights on springs, or like anything
-that you have ever seen --- they are @command{ns-3} components.''
-@end quotation
-
-Just get very familiar with the @command{ns-3} object model. It is the heart
-of the system and if you do not understand it you will not understand how to
-write an @command{ns-3} model properly.
-
-@c ========================================================================
-@c Doxygen
-@c ========================================================================
-
-@node The-Doxygen-Documentation-System
-@chapter The Doxygen Documentation System
-
-@node How-To-Change-Things
-@chapter How to Change Things
-
-@node How-To-Set-Default-Values
-@chapter How to Set Default Values
-
-@node How-To-Write-A-New-Application
-@chapter How to Write a New Application
-
--- a/doc/manual/output.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,462 +0,0 @@
-
-@c ========================================================================
-@c Simulation Output
-@c ========================================================================
-
-@node Simulation Output
-@chapter Simulation Output
-
-At this point, you should be able to execute any of the built-in
-programs distributed with @command{ns-3}. Next, we will look at
-how to generate and tailor the simulation output, before turning
-to how to modify simulation scripts to do different things.
-
-@node Tracing Basics
-@section Tracing Basics
-
-The whole point of simulation is to generate output for further
-study, and the @command{ns-3} tracing system is a primary
-mechanism for this.
-Since @command{ns-3} is a C++ program, standard facilities for
-generating output from C++ programs apply:
-
-@verbatim
-#include <iostream>
-...
-int main ()
-{
- ...
- std::cout << "The value of x is " << x << std::endl;
- ...
-}
-@end verbatim
-
-The goal of the @command{ns-3} tracing system is to
-provide a structured way to configure the simulator to output results
-in standard or modifiable formats.
-@itemize @bullet
-@item For basic tasks, the tracing system should allow the user to
-generate standard tracing for popular tracing sources, and to customize
-which objects generate the tracing.
-@item Intermediate users will be able to extend the tracing system to
-modify the output format generated, or to insert new tracing sources,
-without modifying the core of the simulator.
-@item Advanced users can modify the simulator core to add new
-tracing sources and sinks.
-@end itemize
-
-The @command{ns-3} tracing system is fundamentally built on the
-concept of separating tracing sources from sinks.
-@enumerate
-@item Trace sources (e.g., provide access to every packet received)
-@item Trace sinks (e.g., print out the packet)
-@item A mechanism to tie together sources and sinks
-@end enumerate
-The rationale for this division is to allow users to attach new
-types of sinks to existing tracing sources, without requiring
-users to edit and recompile the core of the simulator.
-Thus, in the example above, a user could write a new tracing sink
-and attach it to an existing tracing source. What remains to
-be defined is a way for users to find these hooks (tracing sources)
-and attach sinks to them. A new tracing namespace is defined for
-this purpose.
-
-We will first walk through how some pre-defined sources and sinks
-are provided and may be customized with little user effort. We
-return later in this chapter to advanced tracing configuration including
-extending the tracing namespace and creating new tracing sources.
-
-@subsection ASCII tracing
-@cindex ASCII
-For Internet nodes, the ASCII trace wrapper is a wrapper around
-the @command{ns-3} low-level
-tracing system that lets you get access to underlying trace events easily.
-The output of a trace of a simulation run is an ASCII file --- thus the name.
-In the spirit of keeping things simple, you won't be able to control or
-configure the output at this stage.
-
-For those familiar with @command{ns-2} output, this type of trace is
-analogous to the @command{out.tr} generated by many scripts.
-
-@cindex tracing packets
-Let's just jump right in. As usual, we need to include the definitions
-related to using ASCII tracing (don't edit any files quite yet):
-
-@verbatim
- #include "ns3/ascii-trace.h"
-@end verbatim
-
-We then need to add the code to the script to actually enable the ASCII tracing
-code. The following code must be inserted before the call to
-@code{Simulator::Run ();}:
-
-@verbatim
- AsciiTrace asciitrace ("tutorial.tr");
- asciitrace.TraceAllQueues ();
- asciitrace.TraceAllNetDeviceRx ();
-@end verbatim
-
-The first line declares an object of type @code{AsciiTrace} named
-@code{asciitrace} and passes a string parameter to its constructor. This
-parameter is a file name to which all of the trace information will be written.
-The second line, @code{asciitrace.TraceAllQueues ();} asks the trace object to
-arrange that all queue operations (enqueue, dequeue, drop) on the queues
-in all of the nodes of the system be traced. On the receive side,
-@code{asciitrace.TraceAlllNetDeviceRx ()} traces packets received by
-a NetDevice. For those familiar with @command{ns-2}, these are equivalent
-to the popular trace points that log "+", "-", "d", and "r" events.
-
-Try running the following program from the command line:
-@verbatim
- ./waf --run tutorial-csma-echo-ascii-trace
-@end verbatim
-
-@cindex tutorial.tr
-Just as you have seen previously, you will see some messages from @emph{Waf}
-and then the ``Compilation finished successfully'' message. The
-next message, @code{UDP Echo Simulation} is from the running program. When
-it ran, the program will have created a file named @code{tutorial.tr}.
-Because of the way that Waf works, the file is not created in the local
-directory, it is created at the top-level directory of the repository. So,
-change into the top level directory and take a look at the file
-@code{tutorial.tr} in your favorite editor.
-
-@subsubsection Parsing ASCII Traces
-@cindex parsing ASCII traces
-
-This section parses in detail the structure of the ASCII tracing
-output. If you find this output format self explanatory (it
-resembles tcpdump output), you may skip to the next
-section on pcap tracing.
-
-@cindex trace event
-There's a lot of information there in a pretty dense form, but the first thing
-to notice is that there are a number of distinct lines in this file. It may
-be difficult to see this clearly unless you widen your windows considerably.
-Each line in the file corresponds to a @emph{trace event}. A trace event
-happens whenever specific conditions happen in the simulation. In this case
-we are tracing events on the @emph{device queue} present in every net device
-on every node in the simulation. The device queue is a queue through which
-every packet destined for a channel must pass --- it is the device
-@emph{transmit} queue. Note that each line in the trace file begins with a
-lone character (has a space after it). This character will have the following
-meaning:
-
-@cindex enqueue
-@cindex dequeue
-@cindex drop
-@itemize @bullet
-@item @code{+}: An enqueue operation occurred on the device queue;
-@item @code{-}: A dequeue operation occurred on the device queue;
-@item @code{d}: A packet was dropped, typically because the queue was full.
-@end itemize
-
-Let's take a more detailed view of the first line. I'll break it down into
-sections (indented for clarity) with a two digit reference number on the
-left side:
-
-@verbatim
- 00 +
- 01 2
- 02 nodeid=0
- 03 device=0
- 04 queue-enqueue
- 05 pkt-uid=9
- 06 ETHERNET
- 07 length/type=0x806,
- 08 source=08:00:2e:00:00:00,
- 09 destination=ff:ff:ff:ff:ff:ff
- 10 ARP(request
- 11 source mac: 08:00:2e:00:00:00
- 12 source ipv4: 10.1.1.1
- 13 dest ipv4: 10.1.1.2)
- 14 ETHERNET fcs=0
-@end verbatim
-
-@cindex trace event
-@cindex simulation time
-The first line of this expanded trace event (reference number 00) is the
-queue operation. We have a @code{+} character, so this corresponds to an
-@emph{enqueue} operation. The second line (reference 01) is the simulation
-time expressed in seconds. You may recall that we asked the
-@code{UdpEchoClient} to start sending packets at two seconds. Here we see
-confirmation that this is, indeed, happening.
-
-@cindex node number
-@cindex net device number
-@cindex smart pointer
-The next lines of the example listing (references 02 and 03) tell us that
-this trace event originated in a given node and net device. Each time a node
-is created it is given an identifying number that monotonically increases from
-zero. Therefore, @code{nodeid=0} means that the node in which the given trace
-event originated is the first node we created. In the case of our script,
-this first node is is the node pointed to by the smart pointer @code{n0}. Not
-too surprisingly, this is also the node to which we attached the
-@code{UdpEchoClient}. The device number is local to each node, and so the
-device given by @code{device=0} is the first net device that we added to the
-node in question. In our simulation, this corresponds to the
-@code{CsmaNetDevice} we added to node zero (@code{n0}).
-
-@cindex uid
-@cindex unique ID
-@cindex packet
-The next line (reference 04) is a more readable form of the operation code
-seen in the first line --- i.e., the character @code{+} means
-@code{queue-enqueue}. Reference number 05 indicates that the @emph{unique id}
-of the packet being enqueued is @code{9}. The fact that the first packet we
-see has a unique ID of 9 should indicates to you that other things have
-happened in the protocol stack before we got to this point. This will become
-clear momentarily.
-
-@cindex Ethernet
-@cindex MAC address
-Reference items 06 and 14 indicate that this is an Ethernet packet with
-a zero (not computed) checksum (note the indentation to make parsing this
-trace event a little easier). Reference 08 and 09 are the source and
-destination addresses of this packet. The packet is from the MAC address we
-assigned to the node zero net device in the script, and is destined for the
-broadcast address --- this is a broadcast packet.
-
-@cindex Address Resolution Protocol
-@cindex ARP
-@cindex ARP|request
-Reference items 10 through 13 make clear what is happening. This is an ARP
-(Address Resolution Protocol) request for the MAC address of the node on
-which the @code{UdpEchoServer} resides. The protocol stack can't send a UDP
-packet to be echoed until it knows (resolves) the MAC address; and this trace
-event corresponds to an ARP request being queued for transmission to the local
-network. The next line in the trace file (partially expanded),
-
-@verbatim
- 00 -
- 01 2
- 02 nodeid=0
- 03 device=0
- 04 queue-dequeue
- 05 pkt-uid=9
- ...
-@end verbatim
-
-shows the (same) ARP request packet being dequeued from the device queue by
-the net device and (implicitly) being sent down the channel to the broadcast
-MAC address. We are not tracing net device reception events so we don't
-actually see all of the net devices receiving the broadcast packet. We do,
-however see the following in the third line of the trace file:
-
-@verbatim
- 00 +
- 01 2.00207
- 02 nodeid=1
- 03 device=0
- 04 queue-enqueue
- 05 pkt-uid=10
- 06 ETHERNET
- 07 length/type=0x806,
- 08 source=08:00:2e:00:00:01,
- 09 destination=08:00:2e:00:00:00,
- 10 ARP(reply
- 11 source mac: 08:00:2e:00:00:01
- 12 source ipv4: 10.1.1.2
- 13 dest mac: 08:00:2e:00:00:00
- 14 dest ipv4: 10.1.1.1)
- 15 ETHERNET fcs=0
-@end verbatim
-
-@cindex simulation time
-@cindex ARP|response
-Notice that this is a queue-enqueue operation (references 00 and 04) happening
-on node one (reference 02) at simulation time 2.00207 seconds (reference 01).
-Looking at the packet payload (references 10-14) we see that this is an ARP
-reply to the request sent by node one. Note that the simulation time
-(reference 01) is now 2.00207 seconds. This is direct result of the data rate
-(5 MB/s) and latency (2 ms) parameters that we passed to the
-@code{CsmaChannel} when we created it. Clearly the ARP request packet was
-sent over the channel and received approximately 2 ms later by node one. A
-corresponding ARP response packet was created and enqueued on node ones net
-device. It is this enqueue trace event that has being logged.
-
-@cindex queue
-@cindex queue|transmit
-@cindex echo
-Given the current state of affairs, the next thing you may expect to see is
-this ARP request being received by node zero, but remember we are only looking
-at trace events on the device @emph{transmit} queue. The reception of the ARP
-response by node zero will not directly trigger any trace event in this case,
-but it will enable the protocol stack to continue what it was originally doing
-(trying to send an echo packet). Thus, the next line we see in the trace file
-(@code{tutorial.tr}) is the first UDP echo packet being sent to the net device.
-
-@verbatim
- 00 +
- 01 2.00415
- 02 nodeid=0
- 03 device=0
- 04 queue-enqueue
- 05 pkt-uid=7
- 06 ETHERNET
- 07 length/type=0x800,
- 08 source=08:00:2e:00:00:00,
- 09 destination=08:00:2e:00:00:01
- 10 IPV4(
- 11 tos 0x0
- 12 ttl 64
- 13 id 0
- 14 offset 0
- 15 flags [none]
- 16 length: 1052) 10.1.1.1 > 10.1.1.2
- 17 UDP(length: 1032)
- 18 49153 > 7
- 19 DATA (length 1024)
- 20 ETHERNET fcs=0
-@end verbatim
-
-@cindex simulation time
-@cindex echo
-@cindex ARP
-@cindex ARP|request
-@cindex ARP|response
-@cindex IP
-@cindex Ipv4
-I won't go into too much detail about this packet, but I will point out a
-few key items in the trace. First, the packet was enqueued at simulation time
-of 2.00415 seconds. This time reflects the fact that the echo client
-application started at 2. seconds and there were two ARP packets transmitted
-across the network (two milliseconds + data transmission time each way). The
-packet unique identifier (reference 05) is 7. Notice that this is a lower
-number than the ARP request packet, which had a unique ID of 9. This tells
-us that the UDP packet was actually created before the ARP request packet ---
-which makes perfect sense since it was the attempt to send packet 7 that
-triggered sending the ARP request packet 9. Note that this an Ethernet
-packet (reference 06) like all other packets in this simulation, however this
-particular packet carries an IPV4 payload and therefore has an IP version 4
-header (indicated by references 10-16). This Ipv4 in turn contains a UDP
-header (references 17, 18) and finally 1024 bytes of data (reference 20).
-Clearly, this is the UDP echo packet emitted by the
-@code{UdpEchoClient Application}.
-
-The next trace event is an ARP request from node one. We can infer that node
-one has received the UDP echo packet and the @code{UdpEchoServer Application}
-on that node has turned the packet around. Just as node zero needed to ARP
-for the MAC address of node one, now node one must ARP for the MAC address of
-node zero. We see the ARP request enqueued on the transmit queue of node one;
-then we see the ARP request dequeued from the transmit queue of node one (and
-implicitly transmitted to node zero). Then we see an ARP response enqueued
-on the transmit queue of node zero; and finally the ARP response dequeued (and
-implicitly transmitted back to node one).
-
-This exchange is summarized in the following trace event excerpts,
-
-@verbatim
- + 2.00786 nodeid=1 ... ARP(request ...
- - 2.00786 nodeid=1 ... ARP(request ...
- + 2.00994 nodeid=0 ... ARP(reply ...
- - 2.00994 nodeid=0 ... ARP(reply ...
-@end verbatim
-
-The final two trace events in the @code{tutorial.tr} file correspond to the
-echoed packet being enqueued for transmission on the net device for node one,
-and that packet being dequeued (and implicitly transmitted back to node zero).
-
-@cindex AsciiTrace!TraceAllNetDeviceRx
-@cindex ARP!request
-If you look at the trace file (@code{tutorial.tr}) you will also see some
-entries with an @code{r} event, indicating a
-@emph{receive} trace event. Recall that the first packet sent on the network
-was a broadcast ARP request. We should then see all four nodes receive a
-copy of this request. This is the case, as the first four receive trace
-events are,
-
-@verbatim
- r 2.00207 nodeid=0 device=0 dev-rx pkt-uid=9 ARP(request ...
- r 2.00207 nodeid=1 device=0 dev-rx pkt-uid=9 ARP(request ...
- r 2.00207 nodeid=2 device=0 dev-rx pkt-uid=9 ARP(request ...
- r 2.00207 nodeid=3 device=0 dev-rx pkt-uid=9 ARP(request ...
-@end verbatim
-
-@cindex unique ID
-You can see that a copy of the broadcast packet with unique ID 9 was received
-by the net devices on nodes 0, 1, 2 and 3. We leave it up to you to parse the
-rest of the trace file and understand the remaining reception events.
-
-@subsection PCAP Trace Wrapper
-@cindex pcap
-@cindex Wireshark
-The @command{ns-3} @emph{pcap trace wrapper} is used to create trace files in
-@code{.pcap} format. The acronym pcap (usually written in lower case) stands
-for @emph{p}acket @emph{cap}ture, and is actually an API that includes the
-definition of a @code{.pcap} file format. The most popular program that can
-read and display this format is Wireshark (formerly called Ethereal).
-However, there are many traffic trace analyzers that use this packet
-format, including X, Y, and Z. We encourage users to exploit the
-many tools available for analyzing pcap traces; below, we show how
-tcpdump and Wireshark can be used..
-
-@cindex tutorial-csma-echo-ascii-trace.cc
-@cindex tutorial-csma-echo-pcap-trace.cc
-The code used to enable pcap tracing is similar to that for ASCII tracing.
-We have provided another file, @code{tutorial-csma-echo-pcap-trace.cc} that
-uses the pcap trace wrapper. We have added the code to include the pcap
-trace wrapper definitions:
-
-@verbatim
- #include "ns3/pcap-trace.h"
-@end verbatim
-
-And then added the following code below the AsciiTrace methods:
-
-@cindex PcapTrace
-@cindex PcapTrace!TraceAllIp
-@verbatim
- PcapTrace pcaptrace ("tutorial.pcap");
- pcaptrace.TraceAllIp ();
-@end verbatim
-
-The first line of the code immediately above declares an object of type
-@code{PcapTrace} named @code{pcaptrace} and passes a string parameter to its
-constructor. This object is used to hide the details of the actual tracing
-subsystem. The parameter is a base file name from which the actual trace file
-names will be built. The second line of code tells the @code{PcamTrace}
-object to trace all IP activity in all of the nodes present in the simulation.
-
-@cindex interface index
-Trace files are not created until trace activity is detected. Each file name
-is composed of the base file name, followed by a @code{'-'}, a node id followed
-by a @code{'-}', and an IP interface index. You will soon see a file named
-@code{tutorial.pcap-0-1}, for example. This will be the trace file generated
-as events are detected on node zero, interface index one. N.B. Interface
-indices are different that net device indices --- interface index zero
-corresponds to the loopback interface and interface index one corresponds to
-the first net device you added to a node.
-
-You may run the new program just like all of the others so far:
-
-@cindex Waf
-@verbatim
- ./waf --run tutorial-csma-echo-pcap-trace
-@end verbatim
-
-If you look at the top level directory of your distribution, you should now
-see three log files: @code{tutorial.tr} is the ASCII trace file we have
-previously examined. @code{tutorial.pcap-0-1} and @code{tutorial.pcap-1-1}
-are the new pcap files we just generated. There will not be files
-corresponding to nodes two and three since we have not sent any IP packets to
-those nodes.
-
-@subsubsection Reading output with tcpdump
-@cindex tcpdump
-
-@subsubsection Reading output with Wireshark
-@cindex Wireshark
-If you are unfamiliar with Wireshark, there is a web site available from which
-you can download programs and documentation: @uref{http://www.wireshark.org/}.
-
-If you have Wireshark available, you can open each of the trace files and
-display the contents as if you had captured the packets using a
-@emph{packet sniffer}. Note that only IP packets are traced using this
-wrapper, so you will not see the ARP exchanges that were logged when using
-the ASCII trace wrapper. You are encouraged to take a look at the contents
-of these pcap files using your favorite pcap software (or Wireshark).
-
-@node Advanced Tracing
-@section Advanced Tracing
-
--- a/doc/manual/packets.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,712 +0,0 @@
-@node Packets
-@chapter Packets
-
-The design of the Packet framework of @emph{ns} was heavily guided by a few
-important use-cases:
-@itemize @bullet
-@item avoid changing the core of the simulator to introduce
-new types of packet headers or trailers
-@item maximize the ease of integration with real-world code
-and systems
-@item make it easy to support fragmentation, defragmentation,
-and, concatenation which are important, especially in wireless systems.
-@item make memory management of this object efficient
-@item allow actual application data or dummy application bytes for
-emulated applications
-@end itemize
-
-Each network packet contains a byte buffer, a set of byte tags, a set of
-packet tags, and metadata.
-
-The byte buffer stores the serialized content of the headers and trailers
-added to a packet. The serialized representation of these headers is expected
-to match that of real network packets bit for bit (although nothing
-forces you to do this) which means that the content of a packet buffer
-is expected to be that of a real packet.
-
-Fragmentation and defragmentation are quite natural to implement within
-this context: since we have a buffer of real bytes, we can split it in
-multiple fragments and re-assemble these fragments. We expect that this
-choice will make it really easy to wrap our Packet data structure within
-Linux-style skb or BSD-style mbuf to integrate real-world kernel code in
-the simulator. We also expect that performing a real-time plug of the
-simulator to a real-world network will be easy.
-
-One problem that this design choice raises is that it is difficult to
-pretty-print the packet headers without context. The packet metadata
-describes the type of the headers and trailers which
-were serialized in the byte buffer. The maintenance of metadata is
-optional and disabled by default. To enable it, you must call
-Packet::EnableMetadata() and this will allow you to get non-empty
-output from Packet::Print and Packet::Print.
-
-Also, developers often want to store data in packet objects that is not found
-in the real packets (such as timestamps or flow-ids). The Packet class
-deals with this requirement by storing a set of tags (class Tag).
-We have found two classes of use cases for these tags, which leads to
-two different types of tags. So-called
-'byte' tags are used to tag a subset of the bytes in the packet byte buffer
-while 'packet' tags are used to tag the packet itself. The main difference
-between these two kinds of tags is what happens when packets are copied,
-fragmented, and reassembled: 'byte' tags follow bytes while 'packet' tags
-follow packets. Another important difference between these two kinds of tags
-is that byte tags cannot be removed and are expected to be written once,
-and read many times, while packet tags are expected to be written once,
-read many times, and removed exactly once. An example of a 'byte'
-tag is a FlowIdTag which contains a flow id and is set by the application
-generating traffic. An example of a 'packet' tag is a cross-layer
-QoS class id set by an application and processed by a lower-level MAC
-layer.
-
-Memory management of Packet objects is entirely automatic and extremely
-efficient: memory for the application-level payload can be modeled by
-a virtual buffer of zero-filled bytes for which memory is never allocated
-unless explicitly requested by the user or unless the packet is fragmented
-or serialized out to a real network device.
-Furthermore, copying, adding, and, removing headers or trailers to a packet
-has been optimized to be virtually free through a technique known as
-Copy On Write.
-
-Packets (messages) are fundamental objects in the simulator and
-their design is important from a performance and resource management
-perspective. There
-are various ways to design the simulation packet, and tradeoffs
-among the different approaches. In particular, there is a
-tension between ease-of-use, performance, and safe interface
-design.
-
-@section Packet design overview
-
-Unlike @emph{ns-2}, in which Packet objects contain a buffer of C++
-structures corresponding to protocol headers, each network packet in
-@emph{ns-3} contains a byte Buffer, a list of byte Tags, a list of
-packet Tags, and a PacketMetadata object:
-@itemize @bullet
-@item The byte buffer stores the serialized content of the chunks
-added to a packet. The serialized representation of these chunks is
-expected to match that of real network packets bit for bit
-(although nothing forces you to do this) which means that the content
-of a packet buffer is expected to be that of a real packet.
-Packets can also be created with an arbitrary zero-filled payload
-for which no real memory is allocated.
-@item Each list of tags stores an arbitrarily large set of arbitrary
-user-provided data structures in the packet. Each Tag is uniquely
-identified by its type; only one instance of each
-type of data structure is allowed in a list of tags. These tags typically
-contain per-packet cross-layer information or flow identifiers (i.e.,
-things that you wouldn't find in the bits on the wire).
-@end itemize
-
-@float Figure,fig:packets
-@caption{Implementation overview of Packet class.}
-@image{figures/packet, 4in}
-@end float
-
-Figure @ref{fig:packets} is a high-level overview of the Packet
-implementation; more detail on the byte Buffer implementation
-is provided later in Figure @ref{fig:buffer}.
-In \nsthree, the Packet byte buffer is analogous to a Linux skbuff
-or BSD mbuf; it is a serialized representation of the actual
-data in the packet. The tag lists are containers for extra
-items useful for simulation convenience; if a Packet is converted
-to an emulated packet and put over an actual network, the tags
-are stripped off and the byte buffer is copied directly
-into a real packet.
-
-Packets are reference counted objects. They are handled with smart
-pointer (Ptr) objects like many of the objects in the ns-3 system.
-One small difference you will see is that class Packet does not
-inherit from class Object or class RefCountBase, and implements the
-Ref() and Unref() methods directly. This was designed to avoid the overhead
-of a vtable in class Packet.
-
-The Packet class is designed to be copied cheaply; the overall design
-is based on Copy on Write (COW). When there are multiple references
-to a packet object, and there is an operation on one of them, only
-so-called "dirty" operations will trigger a deep copy of the packet:
-@itemize @bullet
-@item @code{ns3::Packet::AddHeader()}
-@item @code{ns3::Packet::AddTrailer()}
-@item @code{both versions of ns3::Packet::AddAtEnd()}
-@item @code{Packet::RemovePacketTag()}
-@end itemize
-
-The fundamental classes for adding to and removing from the byte
-buffer are @code{class Header} and @code{class Trailer}.
-Headers are more common but the below discussion also largely applies to
-protocols using trailers. Every protocol header that needs to
-be inserted and removed from a Packet instance should derive from
-the abstract Header base class and implement the private pure
-virtual methods listed below:
-@itemize @bullet
-@item @code{ns3::Header::SerializeTo()}
-@item @code{ns3::Header::DeserializeFrom()}
-@item @code{ns3::Header::GetSerializedSize()}
-@item @code{ns3::Header::PrintTo()}
-@end itemize
-Basically, the first three functions are used to serialize and deserialize
-protocol control information to/from a Buffer. For example,
-one may define @code{class TCPHeader : public Header}. The
-TCPHeader object will typically consist of some private data
-(like a sequence number) and public interface access functions
-(such as checking the bounds of an input). But the underlying
-representation of the TCPHeader in a Packet Buffer is 20 serialized
-bytes (plus TCP options). The TCPHeader::SerializeTo() function would
-therefore be designed to write these 20 bytes properly into
-the packet, in network byte order. The last function is used
-to define how the Header object prints itself onto an output stream.
-
-Similarly, user-defined Tags can be appended to the packet.
-Unlike Headers, Tags are not serialized into a contiguous buffer
-but are stored in lists. Tags can be flexibly defined to be any
-type, but there
-can only be one instance of any particular object type in
-the Tags buffer at any time.
-
-@section Using the packet interface
-
-This section describes how to create and use the @code{ns3::Packet} object.
-
-@subsection Creating a new packet
-
-The following command will create a new packet with a new unique
-Id.
-
-@verbatim
- Ptr<Packet> pkt = Create<Packet> ();
-@end verbatim
-
-What is the Uid (unique Id)? It is an internal id that the
-system uses to identify packets. It can be fetched via the following
-method:
-@verbatim
- uint32_t uid = pkt->GetUid ();
-@end verbatim
-
-But please note the following. This uid is an internal uid and cannot
-be counted on to provide an accurate counter of how many
-"simulated packets" of a particular protocol are in the system.
-It is not trivial to make this uid into such a counter, because of
-questions such as what should the uid be when the packet is
-sent over broadcast media, or when fragmentation occurs. If a user
-wants to trace actual packet counts, he or she should look at
-e.g. the IP ID field or transport sequence numbers, or other packet
-or frame counters at other protocol layers.
-
-We mentioned above that it is possible to create packets with zero-filled
-payloads that do not actually require a memory allocation (i.e.,
-the packet may behave, when delays such as serialization or transmission
-delays are computed, to have a certain number of payload bytes, but
-the bytes will only be allocated on-demand when needed). The command to do
-this is, when the packet
-is created:
-@verbatim
- Ptr<Packet> pkt = Create<Packet> (N);
-@end verbatim
-where N is a positive integer.
-
-The packet now has a size of N bytes, which can be verified by the GetSize()
-method:
-@verbatim
- /**
- * \returns the size in bytes of the packet (including the zero-filled
- * initial payload)
- */
- uint32_t GetSize (void) const;
-@end verbatim
-
-You can also initialize a packet with a character buffer. The input
-data is copied and the input buffer is untouched. The constructor
-applied is:
-@verbatim
- Packet (uint8_t const *buffer, uint32_t size);
-@end verbatim
-Here is an example:
-@smallformat
-@example
- Ptr<Packet> pkt1 = Create<Packet> (reinterpret_cast<const uint8_t*> ("hello"), 5);
-@end example
-@end smallformat
-
-Packets are freed when there are no more references to them, as with
-all ns-3 objects referenced by the Ptr class.
-
-@subsection Adding and removing Buffer data
-
-After the initial packet creation (which may possibly create some
-fake initial bytes of payload), all subsequent buffer data is added by adding
-objects of class Header or class Trailer. Note that, even if you are
-in the application layer, handling packets, and want to write application
-data, you write it as an ns3::Header or ns3::Trailer. If you add a Header,
-it is prepended to the packet, and if you add a Trailer, it is added to
-the end of the packet. If you have no data in the packet, then it
-makes no difference whether you add a Header or Trailer. Since the
-APIs and classes for header and trailer are pretty much identical, we'll
-just look at class Header here.
-
-The first step is to create a new header class. All new Header classes
-must inherit from class Header, and implement the following methods:
-@itemize @bullet
-@item @code{Serialize ()}
-@item @code{Deserialize ()}
-@item @code{GetSerializedSize ()}
-@item @code{Print ()}
-@end itemize
-
-To see a simple example of how these are done, look at the UdpHeader
-class headers src/internet-stack/udp-header.cc. There are many other
-examples within the source code.
-
-Once you have a header (or you have a preexisting header), the following
-Packet API can be used to add or remove such headers.
-
-@smallformat
-@example
- /**
- * Add header to this packet. This method invokes the
- * Header::GetSerializedSize and Header::Serialize
- * methods to reserve space in the buffer and request the
- * header to serialize itself in the packet buffer.
- *
- * \param header a reference to the header to add to this packet.
- */
- void AddHeader (const Header & header);
- /**
- * Deserialize and remove the header from the internal buffer.
- * This method invokes Header::Deserialize.
- *
- * \param header a reference to the header to remove from the internal buffer.
- * \returns the number of bytes removed from the packet.
- */
- uint32_t RemoveHeader (Header &header);
- /**
- * Deserialize but does _not_ remove the header from the internal buffer.
- * This method invokes Header::Deserialize.
- *
- * \param header a reference to the header to read from the internal buffer.
- * \returns the number of bytes read from the packet.
- */
- uint32_t PeekHeader (Header &header) const;
-@end example
-@end smallformat
-
-For instance, here are the typical operations to add and remove a UDP header.
-
-@smallformat
-@example
- // add header
- Ptr<Packet> packet = Create<Packet> ();
- UdpHeader udpHeader;
- // Fill out udpHeader fields appropriately
- packet->AddHeader (udpHeader);
- ...
- // remove header
- UdpHeader udpHeader;
- packet->RemoveHeader (udpHeader);
- // Read udpHeader fields as needed
-@end example
-@end smallformat
-
-@subsection Adding and removing Tags
-
-There is a single base class of Tag that all packet tags must derive from.
-They are used in two different tag lists in the packet; the lists have
-different semantics and different expected use cases.
-
-As the names imply, ByteTags follow bytes and PacketTags follow packets.
-What this means is that when operations are done on packets, such as
-fragmentation, concatenation, and appending or removing headers, the
-byte tags keep track of which packet bytes they cover. For instance,
-if a user creates a TCP segment, and applies a ByteTag to the segment,
-each byte of the TCP segment will be tagged. However, if the next
-layer down inserts an IPv4 header, this ByteTag will not cover those
-bytes. The converse is true for the PacketTag; it covers a packet
-despite the operations on it.
-
-PacketTags are limited in size to 20 bytes. This is a modifiable
-compile-time constant in @code{src/common/packet-tag-list.h}. ByteTags
-have no such restriction.
-
-Each tag type must subclass @code{ns3::Tag}, and only one instance of
-each Tag type may be in each tag list. Here are a few differences
-in the behavior of packet tags and byte tags.
-@itemize @bullet
-@item @strong{Fragmentation:} As mentioned above, when a packet is fragmented,
-each packet fragment (which is a new packet) will get a copy of all packet
-tags, and byte tags will follow the new packet boundaries (i.e. if the
-fragmented packets fragment across a buffer region covered by the byte
-tag, both packet fragments will still have the appropriate buffer regions
-byte tagged).
-@item @strong{Concatenation:} When packets are combined, two different
-buffer regions will become one. For byte tags, the byte tags simply
-follow the respective buffer regions. For packet tags, only the
-tags on the first packet survive the merge.
-@item @strong{Finding and Printing:} Both classes allow you to iterate
-over all of the tags and print them.
-@item @strong{Removal:} Users can add and remove the same packet tag
-multiple times on a single packet (AddPacketTag () and RemovePacketTag ()).
-The packet However, once a byte tag is added,
-it can only be removed by stripping all byte tags from the packet.
-Removing one of possibly multiple byte tags is not supported by the
-current API.
-@end itemize
-
-As of ns-3.5, Tags are not serialized and deserialized to a buffer when
-@code{Packet::Serialize ()} and @code{Packet::Deserialize ()} are called;
-this is an open bug.
-
-If a user wants to take an existing packet object and reuse it as a new
-packet, he or she should remove all byte tags and packet tags before doing so.
-An example is the UdpEchoServer class, which takes the received packet
-and "turns it around" to send back to the echo client.
-
-The Packet API for byte tags is given below.
-@smallformat
-@example
- /**
- * \param tag the new tag to add to this packet
- *
- * Tag each byte included in this packet with the
- * new tag.
- *
- * Note that adding a tag is a const operation which is pretty
- * un-intuitive. The rationale is that the content and behavior of
- * a packet is _not_ changed when a tag is added to a packet: any
- * code which was not aware of the new tag is going to work just
- * the same if the new tag is added. The real reason why adding a
- * tag was made a const operation is to allow a trace sink which gets
- * a packet to tag the packet, even if the packet is const (and most
- * trace sources should use const packets because it would be
- * totally evil to allow a trace sink to modify the content of a
- * packet).
- */
- void AddByteTag (const Tag &tag) const;
- /**
- * \returns an iterator over the set of byte tags included in this packet.
- */
- ByteTagIterator GetByteTagIterator (void) const;
- /**
- * \param tag the tag to search in this packet
- * \returns true if the requested tag type was found, false otherwise.
- *
- * If the requested tag type is found, it is copied in the user's
- * provided tag instance.
- */
- bool FindFirstMatchingByteTag (Tag &tag) const;
-
- /**
- * Remove all the tags stored in this packet.
- */
- void RemoveAllByteTags (void);
-
- /**
- * \param os output stream in which the data should be printed.
- *
- * Iterate over the tags present in this packet, and
- * invoke the Print method of each tag stored in the packet.
- */
- void PrintByteTags (std::ostream &os) const;
-@end example
-@end smallformat
-
-The Packet API for packet tags is given below.
-@smallformat
-@example
- /**
- * \param tag the tag to store in this packet
- *
- * Add a tag to this packet. This method calls the
- * Tag::GetSerializedSize and, then, Tag::Serialize.
- *
- * Note that this method is const, that is, it does not
- * modify the state of this packet, which is fairly
- * un-intuitive.
- */
- void AddPacketTag (const Tag &tag) const;
- /**
- * \param tag the tag to remove from this packet
- * \returns true if the requested tag is found, false
- * otherwise.
- *
- * Remove a tag from this packet. This method calls
- * Tag::Deserialize if the tag is found.
- */
- bool RemovePacketTag (Tag &tag);
- /**
- * \param tag the tag to search in this packet
- * \returns true if the requested tag is found, false
- * otherwise.
- *
- * Search a matching tag and call Tag::Deserialize if it is found.
- */
- bool PeekPacketTag (Tag &tag) const;
- /**
- * Remove all packet tags.
- */
- void RemoveAllPacketTags (void);
-
- /**
- * \param os the stream in which we want to print data.
- *
- * Print the list of 'packet' tags.
- *
- * \sa Packet::AddPacketTag, Packet::RemovePacketTag, Packet::PeekPacketTag,
- * Packet::RemoveAllPacketTags
- */
- void PrintPacketTags (std::ostream &os) const;
-
- /**
- * \returns an object which can be used to iterate over the list of
- * packet tags.
- */
- PacketTagIterator GetPacketTagIterator (void) const;
-@end example
-@end smallformat
-
-Here is a simple example illustrating the use of tags from the
-code in @code{src/internet-stack/udp-socket-impl.cc}:
-@verbatim
- Ptr<Packet> p; // pointer to a pre-existing packet
- SocketIpTtlTag tag
- tag.SetTtl (m_ipMulticastTtl); // Convey the TTL from UDP layer to IP layer
- p->AddPacketTag (tag);
-@end verbatim
-
-This tag is read at the IP layer, then stripped (@code{src/internet-stack/ipv4-l3-protocol.cc}:
-@verbatim
- uint8_t ttl = m_defaultTtl;
- SocketIpTtlTag tag;
- bool found = packet->RemovePacketTag (tag);
- if (found)
- {
- ttl = tag.GetTtl ();
- }
-@end verbatim
-
-@subsection Fragmentation and concatenation
-
-Packets may be fragmented or merged together. For example, to
-fragment a packet @code{p} of 90 bytes into two packets, one containing
-the first 10 bytes and the other containing the remaining 80, one may call the
-following code:
-@verbatim
- Ptr<Packet> frag0 = p->CreateFragment (0, 10);
- Ptr<Packet> frag1 = p->CreateFragment (10, 90);
-@end verbatim
-
-As discussed above, the packet tags from @code{p} will follow to both
-packet fragments, and the byte tags will follow the byte ranges as needed.
-
-Now, to put them back together:
-@verbatim
- frag0->AddAtEnd (frag1);
-@end verbatim
-Now frag0 should be equivalent to the original packet @code{p}. If,
-however, there were operations on the fragments before being reassembled
-(such as tag operations or header operations), the new packet will not
-be the same.
-
-@subsection Enabling metadata
-
-We mentioned above that packets, being on-the-wire representations of
-byte buffers, present a problem to print out in a structured way
-unless the printing function has access to the context of the header.
-For instance, consider a tcpdump-like printer that wants to pretty-print
-the contents of a packet.
-
-To enable this usage, packets may have metadata enabled (disabled by
-default for performance reasons). This class is used by the Packet
-class to record every operation performed on the packet's buffer, and
-provides an implementation of @code{Packet::Print ()} method that uses
-the metadata to analyze the content of the packet's buffer.
-
-The metadata is also used to perform extensive sanity checks at runtime
-when performing operations on a Packet. For example, this metadata is
-used to verify that when you remove a header from a packet, this
-same header was actually present at the front of the packet. These
-errors will be detected and will abort the program.
-
-To enable this operation, users will typically insert one or both
-of these statements at the beginning of their programs:
-@verbatim
- Packet::EnablePrinting ();
- Packet::EnableChecking ();
-@end verbatim
-
-@section Sample programs
-
-See @code{samples/main-packet.cc} and @code{samples/main-packet-tag.cc}.
-
-@section Implementation details
-
-@subsection Private member variables
-
-A Packet object's interface provides access to some private
-data:
-@verbatim
- Buffer m_buffer;
- ByteTagList m_byteTagList;
- PacketTagList m_packetTagList;
- PacketMetadata m_metadata;
- mutable uint32_t m_refCount;
- static uint32_t m_globalUid;
-@end verbatim
-Each Packet has a Buffer and two Tags lists, a PacketMetadata object,
-and a ref count.
-A static member variable keeps track of the UIDs allocated.
-The actual uid of the packet is stored in the PacketMetadata.
-
-Note
-that real network packets do not have a UID; the UID is therefore an
-instance of data that normally would be stored as a Tag in the packet.
-However, it was felt that a UID is a special case that is so often
-used in simulations that it would be more convenient to store it
-in a member variable.
-
-@subsection Buffer implementation
-
-Class Buffer represents a buffer of bytes. Its size is
-automatically adjusted to hold any data prepended
-or appended by the user. Its implementation is optimized
-to ensure that the number of buffer resizes is minimized,
-by creating new Buffers of the maximum size ever used.
-The correct maximum size is learned at runtime during use by
-recording the maximum size of each packet.
-
-Authors of new Header or Trailer classes need to know the public
-API of the Buffer class. (add summary here)
-
-The byte buffer is implemented as follows:
-@verbatim
- struct BufferData {
- uint32_t m_count;
- uint32_t m_size;
- uint32_t m_initialStart;
- uint32_t m_dirtyStart;
- uint32_t m_dirtySize;
- uint8_t m_data[1];
- };
- struct BufferData *m_data;
- uint32_t m_zeroAreaSize;
- uint32_t m_start;
- uint32_t m_size;
-@end verbatim
-
-@itemize @bullet
-@item @code{BufferData::m_count}: reference count for BufferData structure
-@item @code{BufferData::m_size}: size of data buffer stored in BufferData structure
-@item @code{BufferData::m_initialStart}: offset from start of data buffer where data was first inserted
-@item @code{BufferData::m_dirtyStart}: offset from start of buffer where every Buffer which holds a reference to this BufferData instance have written data so far
-@item @code{BufferData::m_dirtySize}: size of area where data has been written so far
-@item @code{BufferData::m_data}: pointer to data buffer
-@item @code{Buffer::m_zeroAreaSize}: size of zero area which extends before @code{m_initialStart}
-@item @code{Buffer::m_start}: offset from start of buffer to area used by this buffer
-@item @code{Buffer::m_size}: size of area used by this Buffer in its BufferData structure
-@end itemize
-
-@float Figure,fig:buffer
-@caption{Implementation overview of a packet's byte Buffer.}
-@image{figures/buffer,15cm}
-@end float
-
-This data structure is summarized in Figure @ref{fig:buffer}.
-Each Buffer holds a pointer to an instance of a BufferData. Most
-Buffers should be able to share the same underlying BufferData and
-thus simply increase the BufferData's reference count. If they have to
-change the content of a BufferData inside the Dirty Area, and if the
-reference count is not one, they first create a copy of the BufferData and
-then complete their state-changing operation.
-
-@subsection Tags implementation
-
-(XXX revise me)
-
-Tags are implemented by a single pointer which points to the start of a
-linked list ofTagData data structures. Each TagData structure points
-to the next TagData in the list (its next pointer contains zero to
-indicate the end of the linked list). Each TagData contains an integer
-unique id which identifies the type of the tag stored in the TagData.
-@verbatim
-struct TagData {
- struct TagData *m_next;
- uint32_t m_id;
- uint32_t m_count;
- uint8_t m_data[Tags::SIZE];
-};
-class Tags {
- struct TagData *m_next;
-};
-@end verbatim
-
-Adding a tag is a matter of inserting a new TagData at the head of
-the linked list. Looking at a tag requires you to find the relevant
-TagData in the linked list and copy its data into the user data
-structure. Removing a tag and updating the content of a tag
-requires a deep copy of the linked list before performing this operation.
-On the other hand, copying a Packet and its tags is a matter of
-copying the TagData head pointer and incrementing its reference count.
-
-Tags are found by the unique mapping between the Tag type and
-its underlying id. This is why at most one instance of any Tag
-can be stored in a packet. The mapping between Tag type and
-underlying id is performed by a registration as follows:
-@verbatim
-/* A sample Tag implementation
- */
-struct MyTag {
- uint16_t m_streamId;
-};
-@end verbatim
-
-@subsection Memory management
-
-@emph{Describe dataless vs. data-full packets.}
-
-@subsection Copy-on-write semantics
-The current implementation of the byte buffers and tag list is based
-on COW (Copy On Write). An introduction to COW can be found in Scott
-Meyer's "More Effective C++", items 17 and 29). This design feature
-and aspects of the public interface borrows from the packet design
-of the Georgia Tech Network Simulator.
-This implementation of COW uses a customized reference counting
-smart pointer class.
-
-What COW means is that
-copying packets without modifying them is very cheap (in terms of CPU
-and memory usage) and modifying them can be also very cheap. What is
-key for proper COW implementations is being
-able to detect when a given modification of the state of a packet triggers
-a full copy of the data prior to the modification: COW systems need
-to detect when an operation is ``dirty'' and must therefore invoke
-a true copy.
-
-Dirty operations:
-@itemize @bullet
-@item ns3::Packet::AddHeader
-@item ns3::Packet::AddTrailer
-@item both versions of ns3::Packet::AddAtEnd
-@item ns3::Packet::RemovePacketTag
-@end itemize
-
-Non-dirty operations:
-@itemize @bullet
-@item ns3::Packet::AddPacketTag
-@item ns3::Packet::PeekPacketTag
-@item ns3::Packet::RemoveAllPacketTags
-@item ns3::Packet::AddByteTag
-@item ns3::Packet::FindFirstMatchingByteTag
-@item ns3::Packet::RemoveAllByteTags
-@item ns3::Packet::RemoveHeader
-@item ns3::Packet::RemoveTrailer
-@item ns3::Packet::CreateFragment
-@item ns3::Packet::RemoveAtStart
-@item ns3::Packet::RemoveAtEnd
-@item ns3::Packet::CopyData
-@end itemize
-
-Dirty operations will always be slower than non-dirty operations,
-sometimes by several orders of magnitude. However, even the
-dirty operations have been optimized for common use-cases which
-means that most of the time, these operations will not trigger
-data copies and will thus be still very fast.
-
--- a/doc/manual/point-to-point.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,179 +0,0 @@
-@node PointToPoint NetDevice
-@chapter PointToPoint NetDevice
-
-This is the introduction to PointToPoint NetDevice chapter, to complement the
-PointToPoint model doxygen.
-
-@menu
-* Overview of the PointToPoint model::
-* Point-to-Point Channel Model::
-* Using the PointToPointNetDevice::
-* PointToPoint Tracing::
-@end menu
-
-@node Overview of the PointToPoint model
-@section Overview of the PointToPoint model
-
-The ns-3 point-to-point model is of a very simple point to point data link
-connecting exactly two PointToPointNetDevice devices over an
-PointToPointChannel. This can be viewed as equivalent to a full
-duplex RS-232 or RS-422 link with null modem and no handshaking.
-
-Data is encapsulated in the Point-to-Point Protocol (PPP -- RFC 1661),
-however the Link Control Protocol (LCP) and associated state machine is
-not implemented. The PPP link is assumed to be established and
-authenticated at all times.
-
-Data is not framed, therefore Address and Control fields will not be found.
-Since the data is not framed, there is no need to provide Flag Sequence and
-Control Escape octets, nor is a Frame Check Sequence appended. All that is
-required to implement non-framed PPP is to prepend the PPP protocol number
-for IP Version 4 which is the sixteen-bit number 0x21 (see
-http://www.iana.org/assignments/ppp-numbers).
-
-The PointToPointNetDevice provides following Attributes:
-
-@itemize @bullet
-@item Address: The ns3::Mac48Address of the device (if desired);
-@item DataRate: The data rate (ns3::DataRate) of the device;
-@item TxQueue: The transmit queue (ns3::Queue) used by the device;
-@item InterframeGap: The optional ns3::Time to wait between "frames";
-@item Rx: A trace source for received packets;
-@item Drop: A trace source for dropped packets.
-@end itemize
-
-The PointToPointNetDevice models a transmitter section that puts bits
-on a corresponding channel "wire." `The DataRate attribute specifies the
-number of bits per second that the device will simulate sending over the
-channel. In reality no bits are sent, but an event is scheduled for an
-elapsed time consistent with the number of bits in each packet and the
-specified DataRate. The implication here is that the receiving device
-models a receiver section that can receive any any data rate. Therefore
-there is no need, nor way to set a receive data rate in this model. By
-setting the DataRate on the transmitter of both devices connected to a
-given PointToPointChannel one can model a symmetric channel; or by
-setting different DataRates one can model an asymmetric channel (e.g.,
-ADSL).
-
-The PointToPointNetDevice supports the assignment of a "receive error
-model." This is an ErrorModel object that is used to simulate data
-corruption on the link.
-
-@node Point-to-Point Channel Model
-@section Point-to-Point Channel Model
-
-The point to point net devices are connected via an
-PointToPointChannel. This channel models two wires transmitting bits
-at the data rate specified by the source net device. There is no overhead
-beyond the eight bits per byte of the packet sent. That is, we do not
-model Flag Sequences, Frame Check Sequences nor do we "escape" any data.
-
-The PointToPointChannel provides following Attributes:
-
-@itemize @bullet
-@item Delay: An ns3::Time specifying the speed of light transmission delay for
-the channel.
-@end itemize
-
-@node Using the PointToPointNetDevice
-@section Using the PointToPointNetDevice
-
-The PointToPoint net devices and channels are typically created and configured using
-the associated @code{PointToPointHelper} object. The various ns3 device helpers
-generally work in a similar way, and their use is seen in many of our example
-programs and is also covered in the ns-3 tutorial.
-
-The conceptual model of interest is that of a bare computer ``husk'' into which
-you plug net devices. The bare computers are created using a @code{NodeContainer}
-helper. You just ask this helper to create as many computers (we call them
-@code{Nodes}) as you need on your network:
-
-@verbatim
- NodeContainer nodes;
- nodes.Create (2);
-@end verbatim
-
-Once you have your nodes, you need to instantiate a @code{PointToPointHelper} and set
-any attributes you may want to change. Note that since this is a point-to-point
-(as compared to a point-to-multipoint) there may only be two nodes with associated
-net devices connected by a PointToPointChannel.
-
-@verbatim
-
- PointToPointHelper pointToPoint;
- pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
- pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));
-@end verbatim
-
-Once the attributes are set, all that remains is to create the devices
-and install them on the required nodes, and to connect the devices
-together using a PointToPoint channel. When we create the net devices, we add
-them to a container to allow you to use them in the future. This all
-takes just one line of code.
-
-@verbatim
- NetDeviceContainer devices = pointToPoint.Install (nodes);
-@end verbatim
-
-@node PointToPoint Tracing
-@section PointToPoint Tracing
-
-Like all ns-3 devices, the Point-to-Point Model provides a number of trace
-sources. These trace sources can be hooked using your own custom trace code,
-or you can use our helper functions to arrange for tracing to be enabled on
-devices you specify.
-
-@subsection Upper-Level (MAC) Hooks
-
-From the point of view of tracing in the net device, there are several
-interesting points to insert trace hooks. A convention inherited from other
-simulators is that packets destined for transmission onto attached networks
-pass through a single "transmit queue" in the net device. We provide trace
-hooks at this point in packet flow, which corresponds (abstractly) only to a
-transition from the network to data link layer, and call them collectively
-the device MAC hooks.
-
-When a packet is sent to the Point-to-Point net device for transmission it
-always passes through the transmit queue. The transmit queue in the
-PointToPointNetDevice inherits from Queue, and therefore inherits three
-trace sources:
-
-@itemize @bullet
-@item An Enqueue operation source (see ns3::Queue::m_traceEnqueue);
-@item A Dequeue operation source (see ns3::Queue::m_traceDequeue);
-@item A Drop operation source (see ns3::Queue::m_traceDrop).
-@end itemize
-
-The upper-level (MAC) trace hooks for the PointToPointNetDevice are, in fact,
-exactly these three trace sources on the single transmit queue of the device.
-
-The m_traceEnqueue event is triggered when a packet is placed on the transmit
-queue. This happens at the time that ns3::PointtoPointNetDevice::Send or
-ns3::PointToPointNetDevice::SendFrom is called by a higher layer to queue a
-packet for transmission. An Enqueue trace event firing should be interpreted
-as only indicating that a higher level protocol has sent a packet to the device.
-
-The m_traceDequeue event is triggered when a packet is removed from the
-transmit queue. Dequeues from the transmit queue can happen in two
-situations: 1) If the underlying channel is idle when
-PointToPointNetDevice::Send is called, a packet is dequeued from the transmit
-queue and immediately transmitted; 2) a packet may be dequeued and
-immediately transmitted in an internal TransmitCompleteEvent that functions
-much like a transmit complete interrupt service routine. An Dequeue trace
-event firing may be viewed as indicating that the PointToPointNetDevice has
-begun transmitting a packet.
-
-@subsection Lower-Level (PHY) Hooks
-
-Similar to the upper level trace hooks, there are trace hooks available at
-the lower levels of the net device. We call these the PHY hooks. These
-events fire from the device methods that talk directly to the
-PointToPointChannel.
-
-The trace source m_dropTrace is called to indicate a packet that is dropped
-by the device. This happens when a packet is discarded as corrupt due to a
-receive error model indication (see ns3::ErrorModel and the associated
-attribute "ReceiveErrorModel").
-
-The other low-level trace source fires on reception of a packet (see
-ns3::PointToPointNetDevice::m_rxTrace) from the PointToPointChannel.
--- a/doc/manual/python.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-@node Python
-@chapter Python
-
-@cartouche
-Placeholder chapter
-@end cartouche
-
-For now, please see the Python wiki page at @*
-@uref{http://www.nsnam.org/wiki/index.php/NS-3_Python_Bindings,,http://www.nsnam.org/wiki/index.php/NS-3_Python_Bindings}.
--- a/doc/manual/random.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,326 +0,0 @@
-@anchor{chap:rv}
-@node Random variables
-@chapter Random variables
-
-@menu
-* Quick Overview::
-* Background::
-* Seeding and independent replications::
-* class RandomVariable::
-* Base class public API::
-* Types of RandomVariables::
-* Semantics of RandomVariable objects::
-* Using other PRNG::
-* More advanced usage::
-* Publishing your results::
-* Summary::
-@end menu
-
-ns-3 contains a built-in pseudo-random number generator (PRNG).
-It is important for serious users of the simulator to understand
-the functionality, configuration, and usage of this PRNG, and
-to decide whether it is sufficient for his or her research use.
-
-@node Quick Overview
-@section Quick Overview
-
-ns-3 random numbers are provided via instances of @code{class RandomVariable}.
-@itemize @bullet
-@item @strong{by default, ns-3 simulations use a fixed seed}; if there is any
-randomness in the simulation, each run of the program will yield identical
-results unless the seed and/or run number is changed.
-@itemize @bullet
-@item @strong{in ns-3.3 and earlier, ns-3 simulations used a random seed by
-default; this marks a change in policy starting with ns-3.4}
-@end itemize
-@item to obtain randomness across multiple simulation runs, you must either
-set the seed differently or set the run number differently. To set a seed, call
-@code{SeedManager::SetSeed (uint32_t)} at the beginning of the program;
-to set a run number with the same seed, call
-@code{SeedManager::SetRun (uint32_t)} at the beginning of the program;
-@xref{Seeding and independent replications}
-@item each RandomVariable used in ns-3 has a virtual random number
-generator associated with it; all random variables use either a fixed
-or random seed based on the use of the global seed (previous bullet);
-@item if you intend to perform multiple runs of the same scenario, with
-different random numbers, please be sure to read the section on how to
-perform independent replications: @xref{Seeding and independent replications}.
-@end itemize
-
-Read further for more explanation about the random number facility for
-ns-3.
-
-@node Background
-@section Background
-
-Simulations use a lot of random numbers; one study
-found that most network simulations spend as much as 50%
-of the CPU generating random numbers. Simulation users need
-to be concerned with the quality of the (pseudo) random numbers and
-the independence between different streams of random numbers.
-
-Users need to be concerned with a few issues, such as:
-@itemize @bullet
-@item the seeding of the random number generator and whether a
-simulation outcome is deterministic or not,
-@item how to acquire different streams of random numbers that are
-independent from one another, and
-@item how long it takes for streams to cycle
-@end itemize
-
-We will introduce a few terms here: a RNG provides a long sequence
-of (pseudo) random numbers.
-The length of this sequence is called the @emph{cycle length}
-or @emph{period}, after which the RNG will repeat itself.
-This sequence can
-be partitioned into disjoint @emph{streams}. A stream of a
-RNG is a contiguous subset or block of the RNG sequence.
-For instance, if the
-RNG period is of length N, and two streams are provided from this
-RNG, then
-the first stream might use the first N/2 values and the second
-stream might produce the second N/2 values. An important property
-here is that the two streams are uncorrelated. Likewise, each
-stream can be partitioned disjointedly to a number of
-uncorrelated @emph{substreams}. The underlying RNG hopefully
-produces a pseudo-random sequence of numbers with a very long
-cycle length, and partitions this into streams and substreams in an
-efficient manner.
-
-ns-3 uses the same underlying random number generator as does
-ns-2: the MRG32k3a generator from Pierre L'Ecuyer. A
-detailed description can be found in
-@uref{http://www.iro.umontreal.ca/~lecuyer/myftp/papers/streams00.pdf,,}.
-The MRG32k3a generator provides 1.8x10^19 independent
-streams of random numbers, each of which consists of
-2.3x10^15 substreams. Each substream has a period
-(@emph{i.e.}, the number of random numbers before overlap) of
-7.6x10^22. The period of the entire generator is
-3.1x10^57.
-
-Class @code{ns3::RandomVariable} is the public interface to this
-underlying random number generator. When users create new
-RandomVariables (such as UniformVariable, ExponentialVariable,
-etc.), they create an object that uses one of the distinct, independent
-streams of the random number generator. Therefore, each
-object of type RandomVariable has, conceptually, its own "virtual" RNG.
-Furthermore, each RandomVariable can be configured to use
-one of the set of substreams drawn from the main stream.
-
-An alternate implementation would be to allow each RandomVariable
-to have its own (differently seeded) RNG. However, we cannot
-guarantee as strongly that the different sequences would be
-uncorrelated in such a case; hence, we prefer to use a single RNG
-and streams and substreams from it.
-
-@anchor{chap:rv:indeprep}
-@node Seeding and independent replications
-@section Seeding and independent replications
-
-ns-3 simulations can be configured to produce deterministic or
-random results. If the ns-3 simulation is configured to use
-a fixed, deterministic seed with the same run number, it should give
-the same output each time it is run.
-
-By default, ns-3 simulations use a fixed seed and run number.
-These values are stored in two @code{ns3::GlobalValue} instances:
-@code{g_rngSeed} and @code{g_rngRun}.
-
-A typical use case is to run a simulation as a sequence of independent
-trials, so as to compute statistics on a large number of independent
-runs. The user can either change the global seed and rerun the
-simulation, or can advance the substream state of the RNG, which is
-referred to as incrementing the run number.
-
-A class @code{ns3::SeedManager ()} provides an API to control
-the seeding and run number behavior.
-This seeding and substream state setting must be called before any
-random variables are created; e.g.
-
-@verbatim
- SeedManager::SetSeed (3); // Changes seed from default of 1 to 3
- SeedManager::SetRun (7); // Changes run number from default of 1 to 7
- // Now, create random variables
- UniformVariable x(0,10);
- ExponentialVariable y(2902);
- ...
-@end verbatim
-
-Which is better, setting a new seed or advancing the substream state?
-There is no guarantee that the streams
-produced by two random seeds will not overlap. The only way to
-guarantee that two streams do not overlap is to use the substream
-capability provided by the RNG implementation.
-@strong{Therefore, use the substream capability to produce
-multiple independent runs of the same simulation.}
-In other words, the more statistically rigorous way to configure
-multiple independent replications is to use a fixed seed and to
-advance the run number. This implementation allows for a maximum of
-2.3x10^15 independent replications using the substreams.
-
-For ease of use, it is not necessary to control the seed and run number
-from within the program; the user can set the
-@code{NS_GLOBAL_VALUE} environment variable as follows:
-@verbatim
- NS_GLOBAL_VALUE="RngRun=3" ./waf --run program-name
-@end verbatim
-
-Another way to control this is by passing a command-line argument; since
-this is an ns-3 GlobalValue instance, it is equivalently done such as follows:
-@verbatim
- ./waf --command-template="%s --RngRun=3" --run program-name
-@end verbatim
-or, if you are running programs directly outside of waf:
-@verbatim
- ./build/optimized/scratch/program-name --RngRun=3
-@end verbatim
-The above command-line variants make it easy to run lots of different
-runs from a shell script by just passing a different RngRun index.
-
-@node class RandomVariable
-@section class RandomVariable
-
-All random variables should derive from @code{class RandomVariable}.
-This base class provides a few static methods for globally configuring
-the behavior of the random number generator. Derived classes
-provide API for drawing random variates from the particular
-distribution being supported.
-
-Each RandomVariable created in the simulation is given a generator
-that is a new RNGStream from the underlying PRNG.
-Used in this manner, the L'Ecuyer implementation allows for a maximum of
-1.8x10^19 random variables. Each random variable in
-a single replication can produce up to 7.6x10^22 random
-numbers before overlapping.
-
-@node Base class public API
-@section Base class public API
-
-Below are excerpted a few public methods of @code{class RandomVariable}
-that access the next value in the substream.
-@smallformat
-@example
- /**
- * \brief Returns a random double from the underlying distribution
- * \return A floating point random value
- */
- double GetValue (void) const;
-
- /**
- * \brief Returns a random integer integer from the underlying distribution
- * \return Integer cast of ::GetValue()
- */
- uint32_t GetInteger (void) const;
-@end example
-@end smallformat
-
-We have already described the seeding configuration above. Different
-RandomVariable subclasses may have additional API.
-
-@node Types of RandomVariables
-@section Types of RandomVariables
-
-The following types of random variables are provided, and are documented
-in the ns-3 Doxygen or by reading @code{src/core/random-variable.h}. Users
-can also create their own custom random variables by deriving from
-class RandomVariable.
-@itemize @bullet
-@item @code{class UniformVariable }
-@item @code{class ConstantVariable }
-@item @code{class SequentialVariable }
-@item @code{class ExponentialVariable }
-@item @code{class ParetoVariable }
-@item @code{class WeibullVariable }
-@item @code{class NormalVariable }
-@item @code{class EmpiricalVariable }
-@item @code{class IntEmpiricalVariable }
-@item @code{class DeterministicVariable }
-@item @code{class LogNormalVariable }
-@item @code{class TriangularVariable }
-@item @code{class GammaVariable }
-@item @code{class ErlangVariable }
-@item @code{class ZipfVariable }
-@end itemize
-
-@node Semantics of RandomVariable objects
-@section Semantics of RandomVariable objects
-
-RandomVariable objects have value semantics. This means that they
-can be passed by value to functions. The can also be passed by
-reference to const. RandomVariables do not derive from
-@code{ns3::Object} and we do not use smart pointers to manage them;
-they are either allocated on the stack or else users explicitly manage
-any heap-allocated RandomVariables.
-
-RandomVariable objects can also be used in ns-3 attributes, which means
-that values can be set for them through the ns-3 attribute system.
-An example is in the propagation models for WifiNetDevice:
-@smallformat
-@example
-TypeId
-RandomPropagationDelayModel::GetTypeId (void)
-@{
- static TypeId tid = TypeId ("ns3::RandomPropagationDelayModel")
- .SetParent<PropagationDelayModel> ()
- .AddConstructor<RandomPropagationDelayModel> ()
- .AddAttribute ("Variable",
- "The random variable which generates random delays (s).",
- RandomVariableValue (UniformVariable (0.0, 1.0)),
- MakeRandomVariableAccessor (&RandomPropagationDelayModel::m_variable),
- MakeRandomVariableChecker ())
- ;
- return tid;
-@}
-@end example
-@end smallformat
-Here, the ns-3 user can change the default random variable for this
-delay model (which is a UniformVariable ranging from 0 to 1) through
-the attribute system.
-
-@node Using other PRNG
-@section Using other PRNG
-
-There is presently no support for substituting a different underlying
-random number generator (e.g., the GNU Scientific Library or the Akaroa
-package). Patches are welcome.
-
-@node More advanced usage
-@section More advanced usage
-
-@emph{To be completed}
-
-@node Publishing your results
-@section Publishing your results
-
-When you publish simulation results, a key piece of configuration
-information that you should always state is how you used the
-the random number generator.
-@itemize @bullet
-@item what seeds you used,
-@item what RNG you used if not the default,
-@item how were independent runs performed,
-@item for large simulations, how did you check that you did not cycle.
-@end itemize
-
-It is incumbent on the researcher publishing results to include enough
-information to allow others to reproduce his or her results. It is
-also incumbent on the researcher to convince oneself that the random
-numbers used were statistically valid, and to state in the paper why
-such confidence is assumed.
-
-@node Summary
-@section Summary
-
-Let's review what things you should do when creating a simulation.
-
-@itemize @bullet
-@item Decide whether you are running with a fixed seed or random seed;
-a fixed seed is the default,
-@item Decide how you are going to manage independent replications, if
-applicable,
-@item Convince yourself that you are not drawing more random values
-than the cycle length, if you are running a very long simulation, and
-@item When you publish, follow the guidelines above about documenting your
-use of the random number generator.
-@end itemize
-
--- a/doc/manual/realtime.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,100 +0,0 @@
-@node RealTime
-@chapter Real-Time Scheduler
-@anchor{chap:RealTime}
-
-ns-3 has been designed for integration into testbed and virtual machine
-environments. To integrate with real network stacks and emit/consume
-packets, a real-time scheduler is needed to try to lock the simulation
-clock with the hardware clock. We describe here a component of this:
-the RealTime scheduler.
-
-The purpose of the realtime scheduler is to cause the progression of
-the simulation clock to occur synchronously with respect to some
-external time base. Without the presence of an external time base
-(wall clock), simulation time jumps instantly from one simulated time to
-the next.
-
-@section Behavior
-
-When using a non-realtime scheduler (the default in ns-3), the simulator
-advances the simulation time to the next scheduled event. During event
-execution, simulation time is frozen. With the realtime scheduler, the
-behavior is similar from the perspective of simulation models (i.e.,
-simulation time is frozen during event execution), but between events,
-the simulator will attempt to keep the simulation clock aligned with
-the machine clock.
-
-When an event is finished executing, and the scheduler moves to the next
-event, the scheduler compares the next event execution time with the
-machine clock. If the next event is scheduled for a future time,
-the simulator sleeps until that realtime is reached and then executes
-the next event.
-
-It may happen that, due to the processing inherent in the execution
-of simulation events, that the simulator cannot keep up with realtime.
-In such a case, it is up to the user configuration what to do. There
-are two ns-3 attributes that govern the behavior. The first is
-@code{ns3::RealTimeSimulatorImpl::SynchronizationMode}. The two
-entries possible for this attribute are @code{BestEffort} (the default)
-or @code{HardLimit}. In "BestEffort" mode, the simulator will just
-try to catch up to realtime by executing events until it reaches
-a point where the next event is in the (realtime) future, or else
-the simulation ends. In BestEffort mode, then, it is possible for
-the simulation to consume more time than the wall clock time. The
-other option "HardLimit" will cause the simulation to abort if the tolerance
-threshold is exceeded. This attribute is
-@code{ns3::RealTimeSimulatorImpl::HardLimit} and the default is 0.1 seconds.
-
-A different mode of operation is one in which simulated time is @strong{not}
-frozen during an event execution. This mode of realtime simulation was
-implemented but removed from the ns-3 tree because of questions of whether
-it would be useful. If users are interested in a realtime simulator
-for which simulation time does not freeze during event execution (i.e.,
-every call to @code{Simulator::Now()} returns the current wall clock time,
-not the time at which the event started executing), please contact the
-ns-developers mailing list.
-
-@section Usage
-
-The usage of the realtime simulator is straightforward, from a scripting
-perspective. Users just need to set the attribute
-@code{SimulatorImplementationType} to the Realtime simulator, such as follows:
-@verbatim
- GlobalValue::Bind ("SimulatorImplementationType",
- StringValue ("ns3::RealtimeSimulatorImpl"));
-@end verbatim
-
-There is a script in @code{examples/realtime-udp-echo.cc} that has an
-example of how to configure the realtime behavior. Try:
-@verbatim
-./waf --run realtime-udp-echo
-@end verbatim
-
-Whether the simulator will work in a best effort or hard limit policy
-fashion is governed by the attributes explained in the previous section.
-
-@section Implementation
-
-The implementation is contained in the following files:
-@itemize @bullet
-@item @code{src/simulator/realtime-simulator-impl.@{cc,h@}}
-@item @code{src/simulator/wall-clock-synchronizer.@{cc,h@}}
-@end itemize
-
-In order to create a realtime scheduler, to a first approximation you
-just want to cause simulation time jumps to consume real time. We propose
-doing this using a combination of sleep- and busy- waits. Sleep-waits cause
-the calling process (thread) to yield the processor for some amount of time.
-Even though this specified amount of time can be passed to nanosecond
-resolution, it is actually converted to an OS-specific granularity.
-In Linux, the granularity is called a Jiffy. Typically this resolution is
-insufficient for our needs (on the order of a ten milliseconds), so we
-round down and sleep for some smaller number of Jiffies. The process is
-then awakened after the specified number of Jiffies has passed. At this
-time, we have some residual time to wait. This time is generally smaller
-than the minimum sleep time, so we busy-wait for the remainder of the time.
-This means that the thread just sits in a for loop consuming cycles until
-the desired time arrives. After the combination of sleep- and busy-waits,
-the elapsed realtime (wall) clock should agree with the simulation time
-of the next event and the simulation proceeds.
-
--- a/doc/manual/routing.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,422 +0,0 @@
-@node Routing overview
-@chapter Routing overview
-
-@menu
-* Routing architecture::
-* Global centralized routing::
-* Unicast routing::
-* Multicast routing::
-@end menu
-
-ns-3 is intended to support traditional routing approaches and protocols,
-support ports of open source routing implementations, and facilitate research
-into unorthodox routing techniques. The overall routing architecture
-is described below in @ref{Routing architecture}. Users who wish to
-just read about how to configure global routing for wired topologies
-can read @ref{Global centralized routing}. Unicast routing protocols
-are described in @ref{Unicast routing}. Multicast routing is documented in
-@ref{Multicast routing}.
-
-@node Routing architecture
-@section Routing architecture
-
-@float Figure,fig:routing
-@caption{Overview of routing}
-@image{figures/routing, 6in}
-@end float
-
-@ref{fig:routing} shows the overall routing architecture for Ipv4. The key objects
-are Ipv4L3Protocol, Ipv4RoutingProtocol(s) (a class to which all
-routing/forwarding has been delegated from Ipv4L3Protocol), and Ipv4Route(s).
-
-Ipv4L3Protocol must have at least one Ipv4RoutingProtocol added to
-it at simulation setup time. This is done explicitly by calling
-Ipv4::SetRoutingProtocol ().
-
-The abstract base class Ipv4RoutingProtocol () declares a minimal interface,
-consisting of two methods: RouteOutput () and RouteInput ().
-For packets traveling outbound from a host, the transport protocol will query
-Ipv4 for the Ipv4RoutingProtocol object interface, and will request
-a route via Ipv4RoutingProtocol::RouteOutput ().
-A Ptr to Ipv4Route object is returned. This is analagous to a
-dst_cache entry in Linux. The Ipv4Route is carried down to the
-Ipv4L3Protocol to avoid a second lookup there. However, some
-cases (e.g. Ipv4 raw sockets) will require a call to RouteOutput()
-directly from Ipv4L3Protocol.
-
-For packets received inbound for forwarding or delivery,
-the following steps occur. Ipv4L3Protocol::Receive() calls
-Ipv4RoutingProtocol::RouteInput().
-This passes the packet ownership to the Ipv4RoutingProtocol object. There
-are four callbacks associated with this call:
-@itemize @bullet
-@item LocalDeliver
-@item UnicastForward
-@item MulticastForward
-@item Error
-@end itemize
-The Ipv4RoutingProtocol must eventually call one of these callbacks for each
-packet that it takes responsibility for. This is basically
-how the input routing process works in Linux.
-
-@float Figure,fig:routing-specialization
-@caption{Ipv4Routing specialization}
-@image{figures/routing-specialization, 5in}
-@end float
-
-This overall architecture is designed to support different routing
-approaches, including (in the future) a Linux-like policy-based routing
-implementation, proactive and on-demand routing protocols, and simple
-routing protocols for when the simulation user does not really care
-about routing.
-
-@ref{fig:routing-specialization} illustrates how multiple routing protocols
-derive from this base class. A class Ipv4ListRouting
-(implementation class Ipv4ListRoutingImpl) provides the existing
-list routing approach in ns-3. Its API is the same as base class
-Ipv4Routing except for the ability to add multiple prioritized routing
-protocols
-(Ipv4ListRouting::AddRoutingProtocol(), Ipv4ListRouting::GetRoutingProtocol()).
-
-The details of these routing protocols are described below in
-@ref{Unicast routing}. For now, we will first start with a basic
-unicast routing capability that is intended to globally build routing
-tables at simulation time t=0 for simulation users who do not care
-about dynamic routing.
-
-@node Global centralized routing
-@section Global centralized routing
-
-Global centralized routing is sometimes called ''God'' routing; it
-is a special implementation that walks the simulation topology and
-runs a shortest path algorithm, and populates each node's routing
-tables. No actual protocol overhead (on the simulated links) is incurred
-with this approach. It does have a few constraints:
-
-@itemize @bullet
-@item @strong{Wired only:} It is not intended for use in wireless networks.
-@item @strong{Unicast only:} It does not do multicast.
-@item @strong{Scalability:} Some users of this on large topologies
-(e.g. 1000 nodes)
-have noticed that the current implementation is not very scalable.
-The global centralized routing will be modified in the future to
-reduce computations and runtime performance.
-@end itemize
-
-Presently, global centralized IPv4 unicast routing over both
-point-to-point and shared (CSMA) links is supported.
-
-By default, when using the ns-3 helper API and the default InternetStackHelper,
-global routing capability will be added to the node, and global routing
-will be inserted as a routing protocol with lower priority than the
-static routes (i.e., users can insert routes via Ipv4StaticRouting API
-and they will take precedence over routes found by global routing).
-
-@subsection Global Unicast Routing API
-
-The public API is very minimal. User scripts include the following:
-@verbatim
-#include "ns3/helper-module.h"
-@end verbatim
-
-If the default InternetStackHelper is used, then an instance of
-global routing will be aggregated to each node.
-After IP addresses are configured, the following function call will
-cause all of the nodes that have an Ipv4 interface to receive
-forwarding tables entered automatically by the GlobalRouteManager:
-@verbatim
- Ipv4GlobalRoutingHelper::PopulateRoutingTables ();
-@end verbatim
-
-@emph{Note:} A reminder that the wifi NetDevice will work but does not
-take any wireless effects into account. For wireless, we recommend
-OLSR dynamic routing described below.
-
-It is possible to call this function again in the midst of a simulation
-using the following additional public function:
-@verbatim
- Ipv4GlobalRoutingHelper::RecomputeRoutingTables ();
-@end verbatim
-which flushes the old tables, queries the nodes for new interface information,
-and rebuilds the routes.
-
-For instance, this scheduling call will cause the tables to be rebuilt
-at time 5 seconds:
-@verbatim
- Simulator::Schedule (Seconds (5),
- &Ipv4GlobalRoutingHelper::RecomputeRoutingTables);
-@end verbatim
-
-There are two attributes that govern the behavior. The first is
-Ipv4GlobalRouting::RandomEcmpRouting. If set to true, packets are randomly
-routed across equal-cost multipath routes. If set to false (default),
-only one route is consistently used. The second is
-Ipv4GlobalRouting::RespondToInterfaceEvents. If set to true, dynamically
-recompute the global routes upon Interface notification events (up/down,
-or add/remove address). If set to false (default), routing may break
-unless the user manually calls RecomputeRoutingTables() after such events.
-The default is set to false to preserve legacy ns-3 program behavior.
-
-@subsection Global Routing Implementation
-
-This section is for those readers who care about how this is implemented.
-A singleton object (GlobalRouteManager) is responsible for populating
-the static routes on each node, using the public Ipv4 API of that node.
-It queries each node in the topology for a "globalRouter" interface.
-If found, it uses the API of that interface to obtain a "link state
-advertisement (LSA)" for the router. Link State Advertisements
-are used in OSPF routing, and we follow their formatting.
-
-The GlobalRouteManager populates a link state database with LSAs
-gathered from the entire topology. Then, for each router in the topology,
-the GlobalRouteManager executes the OSPF shortest path first (SPF)
-computation on the database, and populates the routing tables on each
-node.
-
-The quagga (http://www.quagga.net) OSPF implementation was used as the
-basis for the routing computation logic.
-One benefit of following an existing OSPF SPF implementation is that
-OSPF already has defined link state advertisements for all common
-types of network links:
-@itemize @bullet
-@item point-to-point (serial links)
-@item point-to-multipoint (Frame Relay, ad hoc wireless)
-@item non-broadcast multiple access (ATM)
-@item broadcast (Ethernet)
-@end itemize
-Therefore, we think that enabling these other link types will be more
-straightforward now that the underlying OSPF SPF framework is in place.
-
-Presently, we can handle IPv4 point-to-point, numbered links, as well
-as shared broadcast (CSMA) links, and we do not do equal-cost multipath.
-
-Typically, an Ipv4GlobalRoutingHelper class is used to create global
-routes. The InternetStackHelper, by default, will cause the below
-helper code to be called to aggregate a GlobalRouter
-object to each node.
-@verbatim
-Ptr<Ipv4RoutingProtocol>
-Ipv4GlobalRoutingHelper::Create (Ptr<Node> node) const
-{
- NS_LOG_LOGIC ("Adding GlobalRouter interface to node " <<
- node->GetId ());
-
- Ptr<GlobalRouter> globalRouter = CreateObject<GlobalRouter> ();
- node->AggregateObject (globalRouter);
-
- NS_LOG_LOGIC ("Adding GlobalRouting Protocol to node " << node->GetId ());
- Ptr<Ipv4GlobalRouting> globalRouting = CreateObject<Ipv4GlobalRouting> ();
- globalRouter->SetRoutingProtocol (globalRouting);
-
- return globalRouting;
-}
-@end verbatim
-
-This object interface is later queried and used to generate a Link State
-Advertisement for each router, and this link state database is
-fed into the OSPF shortest path computation logic. The Ipv4 API
-is finally used to populate the routes themselves.
-
-@node Unicast routing
-@section Unicast routing
-
-There are presently five unicast routing protocols defined for IPv4 and
-two for IPv6:
-@itemize @bullet
-@item class Ipv4StaticRouting (covering both unicast and multicast)
-@item IPv4 Optimized Link State Routing (a MANET protocol defined in
-@uref{http://www.ietf.org/rfc/rfc3626.txt,,RFC 3626})
-@item class Ipv4ListRouting (used to store a prioritized list of routing
-protocols)
-@item class Ipv4GlobalRouting (used to store routes computed by the global
-route manager, if that is used)
-@item class Ipv4NixVectorRouting (a more efficient version of global routing
-that stores source routes in a packet header field)
-@item class Ipv6ListRouting (used to store a prioritized list of routing
-protocols)
-@item class Ipv6StaticRouting
-@end itemize
-
-In the future, this architecture should also allow someone to implement
-a Linux-like implementation with routing cache, or a Click modular
-router, but those are out of scope for now.
-
-@subsection Ipv4ListRouting
-
-This section describes the current default ns-3 Ipv4RoutingProtocol.
-Typically, multiple routing protocols are supported in user space and
-coordinate to write a single forwarding table in the kernel. Presently
-in @command{ns-3}, the implementation instead allows for multiple routing
-protocols to build/keep their own routing state, and the IPv4 implementation
-will query each one of these routing protocols (in some order determined
-by the simulation author) until a route is found.
-
-We chose this approach because it may better
-facilitate the integration of disparate routing approaches that may
-be difficult to coordinate the writing to a single table, approaches
-where more information than destination IP address (e.g., source
-routing) is used to determine the next hop, and on-demand
-routing approaches where packets must be cached.
-
-@subsubsection Ipv4ListRouting::AddRoutingProtocol
-
-Class Ipv4ListRouting provides a pure virtual function declaration for the
-method that allows one to add a routing protocol:
-@verbatim
- void AddRoutingProtocol (Ptr<Ipv4RoutingProtocol> routingProtocol,
- int16_t priority);
-@end verbatim
-This method is implemented by class Ipv4ListRoutingImpl in the internet-stack
-module.
-
-The priority variable above governs the priority in which the routing
-protocols are inserted. Notice that it is a signed int.
-By default in ns-3, the helper classes will instantiate a Ipv4ListRoutingImpl
-object, and add to it an Ipv4StaticRoutingImpl object at priority zero.
-Internally, a list of Ipv4RoutingProtocols is stored, and
-and the routing protocols are each consulted in decreasing order
-of priority to see whether a match is found. Therefore, if you
-want your Ipv4RoutingProtocol to have priority lower than the static
-routing, insert it with priority less than 0; e.g.:
-@verbatim
- Ptr<MyRoutingProtocol> myRoutingProto = CreateObject<MyRoutingProtocol> ();
- listRoutingPtr->AddRoutingProtocol (myRoutingProto, -10);
-@end verbatim
-
-Upon calls to RouteOutput() or RouteInput(), the list routing object will
-search the list of routing protocols, in priority order, until a route
-is found. Such routing protocol will invoke the appropriate callback
-and no further routing protocols will be searched.
-
-@subsection Optimized Link State Routing (OLSR)
-
-This IPv4 routing protocol was originally ported from the OLSR-UM
-implementation for ns-2. The implementation
-is found in the src/routing/olsr directory, and an example script is in
-examples/simple-point-to-point-olsr.cc.
-
-Typically, OLSR is enabled in a main program by use of an OlsrHelper class
-that installs OLSR into an Ipv4ListRoutingProtocol object.
-The following sample commands will enable OLSR in a simulation using
-this helper class along with some other routing helper objects.
-The setting of priority value 10, ahead of
-the staticRouting priority of 0, means that OLSR will be consulted for
-a route before the node's static routing table.
-
-@verbatim
- NodeContainer c:
- ...
- // Enable OLSR
- NS_LOG_INFO ("Enabling OLSR Routing.");
- OlsrHelper olsr;
-
- Ipv4StaticRoutingHelper staticRouting;
-
- Ipv4ListRoutingHelper list;
- list.Add (staticRouting, 0);
- list.Add (olsr, 10);
-
- InternetStackHelper internet;
- internet.SetRoutingHelper (list);
- internet.Install (c);
-@end verbatim
-
-Once installed,the OLSR "main interface" can be set with the
-SetMainInterface() command. If the user does not specify a main address,
-the protocol will select the first primary IP address that it finds, starting
-first the loopback interface and then the next non-loopback interface
-found, in order of Ipv4 interface index. The loopback address of 127.0.0.1
-is not selected. In addition, a number of protocol constants are defined in
-olsr-routing-protocol.cc.
-
-Olsr is started at time zero of the simulation, based on a call to
-Object::Start() that eventually calls OlsrRoutingProtocol::DoStart().
-Note: a patch to allow the user to start and stop the protocol at other
-times would be welcome.
-
-Presently, OLSR is limited to use with an Ipv4ListRouting object, and
-does not respond to dynamic changes to a device's IP address or link up/down
-notifications; i.e. the topology changes are due to loss/gain of connectivity
-over a wireless channel.
-
-@node Multicast routing
-@section Multicast routing
-
-The following function is used to add a static multicast route
-to a node:
-@verbatim
-void
-Ipv4StaticRouting::AddMulticastRoute (Ipv4Address origin,
- Ipv4Address group,
- uint32_t inputInterface,
- std::vector<uint32_t> outputInterfaces);
-@end verbatim
-
-A multicast route must specify an origin IP address, a multicast group and
-an input network interface index as conditions and provide a vector of
-output network interface indices over which packets matching the conditions
-are sent.
-
-Typically there are two main types of multicast routes: routes of the
-first kind are used during forwarding. All of the conditions must be
-explicitly provided. The second kind of routes are used to get packets off
-of a local node. The difference is in the input interface. Routes for
-forwarding will always have an explicit input interface specified. Routes
-off of a node will always set the input interface to a wildcard specified
-by the index Ipv4RoutingProtocol::IF\_INDEX\_ANY.
-
-For routes off of a local node wildcards may be used in the origin and
-multicast group addresses. The wildcard used for Ipv4Adresses is that
-address returned by Ipv4Address::GetAny () -- typically "0.0.0.0". Usage
-of a wildcard allows one to specify default behavior to varying degrees.
-
-For example, making the origin address a wildcard, but leaving the
-multicast group specific allows one (in the case of a node with multiple
-interfaces) to create different routes using different output interfaces
-for each multicast group.
-
-If the origin and multicast addresses are made wildcards, you have created
-essentially a default multicast address that can forward to multiple
-interfaces. Compare this to the actual default multicast address that is
-limited to specifying a single output interface for compatibility with
-existing functionality in other systems.
-
-Another command sets the default multicast route:
-@verbatim
-void
-Ipv4StaticRouting::SetDefaultMulticastRoute (uint32_t outputInterface);
-@end verbatim
-
-This is the multicast equivalent of the unicast version SetDefaultRoute.
-We tell the routing system what to do in the case where a specific route
-to a destination multicast group is not found. The system forwards
-packets out the specified interface in the hope that "something out there"
-knows better how to route the packet. This method is only used in
-initially sending packets off of a host. The default multicast route is
-not consulted during forwarding -- exact routes must be specified using
-AddMulticastRoute for that case.
-
-Since we're basically sending packets to some entity we think may know
-better what to do, we don't pay attention to "subtleties" like origin
-address, nor do we worry about forwarding out multiple interfaces. If the
-default multicast route is set, it is returned as the selected route from
-LookupStatic irrespective of origin or multicast group if another specific
-route is not found.
-
-Finally, a number of additional functions are provided to fetch and
-remove multicast routes:
-@verbatim
- uint32_t GetNMulticastRoutes (void) const;
-
- Ipv4MulticastRoute *GetMulticastRoute (uint32_t i) const;
-
- Ipv4MulticastRoute *GetDefaultMulticastRoute (void) const;
-
- bool RemoveMulticastRoute (Ipv4Address origin,
- Ipv4Address group,
- uint32_t inputInterface);
-
- void RemoveMulticastRoute (uint32_t index);
-@end verbatim
-
-
--- a/doc/manual/simple.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,6 +0,0 @@
-@node Simple NetDevice
-@chapter Simple NetDevice
-
-@cartouche
-Placeholder chapter
-@end cartouche
--- a/doc/manual/sockets.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,200 +0,0 @@
-@node Sockets APIs
-@chapter Sockets APIs
-
-The @uref{http://en.wikipedia.org/wiki/Berkeley_sockets,,sockets API}
-is a long-standing API used by user-space applications to access
-network services in the kernel. A ``socket'' is an abstraction, like
-a Unix file handle, that allows applications to connect to other
-Internet hosts and exchange reliable byte streams and unreliable
-datagrams, among other services.
-
-ns-3 provides two types of sockets APIs, and it is important to
-understand the differences between them. The first is a @emph{native}
-ns-3 API, while the second uses the services of the native API to
-provide a @uref{http://en.wikipedia.org/wiki/POSIX,,POSIX-like}
-API as part of an overall application process. Both APIs strive
-to be close to the typical sockets API that application writers
-on Unix systems are accustomed to, but the POSIX variant is much
-closer to a real system's sockets API.
-
-@section ns-3 sockets API
-
-The native sockets API for ns-3 provides an interface to various
-types of transport protocols (TCP, UDP) as well as to packet sockets
-and, in the future, Netlink-like sockets. However, users are cautioned
-to understand that the semantics are @strong{not} the exact same as
-one finds in a real system (for an API which is very much aligned
-to real systems, see the next section).
-
-@code{class ns3::Socket} is defined in @code{src/node/socket.cc,h}.
-Readers will note that many public member functions are aligned
-with real sockets function calls, and all other things being equal,
-we have tried to align with a Posix sockets API. However, note that:
-
-@itemize @bullet
-@item ns-3 applications handle a smart pointer to a Socket object, not
-a file descriptor;
-@item there is no notion of synchronous API or a ``blocking'' API;
-in fact, the model for interaction between application and socket is
-one of asynchronous I/O, which is not typically found in real systems
-(more on this below);
-@item the C-style socket address structures are not used;
-@item the API is not a complete sockets API, such as supporting
-all socket options or all function variants;
-@item many calls use @code{ns3::Packet} class to transfer data
-between application and socket. This may seem peculiar to
-pass ``Packets'' across a stream socket API, but think
-of these packets as just fancy byte buffers at this level (more
-on this also below).
-@end itemize
-
-@subsection Basic operation and calls
-
-@float Figure,fig:sockets-overview
-@caption{Implementation overview of native sockets API}
-@image{figures/sockets-overview, 10cm}
-@end float
-
-@subsubsection Creating sockets
-
-An application that wants to use sockets must first create one.
-On real systems using a C-based API, this is accomplished by calling socket():
-@verbatim
- int
- socket(int domain, int type, int protocol);
-@end verbatim
-which creates a socket in the system and returns an integer descriptor.
-
-In ns-3, we have no equivalent of a system call at the lower layers,
-so we adopt the following model. There are certain @emph{factory}
-objects that can create sockets. Each factory is capable of creating
-one type of socket, and if sockets of a particular type are able to
-be created on a given node, then a factory that can create such sockets
-must be aggregated to the Node.
-@verbatim
- static Ptr<Socket> CreateSocket (Ptr<Node> node, TypeId tid);
-@end verbatim
-Examples of TypeIds to pass to this method are @code{TcpSocketFactory},
-@code{PacketSocketFactory}, and @code{UdpSocketFactory}.
-
-This method returns a smart pointer to a Socket object. Here is an
-example:
-@smallformat
-@example
- Ptr<Node> n0;
- // Do some stuff to build up the Node's internet stack
- Ptr<Socket> localSocket = Socket::CreateSocket (n0, TcpSocketFactory::GetTypeId ());
-@end example
-@end smallformat
-
-In some ns-3 code, sockets will not be explicitly created by user's
-main programs, if an ns-3 application does it. For instance, for
-@code{class ns3::OnOffApplication}, the function @code{StartApplication()}
-performs the socket creation, and the application holds the socket
-pointer.
-
-@subsubsection Using sockets
-
-Below is a typical sequence of socket calls for a TCP client in a
-real implementation:
-@itemize @bullet
-@item @code{sock = socket(PF_INET, SOCK_STREAM, IPPROTO_TCP);}
-@item @code{bind(sock, ...);}
-@item @code{connect(sock, ...);}
-@item @code{send(sock, ...);}
-@item @code{recv(sock, ...);}
-@item @code{close(sock);}
-@end itemize
-
-There are analogs to all of these calls in ns-3, but we will focus on
-two aspects here. First, most usage of sockets in real systems
-requires a way to manage I/O between the application and kernel.
-These models include @emph{blocking sockets}, @emph{signal-based I/O},
-and @emph{non-blocking sockets} with polling. In ns-3, we make use
-of the callback mechanisms to support a fourth mode, which is
-analogous to POSIX @emph{asynchronous I/O}.
-
-In this model, on the sending side, if the @code{send()} call were to
-fail because of insufficient buffers, the application suspends the
-sending of more data until a function registered at the
-@code{SetSendCallback()} callback is invoked. An application can
-also ask the socket how much space is available by calling
-@code{GetTxAvailable ()}. A typical sequence of events for
-sending data (ignoring connection setup) might be:
-
-@itemize @bullet
-@item @code{SetSendCallback (MakeCallback(&HandleSendCallback));}
-@item @code{Send ();}
-@item @code{Send ();}
-@item ...
-@item @code{// Send fails because buffer is full}
-@item (wait until HandleSendCallback() is called)
-@item (HandleSendCallback() is called by socket, since space now available)
-@item @code{Send (); // Start sending again}
-@end itemize
-
-Similarly, on the receive side, the socket user does not block on
-a call to @code{recv()}. Instead, the application sets a callback
-with @code{SetRecvCallback ()} in which the socket will notify the
-application when (and how much) there is data to be read, and
-the application then calls @code{Recv()} to read the data until
-no more can be read.
-
-@subsection Packet vs. buffer variants
-
-There are two basic variants of @code{Send()} and @code{Recv()} supported:
-@verbatim
- virtual int Send (Ptr<Packet> p) = 0;
- int Send (const uint8_t* buf, uint32_t size);
-
- Ptr<Packet> Recv (void);
- int Recv (uint8_t* buf, uint32_t size);
-@end verbatim
-
-The non-Packet variants are provided for legacy API reasons. When calling
-the raw buffer variant of @code{Send()}, the buffer is immediately
-written into a Packet and the @code{Send (Ptr<Packet> p)} is invoked.
-
-Users may find it semantically odd to pass a Packet to a stream socket
-such as TCP. However, do not let the name bother you; think of
-@code{ns3::Packet} to be a fancy byte buffer. There are a few reasons why
-the Packet variants are more likely to be preferred in ns-3:
-
-@itemize @bullet
-@item Users can use the Tags facility of packets to, for example, encode
-a flow ID or other helper data at the application layer.
-@item Users can exploit the copy-on-write implementation to avoid
-memory copies (on the receive side, the conversion back to a
-@code{uint8_t* buf} may sometimes incur an additional copy).
-@item Use of Packet is more aligned with the rest of the ns-3 API
-@end itemize
-
-@subsection Sending dummy data
-
-Sometimes, users want the simulator to just pretend that there is an
-actual data payload in the packet (e.g. to calculate transmission delay)
-but do not want to actually produce or consume the data. This is
-straightforward to support in ns-3; have applications call
-@code{Create<Packet> (size);} instead of @code{Create<Packet> (buffer, size);}.
-Similarly, passing in a zero to the pointer argument in the raw buffer
-variants has the same effect. Note that, if some subsequent code tries
-to read the Packet data buffer, the fake buffer will be converted to
-a real (zeroed) buffer on the spot, and the efficiency will be lost there.
-
-@subsection Socket options
-
-@emph{to be completed}
-
-@subsection Socket errno
-
-@emph{to be completed}
-
-@subsection Example programs
-
-@emph{to be completed}
-
-@section POSIX-like sockets API
-
-@cartouche
-Under development in the http://code.nsnam.org/mathieu/ns-3-simu repository.
-@end cartouche
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/animation.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,181 @@
+.. include:: replace.txt
+
+Animation
+---------
+
+Animation is an important tool for network simulation. While |ns3| does not
+contain a default graphical animation tool, it does provide an animation
+interface for use with stand-alone animators. One such animator called NetAnim,
+presently supporting packet flow animation for point-to-point links, has been
+developed. Other animators and visualization tools are in development; they may
+make use of the existing animation interface or may develop new ones,
+
+Animation interface
+*******************
+
+The animation interface uses underlying |ns3| trace sources to construct a
+timestamped ASCII file that can be read by a standalone animator. The animation
+interface in |ns3| currently only supports point-to-point links; however, we
+hope to support other link types such as CSMA and wireless in the near future.
+A snippet from a sample trace file is shown below.::
+
+ 0.0 N 0 4 5.5
+ 0.0 N 1 7 5.5
+ 0.0 N 2 2.5 2.90192
+
+ ...
+
+ 0.0 L 0 1
+ 0.0 L 0 2
+ 0.0 L 0 3
+
+ ...
+
+ Running the simulation
+ 0.668926 P 11 1 0.66936 0.669926 0.67036
+ 0.67036 P 1 0 0.670794 0.67136 0.671794
+ 0.671794 P 0 6 0.672227 0.672794 0.673227
+
+ ...
+
+The tracefile describes where nodes and links should be placed at the top of the
+file. Following this placement, the packet events are shown. The format for node
+placement, link placement and packet events is shown below.
+
+* Node placement: <time of placement> <N for node> <node id> <x position> <y
+ position>
+* Link placement: <time of placement> <L for link> <node1 id> <node2 id>
+* Packet events: <time of first bit tx> <P for packet> <source node>
+ <destination node> <time of last bit tx> <time of first bit rx> <time of last
+ bit rx>
+
+To get started using the animation interface, several example scripts have been
+provided to show proper use. These examples can be found in examples/animation.
+The example scripts use the animation interface as well as topology helpers in
+order to automatically place the nodes and generate the custom trace. It is
+important to note that if a topology helper is not used with its provided
+BoundingBox method, which automatically calculates the nodes' canvas positions,
+the nodes must be placed manually by aggregating a CanvasLocation to the node.
+An example use of CanvasLocation can be found in any of the topology helpers.
+Additionally, a simple example of placing a node is shown below:::
+
+ // assuming a node container m_hub exists and
+ // contains at least one node.
+ // we grab this node and associate a
+ // CanvasLocation to it, in order for the
+ // animation interface to place the node
+ Ptr<Node> hub = m_hub.Get (0);
+ Ptr<CanvasLocation> hubLoc = hub->GetObject<CanvasLocation> ();
+ if (hubLoc == 0)
+ {
+ hubLoc = CreateObject<CanvasLocation> ();
+ hub->AggregateObject (hubLoc);
+ }
+ Vector hubVec (5, 7);
+ hubLoc->SetLocation (hubVec);
+
+Finally, after the simulation has been set up and the nodes have been placed,
+the animation interface is used to start the animation, which writes the custom
+trace file. Below is an example of how to set up and start the animation
+interface.::
+
+ AnimationInterface anim;
+ // the animation interface can be set up to write
+ // to a socket, if a port > 0 is specified
+ // see doxygen for more information
+ if (port > 0)
+ {
+ anim.SetServerPort (port);
+ }
+ else if (!animFile.empty ())
+ {
+ // if a file name is specified,
+ // the trace is written to the file.
+ // otherwise, it is directed to stdout
+ anim.SetOutputFile (animFile);
+ }
+ anim.StartAnimation ();
+
+NetAnim
+*******
+
+NetAnim is a stand-alone program which uses the custom trace files generated by
+the animation interface to graphically display the simulation. NetAnim is based
+on the multi-platform `Qt4 GUI toolkit <http://www.qtsoftware.com/products/>`_.
+A screenshot of the NetAnim GUI is shown below.
+
+.. _anim-dumbbell:
+
+.. figure:: figures/animation-dumbbell.*
+
+ NetAnim GUI with dumbbell animation.
+
+The NetAnim GUI provides play, pause, and record buttons. Play and pause start
+and stop the simulation. The record button starts a series of screenshots of the
+animator, which are written to the directory in which the trace file was run.
+Two slider bars also exist. The top slider provides a "seek" functionality,
+which allows a user to skip to any moment in the simulation. The bottom slider
+changes the granularity of the time step for the animation. Finally, there is a
+quit button to stop the simulation and quit the animator.
+
+Prerequisites
++++++++++++++
+
+The animator requires the Qt4 development packages. If you are using a Debian or
+Ubuntu Linux distribution, you can get the following package: qt4-dev-tools
+
+This should install everything you need to compile and build NetAnim. If you
+are using an Red Hat based distribution, look for similar qt4 packages (or
+libqt4*) and install these using yum. Mac users should install the binaries:
+`<http://www.qtsoftware.com/downloads/mac-os-cpp>`_.
+
+Make sure to download the binary package; look for a link to something without
+the word "src" or "debug" in the download filename. These will be the library
+binaries you need.
+
+Downloading NetAnim
++++++++++++++++++++
+
+The tarball of the source code for NetAnim is available here:
+`<http://www.nsnam.org/~jpelkey3/NetAnim.tar.gz>`_. Download it, then untar
+it:::
+
+ tar -xzvf NetAnim.tar.gz
+
+Building NetAnim
+++++++++++++++++
+
+NetAnim uses a Qt4 build tool called qmake; this is similar to the configure
+script from autotools in that it generates the Makefile, which make then uses to
+build the project. qmake is different on different versions of Qt, so we'll
+provide some additional information that is system dependent. You can check your
+default version of qmake:::
+
+ qmake --version
+ Qmake version: 1.07a (Qt 3.3.8b)
+ Qmake is free software from Trolltech ASA.
+
+If you see something like the above, where it says Qt 3.x.x, find the
+qt4 version of qmake on your system and explicitly call it instead.
+
+In general,::
+
+ cd NetAnim
+ qmake
+ make
+
+On Mac OSX,::
+
+ cd NetAnim
+ /usr/local/Trolltech/Qt-4.x.y/bin/qmake
+ make
+
+Note that above, the x.y is the specific version of Qt4 you are running. As of
+April 1st 2009, the latest version is 4.5.0, although you might have an older
+version already installed.
+
+On Ubuntu/Debian with Qt3 AND Qt4,::
+
+ cd NetAnim
+ qmake-qt4
+ make
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/applications.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,6 @@
+.. include:: replace.txt
+
+Applications
+------------
+
+*Placeholder chapter*
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/attributes.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,801 @@
+.. include:: replace.txt
+
+Attributes
+----------
+
+In |ns3| simulations, there are two main aspects to configuration:
+
+* the simulation topology and how objects are connected
+* the values used by the models instantiated in the topology
+
+This chapter focuses on the second item above: how the many values in use in
+|ns3| are organized, documented, and modifiable by |ns3| users. The |ns3|
+attribute system is also the underpinning of how traces and statistics are
+gathered in the simulator.
+
+Before delving into details of the attribute value system, it will help to
+review some basic properties of class :cpp:class:`ns3::Object`.
+
+Object Overview
+***************
+
+|ns3| is fundamentally a C++ object-based system. By this we mean that new C++
+classes (types) can be declared, defined, and subclassed as usual.
+
+Many |ns3| objects inherit from the :cpp:class:`ns3::Object` base class. These
+objects have some additional properties that we exploit for organizing the
+system and improving the memory management of our objects:
+
+* a "metadata" system that links the class name to a lot of meta-information
+ about the object, including the base class of the subclass, the set of
+ accessible constructors in the subclass, and the set of "attributes" of the
+ subclass
+* a reference counting smart pointer implementation, for memory management.
+
+|ns3| objects that use the attribute system derive from either
+:cpp:class:`ns3::Object` or :cpp:class:`ns3::ObjectBase`. Most |ns3| objects we
+will discuss derive from :cpp:class:`ns3::Object`, but a few that are outside
+the smart pointer memory management framework derive from
+:cpp:class:`ns3::ObjectBase`.
+
+Let's review a couple of properties of these objects.
+
+Smart pointers
+**************
+
+As introduced in the |ns3| tutorial, |ns3| objects are memory managed by a
+`reference counting smart pointer implementation
+<http://en.wikipedia.org/wiki/Smart_pointer>`_, class :cpp:class:`ns3::Ptr`.
+
+Smart pointers are used extensively in the |ns3| APIs, to avoid passing
+references to heap-allocated objects that may cause memory leaks.
+For most basic usage (syntax), treat a smart pointer like a regular pointer:::
+
+ Ptr<WifiNetDevice> nd = ...;
+ nd->CallSomeFunction ();
+ // etc.
+
+CreateObject
+++++++++++++
+
+As we discussed above in :ref:`Memory management and class Ptr`, at the
+lowest-level API, objects of type :cpp:class:`ns3::Object` are not instantiated
+using ``operator new`` as usual but instead by a templated function called
+:cpp:func:`CreateObject()`.
+
+A typical way to create such an object is as follows:::
+
+ Ptr<WifiNetDevice> nd = CreateObject<WifiNetDevice> ();
+
+You can think of this as being functionally equivalent to:::
+
+ WifiNetDevice* nd = new WifiNetDevice ();
+
+Objects that derive from :cpp:class:`ns3::Object` must be allocated on the heap
+using CreateObject(). Those deriving from :cpp:class:`ns3::ObjectBase`, such as
+|ns3| helper functions and packet headers and trailers, can be allocated on the
+stack.
+
+In some scripts, you may not see a lot of CreateObject() calls in the code; this
+is because there are some helper objects in effect that are doing the
+CreateObject()s for you.
+
+TypeId
+++++++
+
+|ns3| classes that derive from class ns3::Object can include a metadata class
+called ``TypeId`` that records meta-information about the class, for use in the
+object aggregation and component manager systems:
+
+* a unique string identifying the class
+* the base class of the subclass, within the metadata system
+* the set of accessible constructors in the subclass
+
+Object Summary
+++++++++++++++
+
+Putting all of these concepts together, let's look at a specific
+example: class :cpp:class:`ns3::Node`.
+
+The public header file node.h has a declaration that includes a static GetTypeId
+function call:::
+
+ class Node : public Object
+ {
+ public:
+ static TypeId GetTypeId (void);
+ ...
+
+This is defined in the ``node.cc`` file as follows:::
+
+ TypeId
+ Node::GetTypeId (void)
+ {
+ static TypeId tid = TypeId ("ns3::Node")
+ .SetParent<Object> ()
+ .AddConstructor<Node> ()
+ .AddAttribute ("DeviceList", "The list of devices associated to this Node.",
+ ObjectVectorValue (),
+ MakeObjectVectorAccessor (&Node::m_devices),
+ MakeObjectVectorChecker<NetDevice> ())
+ .AddAttribute ("ApplicationList", "The list of applications associated to this Node.",
+ ObjectVectorValue (),
+ MakeObjectVectorAccessor (&Node::m_applications),
+ MakeObjectVectorChecker<Application> ())
+ .AddAttribute ("Id", "The id (unique integer) of this Node.",
+ TypeId::ATTR_GET, // allow only getting it.
+ UintegerValue (0),
+ MakeUintegerAccessor (&Node::m_id),
+ MakeUintegerChecker<uint32_t> ())
+ ;
+ return tid;
+ }
+
+Consider the TypeId of an |ns3| ``Object`` class as an extended form of run time
+type information (RTTI). The C++ language includes a simple kind of RTTI in
+order to support ``dynamic_cast`` and ``typeid`` operators.
+
+The "``.SetParent<Object> ()``" call in the declaration above is used in
+conjunction with our object aggregation mechanisms to allow safe up- and
+down-casting in inheritance trees during ``GetObject``.
+
+The "``.AddConstructor<Node> ()``" call is used in conjunction with our abstract
+object factory mechanisms to allow us to construct C++ objects without forcing a
+user to know the concrete class of the object she is building.
+
+The three calls to "``.AddAttribute``" associate a given string with a strongly
+typed value in the class. Notice that you must provide a help string which may
+be displayed, for example, via command line processors. Each ``Attribute`` is
+associated with mechanisms for accessing the underlying member variable in the
+object (for example, ``MakeUintegerAccessor`` tells the generic ``Attribute``
+code how to get to the node ID above). There are also "Checker" methods which
+are used to validate values.
+
+When users want to create Nodes, they will usually call some form of
+``CreateObject``,::
+
+ Ptr<Node> n = CreateObject<Node> ();
+
+or more abstractly, using an object factory, you can create a ``Node`` object
+without even knowing the concrete C++ type::
+
+ ObjectFactory factory;
+ const std::string typeId = "ns3::Node'';
+ factory.SetTypeId (typeId);
+ Ptr<Object> node = factory.Create <Object> ();
+
+Both of these methods result in fully initialized attributes being available
+in the resulting ``Object`` instances.
+
+We next discuss how attributes (values associated with member variables or
+functions of the class) are plumbed into the above TypeId.
+
+Attribute Overview
+******************
+
+The goal of the attribute system is to organize the access of
+internal member objects of a simulation. This goal arises because,
+typically in simulation, users will cut and paste/modify existing
+simulation scripts, or will use higher-level simulation constructs,
+but often will be interested in studying or tracing particular
+internal variables. For instance, use cases such as:
+
+* "I want to trace the packets on the wireless interface only on the first
+ access point"
+* "I want to trace the value of the TCP congestion window (every time it
+ changes) on a particular TCP socket"
+* "I want a dump of all values that were used in my simulation."
+
+Similarly, users may want fine-grained access to internal variables in the
+simulation, or may want to broadly change the initial value used for a
+particular parameter in all subsequently created objects. Finally, users may
+wish to know what variables are settable and retrievable in a simulation
+configuration. This is not just for direct simulation interaction on the command
+line; consider also a (future) graphical user interface that would like to be
+able to provide a feature whereby a user might right-click on an node on the
+canvas and see a hierarchical, organized list of parameters that are settable on
+the node and its constituent member objects, and help text and default values
+for each parameter.
+
+Functional overview
++++++++++++++++++++
+
+We provide a way for users to access values deep in the system, without having
+to plumb accessors (pointers) through the system and walk pointer chains to get
+to them. Consider a class DropTailQueue that has a member variable that is an
+unsigned integer ``m_maxPackets``; this member variable controls the depth of
+the queue.
+
+If we look at the declaration of DropTailQueue, we see the following:::
+
+ class DropTailQueue : public Queue {
+ public:
+ static TypeId GetTypeId (void);
+ ...
+
+ private:
+ std::queue<Ptr<Packet> > m_packets;
+ uint32_t m_maxPackets;
+ };
+
+Let's consider things that a user may want to do with the value of
+m_maxPackets:
+
+* Set a default value for the system, such that whenever a new DropTailQueue is
+ created, this member is initialized to that default.
+* Set or get the value on an already instantiated queue.
+
+The above things typically require providing Set() and Get() functions, and some
+type of global default value.
+
+In the |ns3| attribute system, these value definitions and accessor functions
+are moved into the TypeId class; e.g.:::
+
+ NS_OBJECT_ENSURE_REGISTERED (DropTailQueue);
+
+ TypeId DropTailQueue::GetTypeId (void)
+ {
+ static TypeId tid = TypeId ("ns3::DropTailQueue")
+ .SetParent<Queue> ()
+ .AddConstructor<DropTailQueue> ()
+ .AddAttribute ("MaxPackets",
+ "The maximum number of packets accepted by this DropTailQueue.",
+ UintegerValue (100),
+ MakeUintegerAccessor (&DropTailQueue::m_maxPackets),
+ MakeUintegerChecker<uint32_t> ())
+ ;
+
+ return tid;
+ }
+
+The AddAttribute() method is performing a number of things with this
+value:
+
+* Binding the variable m_maxPackets to a string "MaxPackets"
+* Providing a default value (100 packets)
+* Providing some help text defining the value
+* Providing a "checker" (not used in this example) that can be used to set
+ bounds on the allowable range of values
+
+The key point is that now the value of this variable and its default value are
+accessible in the attribute namespace, which is based on strings such as
+"MaxPackets" and TypeId strings. In the next section, we will provide an example
+script that shows how users may manipulate these values.
+
+Note that initialization of the attribute relies on the macro
+``NS_OBJECT_ENSURE_REGISTERED`` (DropTailQueue) being called; if you leave this
+out of your new class implementation, your attributes will not be initialized
+correctly.
+
+While we have described how to create attributes, we still haven't described how
+to access and manage these values. For instance, there is no ``globals.h``
+header file where these are stored; attributes are stored with their classes.
+Questions that naturally arise are how do users easily learn about all of the
+attributes of their models, and how does a user access these attributes, or
+document their values as part of the record of their simulation?
+
+Default values and command-line arguments
++++++++++++++++++++++++++++++++++++++++++
+
+Let's look at how a user script might access these values.
+This is based on the script found at ``samples/main-attribute-value.cc``,
+with some details stripped out.::
+
+ //
+ // This is a basic example of how to use the attribute system to
+ // set and get a value in the underlying system; namely, an unsigned
+ // integer of the maximum number of packets in a queue
+ //
+
+ int
+ main (int argc, char *argv[])
+ {
+
+ // By default, the MaxPackets attribute has a value of 100 packets
+ // (this default can be observed in the function DropTailQueue::GetTypeId)
+ //
+ // Here, we set it to 80 packets. We could use one of two value types:
+ // a string-based value or a Uinteger value
+ Config::SetDefault ("ns3::DropTailQueue::MaxPackets", StringValue ("80"));
+ // The below function call is redundant
+ Config::SetDefault ("ns3::DropTailQueue::MaxPackets", UintegerValue (80));
+
+ // Allow the user to override any of the defaults and the above
+ // SetDefaults() at run-time, via command-line arguments
+ CommandLine cmd;
+ cmd.Parse (argc, argv);
+
+The main thing to notice in the above are the two calls to
+``Config::SetDefault``. This is how we set the default value
+for all subsequently instantiated DropTailQueues. We illustrate
+that two types of Value classes, a StringValue and a UintegerValue class,
+can be used to assign the value to the attribute named by
+"ns3::DropTailQueue::MaxPackets".
+
+Now, we will create a few objects using the low-level API; here,
+our newly created queues will not have a m_maxPackets initialized to
+100 packets but to 80 packets, because of what we did above with
+default values.::
+
+ Ptr<Node> n0 = CreateObject<Node> ();
+
+ Ptr<PointToPointNetDevice> net0 = CreateObject<PointToPointNetDevice> ();
+ n0->AddDevice (net0);
+
+ Ptr<Queue> q = CreateObject<DropTailQueue> ();
+ net0->AddQueue(q);
+
+At this point, we have created a single node (Node 0) and a single
+PointToPointNetDevice (NetDevice 0) and added a DropTailQueue to it.
+
+Now, we can manipulate the MaxPackets value of the already instantiated
+DropTailQueue. Here are various ways to do that.
+
+Pointer-based access
+++++++++++++++++++++
+
+We assume that a smart pointer (Ptr) to a relevant network device is in hand; in
+the current example, it is the ``net0`` pointer.
+
+One way to change the value is to access a pointer to the underlying queue and
+modify its attribute.
+
+First, we observe that we can get a pointer to the (base class) queue via the
+PointToPointNetDevice attributes, where it is called TxQueue::
+
+ PointerValue tmp;
+ net0->GetAttribute ("TxQueue", tmp);
+ Ptr<Object> txQueue = tmp.GetObject ();
+
+Using the GetObject function, we can perform a safe downcast to a DropTailQueue,
+where MaxPackets is a member::
+
+ Ptr<DropTailQueue> dtq = txQueue->GetObject <DropTailQueue> ();
+ NS_ASSERT (dtq != 0);
+
+Next, we can get the value of an attribute on this queue. We have introduced
+wrapper "Value" classes for the underlying data types, similar to Java wrappers
+around these types, since the attribute system stores values and not disparate
+types. Here, the attribute value is assigned to a UintegerValue, and the Get()
+method on this value produces the (unwrapped) uint32_t.::
+
+ UintegerValue limit;
+ dtq->GetAttribute ("MaxPackets", limit);
+ NS_LOG_INFO ("1. dtq limit: " << limit.Get () << " packets");
+
+Note that the above downcast is not really needed; we could have done the same
+using the Ptr<Queue> even though the attribute is a member of the subclass::
+
+ txQueue->GetAttribute ("MaxPackets", limit);
+ NS_LOG_INFO ("2. txQueue limit: " << limit.Get () << " packets");
+
+Now, let's set it to another value (60 packets)::
+
+ txQueue->SetAttribute("MaxPackets", UintegerValue (60));
+ txQueue->GetAttribute ("MaxPackets", limit);
+ NS_LOG_INFO ("3. txQueue limit changed: " << limit.Get () << " packets");
+
+Namespace-based access
+++++++++++++++++++++++
+
+An alternative way to get at the attribute is to use the configuration
+namespace. Here, this attribute resides on a known path in this namespace; this
+approach is useful if one doesn't have access to the underlying pointers and
+would like to configure a specific attribute with a single statement.::
+
+ Config::Set ("/NodeList/0/DeviceList/0/TxQueue/MaxPackets", UintegerValue (25));
+ txQueue->GetAttribute ("MaxPackets", limit);
+ NS_LOG_INFO ("4. txQueue limit changed through namespace: " <<
+ limit.Get () << " packets");
+
+We could have also used wildcards to set this value for all nodes and all net
+devices (which in this simple example has the same effect as the previous
+Set())::
+
+ Config::Set ("/NodeList/*/DeviceList/*/TxQueue/MaxPackets", UintegerValue (15));
+ txQueue->GetAttribute ("MaxPackets", limit);
+ NS_LOG_INFO ("5. txQueue limit changed through wildcarded namespace: " <<
+ limit.Get () << " packets");
+
+Object Name Service-based access
+++++++++++++++++++++++++++++++++
+
+Another way to get at the attribute is to use the object name service facility.
+Here, this attribute is found using a name string. This approach is useful if
+one doesn't have access to the underlying pointers and it is difficult to
+determine the required concrete configuration namespaced path.::
+
+ Names::Add ("server", serverNode);
+ Names::Add ("server/eth0", serverDevice);
+
+ ...
+
+ Config::Set ("/Names/server/eth0/TxQueue/MaxPackets", UintegerValue (25));
+
+:ref:`Object names` for a fuller treatment of the |ns3| configuration namespace.
+
+Setting through constructors helper classes
++++++++++++++++++++++++++++++++++++++++++++
+
+Arbitrary combinations of attributes can be set and fetched from
+the helper and low-level APIs; either from the constructors themselves:::
+
+ Ptr<Object> p = CreateObject<MyNewObject> ("n1", v1, "n2", v2, ...);
+
+or from the higher-level helper APIs, such as:::
+
+ mobility.SetPositionAllocator ("GridPositionAllocator",
+ "MinX", DoubleValue (-100.0),
+ "MinY", DoubleValue (-100.0),
+ "DeltaX", DoubleValue (5.0),
+ "DeltaY", DoubleValue (20.0),
+ "GridWidth", UintegerValue (20),
+ "LayoutType", StringValue ("RowFirst"));
+
+Implementation details
+++++++++++++++++++++++
+
+Value classes
+~~~~~~~~~~~~~
+
+Readers will note the new FooValue classes which are subclasses of the
+AttributeValue base class. These can be thought of as an intermediate class that
+can be used to convert from raw types to the Values that are used by the
+attribute system. Recall that this database is holding objects of many types
+with a single generic type. Conversions to this type can either be done using an
+intermediate class (IntegerValue, DoubleValue for "floating point") or via
+strings. Direct implicit conversion of types to Value is not really practical.
+So in the above, users have a choice of using strings or values:::
+
+ p->Set ("cwnd", StringValue ("100")); // string-based setter
+ p->Set ("cwnd", IntegerValue (100)); // integer-based setter
+
+The system provides some macros that help users declare and define
+new AttributeValue subclasses for new types that they want to introduce into
+the attribute system:
+
+* ATTRIBUTE_HELPER_HEADER
+* ATTRIBUTE_HELPER_CPP
+
+Initialization order
+~~~~~~~~~~~~~~~~~~~~
+
+Attributes in the system must not depend on the state of any other Attribute in
+this system. This is because an ordering of Attribute initialization is not
+specified, nor enforced, by the system. A specific example of this can be seen
+in automated configuration programs such as :cpp:class:`ns3::ConfigStore`.
+Although a given model may arrange it so that Attributes are initialized in a
+particular order, another automatic configurator may decide independently to
+change Attributes in, for example, alphabetic order.
+
+Because of this non-specific ordering, no Attribute in the system may have any
+dependence on any other Attribute. As a corollary, Attribute setters must never
+fail due to the state of another Attribute. No Attribute setter may change (set)
+any other Attribute value as a result of changing its value.
+
+This is a very strong restriction and there are cases where Attributes must set
+consistently to allow correct operation. To this end we do allow for consistency
+checking *when the attribute is used* (cf. NS_ASSERT_MSG or NS_ABORT_MSG).
+
+In general, the attribute code to assign values to the underlying class member
+variables is executed after an object is constructed. But what if you need the
+values assigned before the constructor body executes, because you need them in
+the logic of the constructor? There is a way to do this, used for example in the
+class :cpp:class:`ns3::ConfigStore`: call ``ObjectBase::ConstructSelf ()`` as
+follows:::
+
+ ConfigStore::ConfigStore ()
+ {
+ ObjectBase::ConstructSelf (AttributeList ());
+ // continue on with constructor.
+ }
+
+Extending attributes
+********************
+
+The |ns3| system will place a number of internal values under the attribute
+system, but undoubtedly users will want to extend this to pick up ones we have
+missed, or to add their own classes to this.
+
+Adding an existing internal variable to the metadata system
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Consider this variable in class TcpSocket:::
+
+ uint32_t m_cWnd; // Congestion window
+
+Suppose that someone working with TCP wanted to get or set the value of that
+variable using the metadata system. If it were not already provided by |ns3|,
+the user could declare the following addition in the runtime metadata system (to
+the TypeId declaration for TcpSocket):::
+
+ .AddAttribute ("Congestion window",
+ "Tcp congestion window (bytes)",
+ UintegerValue (1),
+ MakeUintegerAccessor (&TcpSocket::m_cWnd),
+ MakeUintegerChecker<uint16_t> ())
+
+Now, the user with a pointer to the TcpSocket can perform operations such as
+setting and getting the value, without having to add these functions explicitly.
+Furthermore, access controls can be applied, such as allowing the parameter to
+be read and not written, or bounds checking on the permissible values can be
+applied.
+
+Adding a new TypeId
++++++++++++++++++++
+
+Here, we discuss the impact on a user who wants to add a new class to |ns3|;
+what additional things must be done to hook it into this system.
+
+We've already introduced what a TypeId definition looks like:::
+
+ TypeId
+ RandomWalk2dMobilityModel::GetTypeId (void)
+ {
+ static TypeId tid = TypeId ("ns3::RandomWalk2dMobilityModel")
+ .SetParent<MobilityModel> ()
+ .SetGroupName ("Mobility")
+ .AddConstructor<RandomWalk2dMobilityModel> ()
+ .AddAttribute ("Bounds",
+ "Bounds of the area to cruise.",
+ RectangleValue (Rectangle (0.0, 0.0, 100.0, 100.0)),
+ MakeRectangleAccessor (&RandomWalk2dMobilityModel::m_bounds),
+ MakeRectangleChecker ())
+ .AddAttribute ("Time",
+ "Change current direction and speed after moving for this delay.",
+ TimeValue (Seconds (1.0)),
+ MakeTimeAccessor (&RandomWalk2dMobilityModel::m_modeTime),
+ MakeTimeChecker ())
+ // etc (more parameters).
+ ;
+ return tid;
+ }
+
+The declaration for this in the class declaration is one-line public member
+method:::
+
+ public:
+ static TypeId GetTypeId (void);
+
+Typical mistakes here involve:
+
+* Not calling the SetParent method or calling it with the wrong type
+* Not calling the AddConstructor method of calling it with the wrong type
+* Introducing a typographical error in the name of the TypeId in its constructor
+* Not using the fully-qualified c++ typename of the enclosing c++ class as the
+ name of the TypeId
+
+None of these mistakes can be detected by the |ns3| codebase so, users
+are advised to check carefully multiple times that they got these right.
+
+Adding new class type to the attribute system
+*********************************************
+
+From the perspective of the user who writes a new class in the system and wants
+to hook it in to the attribute system, there is mainly the matter of writing the
+conversions to/from strings and attribute values. Most of this can be
+copy/pasted with macro-ized code. For instance, consider class declaration for
+Rectangle in the ``src/mobility/`` directory:
+
+Header file
++++++++++++
+
+::
+
+ /**
+ * \brief a 2d rectangle
+ */
+ class Rectangle
+ {
+ ...
+
+ double xMin;
+ double xMax;
+ double yMin;
+ double yMax;
+ };
+
+One macro call and two operators, must be added below the class declaration in
+order to turn a Rectangle into a value usable by the ``Attribute`` system:::
+
+ std::ostream &operator << (std::ostream &os, const Rectangle &rectangle);
+ std::istream &operator >> (std::istream &is, Rectangle &rectangle);
+
+ ATTRIBUTE_HELPER_HEADER (Rectangle);
+
+Implementation file
++++++++++++++++++++
+
+In the class definition (``.cc`` file), the code looks like this:::
+
+ ATTRIBUTE_HELPER_CPP (Rectangle);
+
+ std::ostream &
+ operator << (std::ostream &os, const Rectangle &rectangle)
+ {
+ os << rectangle.xMin << "|" << rectangle.xMax << "|" << rectangle.yMin << "|"
+ << rectangle.yMax;
+ return os;
+ }
+ std::istream &
+ operator >> (std::istream &is, Rectangle &rectangle)
+ {
+ char c1, c2, c3;
+ is >> rectangle.xMin >> c1 >> rectangle.xMax >> c2 >> rectangle.yMin >> c3
+ >> rectangle.yMax;
+ if (c1 != '|' ||
+ c2 != '|' ||
+ c3 != '|')
+ {
+ is.setstate (std::ios_base::failbit);
+ }
+ return is;
+ }
+
+These stream operators simply convert from a string representation of the
+Rectangle ("xMin|xMax|yMin|yMax") to the underlying Rectangle, and the modeler
+must specify these operators and the string syntactical representation of an
+instance of the new class.
+
+ConfigStore
+***********
+
+**Feedback requested:** This is an experimental feature of |ns3|. It is found
+in ``src/contrib`` and not in the main tree. If you like this feature and
+would like to provide feedback on it, please email us.
+
+Values for |ns3| attributes can be stored in an ASCII or XML text file and
+loaded into a future simulation. This feature is known as the |ns3|
+ConfigStore. The ConfigStore code is in ``src/contrib/``. It is not yet
+main-tree code, because we are seeking some user feedback and experience with
+this.
+
+We can explore this system by using an example. Copy the ``csma-bridge.cc``
+file to the scratch directory:::
+
+ cp examples/csma-bridge.cc scratch/
+ ./waf
+
+Let's edit it to add the ConfigStore feature. First, add an include statement to
+include the contrib module, and then add these lines:::
+
+ #include "contrib-module.h"
+ ...
+ int main (...)
+ {
+ // setup topology
+
+ // Invoke just before entering Simulator::Run ()
+ ConfigStore config;
+ config.ConfigureDefaults ();
+ config.ConfigureAttributes ();
+
+ Simulator::Run ();
+ }
+
+There are three attributes that govern the behavior of the ConfigStore: "Mode",
+"Filename", and "FileFormat". The Mode (default "None") configures whether
+|ns3| should load configuration from a previously saved file (specify
+"Mode=Load") or save it to a file (specify "Mode=Save"). The Filename (default
+"") is where the ConfigStore should store its output data. The FileFormat
+(default "RawText") governs whether the ConfigStore format is Xml or RawText
+format.
+
+So, using the above modified program, try executing the following waf command
+and ::
+
+ ./waf --command-template="%s --ns3::ConfigStore::Filename=csma-bridge-config.xml
+ --ns3::ConfigStore::Mode=Save --ns3::ConfigStore::FileFormat=Xml" --run scratch/csma-bridge
+ @end example
+ @end smallformat
+ After running, you can open the csma-bridge-config.xml file and it will
+ display the configuration that was applied to your simulation; e.g.
+ @smallformat
+ @example
+ <?xml version="1.0" encoding="UTF-8"?>
+ <ns3>
+ <default name="ns3::V4Ping::Remote" value="102.102.102.102"/>
+ <default name="ns3::MsduStandardAggregator::MaxAmsduSize" value="7935"/>
+ <default name="ns3::EdcaTxopN::MinCw" value="31"/>
+ <default name="ns3::EdcaTxopN::MaxCw" value="1023"/>
+ <default name="ns3::EdcaTxopN::Aifsn" value="3"/>
+ <default name="ns3::QstaWifiMac::ProbeRequestTimeout" value="50000000ns"/>
+ <default name="ns3::QstaWifiMac::AssocRequestTimeout" value="500000000ns"/>
+ <default name="ns3::QstaWifiMac::MaxMissedBeacons" value="10"/>
+ <default name="ns3::QstaWifiMac::ActiveProbing" value="false"/>
+ ...
+
+This file can be archived with your simulation script and output data.
+
+While it is possible to generate a sample config file and lightly edit it to
+change a couple of values, there are cases where this process will not work
+because the same value on the same object can appear multiple times in the same
+automatically-generated configuration file under different configuration paths.
+
+As such, the best way to use this class is to use it to generate an initial
+configuration file, extract from that configuration file only the strictly
+necessary elements, and move these minimal elements to a new configuration file
+which can then safely be edited and loaded in a subsequent simulation run.
+
+When the ConfigStore object is instantiated, its attributes Filename, Mode, and
+FileFormat must be set, either via command-line or via program statements.
+
+As a more complicated example, let's assume that we want to read in a
+configuration of defaults from an input file named "input-defaults.xml", and
+write out the resulting attributes to a separate file called
+"output-attributes.xml". (Note-- to get this input xml file to begin with, it
+is sometimes helpful to run the program to generate an output xml file first,
+then hand-edit that file and re-input it for the next simulation run).::
+
+ #include "contrib-module.h"
+ ...
+ int main (...)
+ {
+
+ Config::SetDefault ("ns3::ConfigStore::Filename", StringValue ("input-defaults.xml"));
+ Config::SetDefault ("ns3::ConfigStore::Mode", StringValue ("Load"));
+ Config::SetDefault ("ns3::ConfigStore::FileFormat", StringValue ("Xml"));
+ ConfigStore inputConfig;
+ inputConfig.ConfigureDefaults ();
+
+ //
+ // Allow the user to override any of the defaults and the above Bind() at
+ // run-time, via command-line arguments
+ //
+ CommandLine cmd;
+ cmd.Parse (argc, argv);
+
+ // setup topology
+ ...
+
+ // Invoke just before entering Simulator::Run ()
+ Config::SetDefault ("ns3::ConfigStore::Filename", StringValue ("output-attributes.xml"));
+ Config::SetDefault ("ns3::ConfigStore::Mode", StringValue ("Save"));
+ ConfigStore outputConfig;
+ outputConfig.ConfigureAttributes ();
+ Simulator::Run ();
+ }
+
+GTK-based ConfigStore
++++++++++++++++++++++
+
+There is a GTK-based front end for the ConfigStore. This allows users to use a
+GUI to access and change variables. Screenshots of this feature are available
+in the `|ns3| Overview <http://www.nsnam.org/docs/ns-3-overview.pdf>`_
+presentation.
+
+To use this feature, one must install libgtk and libgtk-dev; an example
+Ubuntu installation command is:::
+
+ sudo apt-get install libgtk2.0-0 libgtk2.0-dev
+
+To check whether it is configured or not, check the output of the
+./waf configure step:::
+
+ ---- Summary of optional NS-3 features:
+ Threading Primitives : enabled
+ Real Time Simulator : enabled
+ GtkConfigStore : not enabled (library 'gtk+-2.0 >= 2.12' not found)
+
+In the above example, it was not enabled, so it cannot be used until a suitable
+version is installed and ./waf configure; ./waf is rerun.
+
+Usage is almost the same as the non-GTK-based version, but there
+are no ConfigStore attributes involved:::
+
+ // Invoke just before entering Simulator::Run ()
+ GtkConfigStore config;
+ config.ConfigureDefaults ();
+ config.ConfigureAttributes ();
+
+Now, when you run the script, a GUI should pop up, allowing you to open menus of
+attributes on different nodes/objects, and then launch the simulation execution
+when you are done.
+
+Future work
++++++++++++
+There are a couple of possible improvements:
+* save a unique version number with date and time at start of file
+* save rng initial seed somewhere.
+* make each RandomVariable serialize its own initial seed and re-read it later
+* add the default values
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/bridge.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,9 @@
+.. include:: replace.txt
+
+Bridge NetDevice
+----------------
+
+*Placeholder chapter*
+
+Some examples of the use of Bridge NetDevice can be found in ``examples/csma/``
+directory.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/callbacks.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,235 @@
+.. include:: replace.txt
+
+Callbacks
+---------
+
+Some new users to |ns3| are unfamiliar with an extensively used programming
+idiom used throughout the code: the *ns-3 callback*. This chapter provides some
+motivation on the callback, guidance on how to use it, and details on its
+implementation.
+
+Callbacks Motivation
+********************
+
+Consider that you have two simulation models A and B, and you wish to have them
+pass information between them during the simulation. One way that you can do
+that is that you can make A and B each explicitly knowledgeable about the other,
+so that they can invoke methods on each other::
+
+ class A {
+ public:
+ void ReceiveInput ( // parameters );
+ ...
+ }
+
+ (in another source file:)
+
+ class B {
+ public:
+ void DoSomething (void);
+ ...
+
+ private:
+ A* a_instance; // pointer to an A
+ }
+
+ void
+ B::DoSomething()
+ {
+ // Tell a_instance that something happened
+ a_instance->ReceiveInput ( // parameters);
+ ...
+ }
+
+This certainly works, but it has the drawback that it introduces a dependency on
+A and B to know about the other at compile time (this makes it harder to have
+independent compilation units in the simulator) and is not generalized; if in a
+later usage scenario, B needs to talk to a completely different C object, the
+source code for B needs to be changed to add a ``c_instance`` and so forth. It
+is easy to see that this is a brute force mechanism of communication that can
+lead to programming cruft in the models.
+
+This is not to say that objects should not know about one another if there is a
+hard dependency between them, but that often the model can be made more flexible
+if its interactions are less constrained at compile time.
+
+This is not an abstract problem for network simulation research, but rather it
+has been a source of problems in previous simulators, when researchers want to
+extend or modify the system to do different things (as they are apt to do in
+research). Consider, for example, a user who wants to add an IPsec security
+protocol sublayer between TCP and IP::
+
+ ------------ -----------
+ | TCP | | TCP |
+ ------------ -----------
+ | becomes -> |
+ ----------- -----------
+ | IP | | IPsec |
+ ----------- -----------
+ |
+ -----------
+ | IP |
+ -----------
+
+
+If the simulator has made assumptions, and hard coded into the code, that IP
+always talks to a transport protocol above, the user may be forced to hack the
+system to get the desired interconnections. This is clearly not an optimal way
+to design a generic simulator.
+
+Callbacks Background
+********************
+
+.. note:: Readers familiar with programming callbacks may skip this tutorial
+ section.
+
+The basic mechanism that allows one to address the problem above is known as a
+*callback*. The ultimate goal is to allow one piece of code to call a function
+(or method in C++) without any specific inter-module dependency.
+
+This ultimately means you need some kind of indirection -- you treat the address
+of the called function as a variable. This variable is called a
+pointer-to-function variable. The relationship between function and
+pointer-to-function pointer is really no different that that of object and
+pointer-to-object.
+
+In C the canonical example of a pointer-to-function is a
+pointer-to-function-returning-integer (PFI). For a PFI taking one int parameter,
+this could be declared like,::
+
+ int (*pfi)(int arg) = 0;
+
+What you get from this is a variable named simply ``pfi`` that is initialized to
+the value 0. If you want to initialize this pointer to something meaningful, you
+have to have a function with a matching signature. In this case::
+
+ int MyFunction (int arg) {}
+
+If you have this target, you can initialize the variable to point to your
+function like::
+
+ pfi = MyFunction;
+
+You can then call MyFunction indirectly using the more suggestive form of the
+call::
+
+ int result = (*pfi) (1234);
+
+This is suggestive since it looks like you are dereferencing the function
+pointer just like you would dereference any pointer. Typically, however, people
+take advantage of the fact that the compiler knows what is going on and will
+just use a shorter form::
+
+ int result = pfi (1234);
+
+Notice that the function pointer obeys value semantics, so you can pass it
+around like any other value. Typically, when you use an asynchronous interface
+you will pass some entity like this to a function which will perform an action
+and *call back* to let you know it completed. It calls back by following the
+indirection and executing the provided function.
+
+In C++ you have the added complexity of objects. The analogy with the PFI above
+means you have a pointer to a member function returning an int (PMI) instead of
+the pointer to function returning an int (PFI).
+
+The declaration of the variable providing the indirection looks only slightly
+different::
+
+ int (MyClass::*pmi) (int arg) = 0;
+
+This declares a variable named ``pmi`` just as the previous example declared a
+variable named ``pfi``. Since the will be to call a method of an instance of a
+particular class, one must declare that method in a class::
+
+ class MyClass {
+ public:
+ int MyMethod (int arg);
+ };
+
+Given this class declaration, one would then initialize that variable like
+this::
+
+ pmi = &MyClass::MyMethod;
+
+This assigns the address of the code implementing the method to the variable,
+completing the indirection. In order to call a method, the code needs a ``this``
+pointer. This, in turn, means there must be an object of MyClass to refer to. A
+simplistic example of this is just calling a method indirectly (think virtual
+function)::
+
+ int (MyClass::*pmi) (int arg) = 0; // Declare a PMI
+ pmi = &MyClass::MyMethod; // Point at the implementation code
+
+ MyClass myClass; // Need an instance of the class
+ (myClass.*pmi) (1234); // Call the method with an object ptr
+
+Just like in the C example, you can use this in an asynchronous call to another
+module which will *call back* using a method and an object pointer. The
+straightforward extension one might consider is to pass a pointer to the object
+and the PMI variable. The module would just do::
+
+ (*objectPtr.*pmi) (1234);
+
+to execute the callback on the desired object.
+
+One might ask at this time, *what's the point*? The called module will have to
+understand the concrete type of the calling object in order to properly make the
+callback. Why not just accept this, pass the correctly typed object pointer and
+do ``object->Method(1234)`` in the code instead of the callback? This is
+precisely the problem described above. What is needed is a way to decouple the
+calling function from the called class completely. This requirement led to the
+development of the *Functor*.
+
+A functor is the outgrowth of something invented in the 1960s called a closure.
+It is basically just a packaged-up function call, possibly with some state.
+
+A functor has two parts, a specific part and a generic part, related through
+inheritance. The calling code (the code that executes the callback) will execute
+a generic overloaded ``operator ()`` of a generic functor to cause the callback
+to be called. The called code (the code that wants to be called back) will have
+to provide a specialized implementation of the ``operator ()`` that performs the
+class-specific work that caused the close-coupling problem above.
+
+With the specific functor and its overloaded ``operator ()`` created, the called
+code then gives the specialized code to the module that will execute the
+callback (the calling code).
+
+The calling code will take a generic functor as a parameter, so an implicit cast
+is done in the function call to convert the specific functor to a generic
+functor. This means that the calling module just needs to understand the
+generic functor type. It is decoupled from the calling code completely.
+
+The information one needs to make a specific functor is the object pointer and
+the pointer-to-method address.
+
+The essence of what needs to happen is that the system declares a generic part
+of the functor::
+
+ template <typename T>
+ class Functor
+ {
+ public:
+ virtual void operator() (T arg) = 0;
+ };
+
+The caller defines a specific part of the functor that really is just there to
+implement the specific ``operator()`` method::
+
+ template <typename T, typename ARG>
+ class SpecificFunctor : public Functor
+ {
+ public:
+ SpecificFunctor(T* p, int (T::*_pmi)(ARG arg))
+ {
+ m_p = p;
+ m_pmi = pmi;
+ }
+
+ virtual int operator() (ARG arg)
+ {
+ (*m_p.*m_pmi)(arg);
+ }
+ private:
+ void (T::*m_pmi)(ARG arg);
+ T* m_p;
+ };
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/core.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,17 @@
+Core
+----
+
+.. toctree::
+
+ random-variables
+ callbacks
+ object-model
+ attributes
+ object-names
+ logging
+ tracing
+ realtime
+ distributed
+ packets
+ helpers
+ python
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/csma.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,305 @@
+.. include:: replace.txt
+
+CSMA NetDevice
+--------------
+
+This is the introduction to CSMA NetDevice chapter, to complement the Csma model
+doxygen.
+
+Overview of the CSMA model
+**************************
+
+The |ns3| CSMA device models a simple bus network in the spirit of Ethernet.
+Although it does not model any real physical network you could ever build or
+buy, it does provide some very useful functionality.
+
+Typically when one thinks of a bus network Ethernet or IEEE 802.3 comes to mind.
+Ethernet uses CSMA/CD (Carrier Sense Multiple Access with Collision Detection
+with exponentially increasing backoff to contend for the shared transmission
+medium. The |ns3| CSMA device models only a portion of this process, using the
+nature of the globally available channel to provide instantaneous (faster than
+light) carrier sense and priority-based collision "avoidance." Collisions in the
+sense of Ethernet never happen and so the |ns3| CSMA device does not model
+collision detection, nor will any transmission in progress be "jammed."
+
+CSMA Layer Model
+++++++++++++++++
+
+There are a number of conventions in use for describing layered communications
+architectures in the literature and in textbooks. The most common layering model
+is the ISO seven layer reference model. In this view the CsmaNetDevice and
+CsmaChannel pair occupies the lowest two layers -- at the physical (layer one),
+and data link (layer two) positions. Another important reference model is that
+specified by RFC 1122, "Requirements for Internet Hosts -- Communication
+Layers." In this view the CsmaNetDevice and CsmaChannel pair occupies the lowest
+layer -- the link layer. There is also a seemingly endless litany of alternative
+descriptions found in textbooks and in the literature. We adopt the naming
+conventions used in the IEEE 802 standards which speak of LLC, MAC, MII and PHY
+layering. These acronyms are defined as:
+
+* LLC: Logical Link Control;
+* MAC: Media Access Control;
+* MII: Media Independent Interface;
+* PHY: Physical Layer.
+
+In this case the *LLC* and *MAC* are sublayers of the OSI data link layer and
+the *MII* and *PHY* are sublayers of the OSI physical layer.
+
+The "top" of the CSMA device defines the transition from the network layer to
+the data link layer. This transition is performed by higher layers by calling
+either CsmaNetDevice::Send or CsmaNetDevice::SendFrom.
+
+In contrast to the IEEE 802.3 standards, there is no precisely specified PHY in
+the CSMA model in the sense of wire types, signals or pinouts. The "bottom"
+interface of the CsmaNetDevice can be thought of as as a kind of Media
+Independent Interface (MII) as seen in the "Fast Ethernet" (IEEE 802.3u)
+specifications. This MII interface fits into a corresponding media independent
+interface on the CsmaChannel. You will not find the equivalent of a 10BASE-T or
+a 1000BASE-LX PHY.
+
+The CsmaNetDevice calls the CsmaChannel through a media independent interface.
+There is a method defined to tell the channel when to start "wiggling the wires"
+using the method CsmaChannel::TransmitStart, and a method to tell the channel
+when the transmission process is done and the channel should begin propagating
+the last bit across the "wire": CsmaChannel::TransmitEnd.
+
+When the TransmitEnd method is executed, the channel will model a single uniform
+signal propagation delay in the medium and deliver copes of the packet to each
+of the devices attached to the packet via the CsmaNetDevice::Receive method.
+
+There is a "pin" in the device media independent interface corresponding to
+"COL" (collision). The state of the channel may be sensed by calling
+CsmaChannel::GetState. Each device will look at this "pin" before starting a
+send and will perform appropriate backoff operations if required.
+
+Properly received packets are forwarded up to higher levels from the
+CsmaNetDevice via a callback mechanism. The callback function is initialized by
+the higher layer (when the net device is attached) using
+CsmaNetDevice::SetReceiveCallback and is invoked upon "proper" reception of a
+packet by the net device in order to forward the packet up
+the protocol stack.
+
+CSMA Channel Model
+******************
+
+The class CsmaChannel models the actual transmission medium. There is no fixed
+limit for the number of devices connected to the channel. The CsmaChannel models
+a data rate and a speed-of-light delay which can be accessed via the attributes
+"DataRate" and "Delay" respectively. The data rate provided to the channel is
+used to set the data rates used by the transmitter sections of the CSMA devices
+connected to the channel. There is no way to independently set data rates in the
+devices. Since the data rate is only used to calculate a delay time, there is no
+limitation (other than by the data type holding the value) on the speed at which
+CSMA channels and devices can operate; and no restriction based on any kind of
+PHY characteristics.
+
+The CsmaChannel has three states, ``IDLE``, ``TRANSMITTING`` and
+``PROPAGATING``. These three states are "seen" instantaneously by all devices on
+the channel. By this we mean that if one device begins or ends a simulated
+transmission, all devices on the channel are @emph{immediately} aware of the
+change in state. There is no time during which one device may see an ``IDLE``
+channel while another device physically further away in the collision domain may
+have begun transmitting with the associated signals not propagated down the
+channel to other devices. Thus there is no need for collision detection in the
+CsmaChannel model and it is not implemented in any way.
+
+We do, as the name indicates, have a Carrier Sense aspect to the model. Since
+the simulator is single threaded, access to the common channel will be
+serialized by the simulator. This provides a deterministic mechanism for
+contending for the channel. The channel is allocated (transitioned from state
+``IDLE`` to state ``TRANSMITTING``) on a first-come first-served basis.
+The channel always goes through a three state process:::
+
+ IDLE -> TRANSMITTING -> PROPAGATING -> IDLE
+
+The ``TRANSMITTING`` state models the time during which the source net device is
+actually wiggling the signals on the wire. The ``PROPAGATING`` state models the
+time after the last bit was sent, when the signal is propagating down the wire
+to the "far end."
+
+The transition to the ``TRANSMITTING`` state is driven by a call to
+CsmaChannel::TransmitStart which is called by the net device that transmits the
+packet. It is the responsibility of that device to end the transmission with a
+call to CsmaChannel::TransmitEnd at the appropriate simulation time that
+reflects the time elapsed to put all of the packet bits on the wire. When
+TransmitEnd is called, the channel schedules an event corresponding to a single
+speed-of-light delay. This delay applies to all net devices on the channel
+identically. You can think of a symmetrical hub in which the packet bits
+propagate to a central location and then back out equal length cables to the
+other devices on the channel. The single "speed of light" delay then corresponds
+to the time it takes for: 1) a signal to propagate from one CsmaNetDevice
+through its cable to the hub; plus 2) the time it takes for the hub to forward
+the packet out a port; plus 3) the time it takes for the signal in question to
+propagate to the destination net device.
+
+The CsmaChannel models a broadcast medium so the packet is delivered to all of
+the devices on the channel (including the source) at the end of the propagation
+time. It is the responsibility of the sending device to determine whether or not
+it receives a packet broadcast over the channel.
+
+The CsmaChannel provides following Attributes:
+
+* DataRate: The bitrate for packet transmission on connected devices;
+* Delay: The speed of light transmission delay for the channel.
+
+CSMA Net Device Model
+*********************
+
+The CSMA network device appears somewhat like an Ethernet device. The
+CsmaNetDevice provides following Attributes:
+
+* Address: The Mac48Address of the device;
+* SendEnable: Enable packet transmission if true;
+* ReceiveEnable: Enable packet reception if true;
+* EncapsulationMode: Type of link layer encapsulation to use;
+* RxErrorModel: The receive error model;
+* TxQueue: The transmit queue used by the device;
+* InterframeGap: The optional time to wait between "frames";
+* Rx: A trace source for received packets;
+* Drop: A trace source for dropped packets.
+
+The CsmaNetDevice supports the assignment of a "receive error model." This is an
+ErrorModel object that is used to simulate data corruption on the link.
+
+Packets sent over the CsmaNetDevice are always routed through the transmit queue
+to provide a trace hook for packets sent out over the network. This transmit
+queue can be set (via attribute) to model different queuing strategies.
+
+Also configurable by attribute is the encapsulation method used by the device.
+Every packet gets an EthernetHeader that includes the destination and source MAC
+addresses, and a length/type field. Every packet also gets an EthernetTrailer
+which includes the FCS. Data in the packet may be encapsulated in different
+ways.
+
+By default, or by setting the "EncapsulationMode" attribute to "Dix", the
+encapsulation is according to the DEC, Intel, Xerox standard. This is sometimes
+called EthernetII framing and is the familiar destination MAC, source MAC,
+EtherType, Data, CRC format.
+
+If the "EncapsulationMode" attribute is set to "Llc", the encapsulation is by
+LLC SNAP. In this case, a SNAP header is added that contains the EtherType (IP
+or ARP).
+
+The other implemented encapsulation modes are IP_ARP (set "EncapsulationMode" to
+"IpArp") in which the length type of the Ethernet header receives the protocol
+number of the packet; or ETHERNET_V1 (set "EncapsulationMode" to "EthernetV1")
+in which the length type of the Ethernet header receives the length of the
+packet. A "Raw" encapsulation mode is defined but not implemented -- use of the
+RAW mode results in an assertion.
+
+Note that all net devices on a channel must be set to the same encapsulation
+mode for correct results. The encapsulation mode is not sensed at the receiver.
+
+The CsmaNetDevice implements a random exponential backoff algorithm that is
+executed if the channel is determined to be busy (``TRANSMITTING`` or
+``PPROPAGATING``) when the device wants to start propagating. This results in a
+random delay of up to pow (2, retries) - 1 microseconds before a retry is
+attempted. The default maximum number of retries is 1000.
+
+Using the CsmaNetDevice
+***********************
+
+The CSMA net devices and channels are typically created and configured using the
+associated ``CsmaHelper`` object. The various |ns3| device helpers generally
+work in a similar way, and their use is seen in many of our example programs.
+
+The conceptual model of interest is that of a bare computer "husk" into which
+you plug net devices. The bare computers are created using a ``NodeContainer``
+helper. You just ask this helper to create as many computers (we call them
+``Nodes``) as you need on your network:::
+
+ NodeContainer csmaNodes;
+ csmaNodes.Create (nCsmaNodes);
+
+Once you have your nodes, you need to instantiate a ``CsmaHelper`` and set any
+attributes you may want to change.::
+
+ CsmaHelper csma;
+ csma.SetChannelAttribute ("DataRate", StringValue ("100Mbps"));
+ csma.SetChannelAttribute ("Delay", TimeValue (NanoSeconds (6560)));
+
+ csma.SetDeviceAttribute ("EncapsulationMode", StringValue ("Dix"));
+ csma.SetDeviceAttribute ("FrameSize", UintegerValue (2000));
+
+Once the attributes are set, all that remains is to create the devices and
+install them on the required nodes, and to connect the devices together using a
+CSMA channel. When we create the net devices, we add them to a container to
+allow you to use them in the future. This all takes just one line of code.::
+
+ NetDeviceContainer csmaDevices = csma.Install (csmaNodes);
+
+CSMA Tracing
+************
+
+Like all |ns3| devices, the CSMA Model provides a number of trace sources.
+These trace sources can be hooked using your own custom trace code, or you can
+use our helper functions to arrange for tracing to be enabled on devices you
+specify.
+
+Upper-Level (MAC) Hooks
++++++++++++++++++++++++
+
+From the point of view of tracing in the net device, there are several
+interesting points to insert trace hooks. A convention inherited from other
+simulators is that packets destined for transmission onto attached networks pass
+through a single "transmit queue" in the net device. We provide trace hooks at
+this point in packet flow, which corresponds (abstractly) only to a transition
+from the network to data link layer, and call them collectively the device MAC
+hooks.
+
+When a packet is sent to the CSMA net device for transmission it always passes
+through the transmit queue. The transmit queue in the CsmaNetDevice inherits
+from Queue, and therefore inherits three trace sources:
+
+* An Enqueue operation source (see Queue::m_traceEnqueue);
+* A Dequeue operation source (see Queue::m_traceDequeue);
+* A Drop operation source (see Queue::m_traceDrop).
+
+The upper-level (MAC) trace hooks for the CsmaNetDevice are, in fact, exactly
+these three trace sources on the single transmit queue of the device.
+
+The m_traceEnqueue event is triggered when a packet is placed on the transmit
+queue. This happens at the time that CsmaNetDevice::Send or
+CsmaNetDevice::SendFrom is called by a higher layer to queue a packet for
+transmission.
+
+The m_traceDequeue event is triggered when a packet is removed from the transmit
+queue. Dequeues from the transmit queue can happen in three situations: 1) If
+the underlying channel is idle when the CsmaNetDevice::Send or
+CsmaNetDevice::SendFrom is called, a packet is dequeued from the transmit queue
+and immediately transmitted; 2) If the underlying channel is idle, a packet may
+be dequeued and immediately transmitted in an internal TransmitCompleteEvent
+that functions much like a transmit complete interrupt service routine; or 3)
+from the random exponential backoff handler if a timeout is detected.
+
+Case (3) implies that a packet is dequeued from the transmit queue if it is
+unable to be transmitted according to the backoff rules. It is important to
+understand that this will appear as a Dequeued packet and it is easy to
+incorrectly assume that the packet was transmitted since it passed through the
+transmit queue. In fact, a packet is actually dropped by the net device in this
+case. The reason for this behavior is due to the definition of the Queue Drop
+event. The m_traceDrop event is, by definition, fired when a packet cannot be
+enqueued on the transmit queue because it is full. This event only fires if the
+queue is full and we do not overload this event to indicate that the CsmaChannel
+is "full."
+
+Lower-Level (PHY) Hooks
++++++++++++++++++++++++
+
+Similar to the upper level trace hooks, there are trace hooks available at the
+lower levels of the net device. We call these the PHY hooks. These events fire
+from the device methods that talk directly to the CsmaChannel.
+
+The trace source m_dropTrace is called to indicate a packet that is dropped by
+the device. This happens in two cases: First, if the receive side of the net
+device is not enabled (see CsmaNetDevice::m_receiveEnable and the associated
+attribute "ReceiveEnable").
+
+The m_dropTrace is also used to indicate that a packet was discarded as corrupt
+if a receive error model is used (see CsmaNetDevice::m_receiveErrorModel and the
+associated attribute "ReceiveErrorModel").
+
+The other low-level trace source fires on reception of an accepted packet (see
+CsmaNetDevice::m_rxTrace). A packet is accepted if it is destined for the
+broadcast address, a multicast address, or to the MAC address assigned to the
+net device.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/distributed.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,212 @@
+.. include:: replace.txt
+
+Distributed
+-----------
+
+Parallel and distributed discrete event simulation allows the execution of a
+single simulation program on multiple processors. By splitting up the simulation
+into logical processes, LPs, each LP can be executed by a different processor.
+This simulation methodology enables very large-scale simulations by leveraging
+increased processing power and memory availability. In order to ensure proper
+execution of a distributed simulation, message passing between LPs is required.
+To support distributed simulation in |ns3|, the standard Message Passing
+Interface (MPI) is used, along with a new distributed simulator class.
+Currently, dividing a simulation for distributed purposes in |ns3| can only occur
+across point-to-point links.
+
+Current Implementation Details
+******************************
+
+During the course of a distributed simulation, many packets must cross simulator
+boundaries. In other words, a packet that originated on one LP is destined for a
+different LP, and in order to make this transition, a message containing the
+packet contents must be sent to the remote LP. Upon receiving this message, the
+remote LP can rebuild the packet and proceed as normal. The process of sending
+an receiving messages between LPs is handled easily by the new MPI interface in
+|ns3|.
+
+Along with simple message passing between LPs, a distributed simulator is used
+on each LP to determine which events to process. It is important to process
+events in time-stamped order to ensure proper simulation execution. If a LP
+receives a message containing an event from the past, clearly this is an issue,
+since this event could change other events which have already been executed. To
+address this problem, a conservative synchronization algorithm with lookahead is
+used in |ns3|. For more information on different synchronization approaches and
+parallel and distributed simulation in general, please refer to "Parallel and
+Distributed Simulation Systems" by Richard Fujimoto.
+
+Remote point-to-point links
++++++++++++++++++++++++++++
+
+As described in the introduction, dividing a simulation for distributed purposes
+in |ns3| currently can only occur across point-to-point links; therefore, the
+idea of remote point-to-point links is very important for distributed simulation
+in |ns3|. When a point-to-point link is installed, connecting two nodes, the
+point-to-point helper checks the system id, or rank, of both nodes. The rank
+should be assigned during node creation for distributed simulation and is
+intended to signify on which LP a node belongs. If the two nodes are on the same
+rank, a regular point-to-point link is created. If, however, the two nodes are
+on different ranks, then these nodes are intended for different LPs, and a
+remote point-to-point link is used. If a packet is to be sent across a remote
+point-to-point link, MPI is used to send the message to the remote LP.
+
+Distributing the topology
++++++++++++++++++++++++++
+
+Currently, the full topology is created on each rank, regardless of the
+individual node system ids. Only the applications are specific to a rank. For
+example, consider node 1 on LP 1 and node 2 on LP 2, with a traffic generator on
+node 1. Both node 1 and node 2 will be created on both LP1 and LP2; however, the
+traffic generator will only be installed on LP1. While this is not optimal for
+memory efficiency, it does simplify routing, since all current routing
+implementations in |ns3| will work with distributed simulation.
+
+Running Distributed Simulations
+*******************************
+
+Prerequisites
++++++++++++++
+
+Ensure that MPI is installed, as well as mpic++. In Ubuntu repositories,
+these are openmpi-bin, openmpi-common, openmpi-doc, libopenmpi-dev. In
+Fedora, these are openmpi and openmpi-devel.
+
+Note:
+
+There is a conflict on some Fedora systems between libotf and openmpi. A
+possible "quick-fix" is to yum remove libotf before installing openmpi.
+This will remove conflict, but it will also remove emacs. Alternatively,
+these steps could be followed to resolve the conflict:::
+
+ 1) Rename the tiny otfdump which emacs says it needs:
+
+ mv /usr/bin/otfdump /usr/bin/otfdump.emacs-version
+
+ 2) Manually resolve openmpi dependencies:
+
+ sudo yum install libgfortran libtorque numactl
+
+ 3) Download rpm packages:
+
+ openmpi-1.3.1-1.fc11.i586.rpm
+ openmpi-devel-1.3.1-1.fc11.i586.rpm
+ openmpi-libs-1.3.1-1.fc11.i586.rpm
+ openmpi-vt-1.3.1-1.fc11.i586.rpm
+
+ from
+
+ http://mirrors.kernel.org/fedora/releases/11/Everything/i386/os/Packages/
+
+ 4) Force the packages in:
+
+ sudo rpm -ivh --force openmpi-1.3.1-1.fc11.i586.rpm
+ openmpi-libs-1.3.1-1.fc11.i586.rpm openmpi-devel-1.3.1-1.fc11.i586.rpm
+ openmpi-vt-1.3.1-1.fc11.i586.rpm
+
+Also, it may be necessary to add the openmpi bin directory to PATH in order to
+execute mpic++ and mpirun from the command line. Alternatively, the full path to
+these executables can be used. Finally, if openmpi complains about the inability
+to open shared libraries, such as libmpi_cxx.so.0, it may be necessary to add
+the openmpi lib directory to LD_LIBRARY_PATH.
+
+Building and Running Examples
++++++++++++++++++++++++++++++
+
+If you already built |ns3| without MPI enabled, you must re-build:::
+
+ ./waf distclean
+
+Configure |ns3| with the --enable-mpi option:::
+
+ ./waf -d debug configure --enable-mpi
+
+Ensure that MPI is enabled by checking the optional features shown from the
+output of configure.
+
+Next, build |ns3|:
+
+ ./waf
+
+After building |ns3| with mpi enabled, the example programs are now ready to run
+with mpirun. Here are a few examples (from the root |ns3| directory):::
+
+ mpirun -np 2 ./waf --run simple-distributed
+ mpirun -np 4 -machinefile mpihosts ./waf --run 'nms-udp-nix --LAN=2 --CN=4 --nix=1'
+
+The np switch is the number of logical processors to use. The machinefile switch
+is which machines to use. In order to use machinefile, the target file must
+exist (in this case mpihosts). This can simply contain something like:::
+
+ localhost
+ localhost
+ localhost
+ ...
+
+Or if you have a cluster of machines, you can name them.
+
+NOTE: Some users have experienced issues using mpirun and waf together. An
+alternative way to run distributed examples is shown below:::
+
+ ./waf shell
+ cd build/debug
+ mpirun -np 2 examples/mpi/simple-distributed
+
+Creating custom topologies
+++++++++++++++++++++++++++
+
+The example programs in examples/mpi give a good idea of how to create different
+topologies for distributed simulation. The main points are assigning system ids
+to individual nodes, creating point-to-point links where the simulation should
+be divided, and installing applications only on the LP associated with the
+target node.
+
+Assigning system ids to nodes is simple and can be handled two different ways.
+First, a NodeContainer can be used to create the nodes and assign system ids:::
+
+ NodeContainer nodes;
+ nodes.Create (5, 1); // Creates 5 nodes with system id 1.
+
+Alternatively, nodes can be created individually, assigned system ids, and added
+to a NodeContainer. This is useful if a NodeContainer holds nodes with different
+system ids:::
+
+ NodeContainer nodes;
+ Ptr<Node> node1 = CreateObject<Node> (0); // Create node1 with system id 0
+ Ptr<Node> node2 = CreateObject<Node> (1); // Create node2 with system id 1
+ nodes.Add (node1);
+ nodes.Add (node2);
+
+Next, where the simulation is divided is determined by the placement of
+point-to-point links. If a point-to-point link is created between two
+nodes with different system ids, a remote point-to-point link is created,
+as described in :ref:`Current Implementation Details`.
+
+Finally, installing applications only on the LP associated with the target node
+is very important. For example, if a traffic generator is to be placed on node
+0, which is on LP0, only LP0 should install this application. This is easily
+accomplished by first checking the simulator system id, and ensuring that it
+matches the system id of the target node before installing the application.
+
+Tracing During Distributed Simulations
+**************************************
+
+Depending on the system id (rank) of the simulator, the information traced will
+be different, since traffic originating on one simulator is not seen by another
+simulator until it reaches nodes specific to that simulator. The easiest way to
+keep track of different traces is to just name the trace files or pcaps
+differently, based on the system id of the simulator. For example, something
+like this should work well, assuming all of these local variables were
+previously defined:::
+
+ if (MpiInterface::GetSystemId () == 0)
+ {
+ pointToPoint.EnablePcapAll ("distributed-rank0");
+ phy.EnablePcap ("distributed-rank0", apDevices.Get (0));
+ csma.EnablePcap ("distributed-rank0", csmaDevices.Get (0), true);
+ }
+ else if (MpiInterface::GetSystemId () == 1)
+ {
+ pointToPoint.EnablePcapAll ("distributed-rank1");
+ phy.EnablePcap ("distributed-rank1", apDevices.Get (0));
+ csma.EnablePcap ("distributed-rank1", csmaDevices.Get (0), true);
+ }
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/emu.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,268 @@
+.. include:: replace.txt
+
+Emu NetDevice
+-------------
+
+Behavior
+********
+
+The ``Emu`` net device allows a simulation node to send and receive packets over
+a real network. The emulated net device relies on a specified interface being in
+promiscuous mode. It opens a raw socket and binds to that interface. We perform
+MAC spoofing to separate simulation network traffic from other
+network traffic that may be flowing to and from the host.
+
+One can use the ``Emu`` net device in a testbed situation where the host on
+which the simulation is running has a specific interface of interest which
+drives the testbed hardware. You would also need to set this specific interface
+into promiscuous mode and provide an appropriate device name to the |ns3|
+emulated net device. An example of this environment is the ORBIT testbed as
+described above.
+
+The ``Emu`` net device only works if the underlying interface is up and in
+promiscuous mode. Packets will be sent out over the device, but we use MAC
+spoofing. The MAC addresses will be generated (by default) using the
+Organizationally Unique Identifier (OUI) 00:00:00 as a base. This vendor code is
+not assigned to any organization and so should not conflict with any real
+hardware.
+
+It is always up to the user to determine that using these MAC addresses is okay
+on your network and won't conflict with anything else (including another
+simulation using ``Emu`` devices) on your network. If you are using the emulated
+net device in separate simulations you must consider global MAC address
+assignment issues and ensure that MAC addresses are unique across all
+simulations. The emulated net device respects the MAC address provided in the
+``SetAddress`` method so you can do this manually. For larger simulations, you
+may want to set the OUI in the MAC address allocation function.
+
+IP addresses corresponding to the emulated net devices are the addresses
+generated in the simulation, which are generated in the usual way via helper
+functions. Since we are using MAC spoofing, there will not be a conflict between
+|ns3| network stacks and any native network stacks.
+
+The emulated net device comes with a helper function as all |ns3| devices do.
+One unique aspect is that there is no channel associated with the underlying
+medium. We really have no idea what this external medium is, and so have not
+made an effort to model it abstractly. The primary thing to be aware of is the
+implication this has for IPv4 global routing. The global router module attempts
+to walk the channels looking for adjacent networks. Since there is no channel,
+the global router will be unable to do this and you must then use a dynamic
+routing protocol such as OLSR to include routing in ``Emu``-based networks.
+
+Usage
+*****
+
+Any mixing of |ns3| objects with real objects will typically require that
+|ns3| compute checksums in its protocols. By default, checksums are not
+computed by |ns3|. To enable checksums (e.g. UDP, TCP, IP), users must set
+the attribute ``ChecksumEnabled`` to true, such as follows:::
+
+ GlobalValue::Bind ("ChecksumEnabled", BooleanValue (true));
+
+The usage of the ``Emu`` net device is straightforward once the network of
+simulations has been configured. Since most of the work involved in working with
+this device is in network configuration before even starting a simulation, you
+may want to take a moment to review a couple of HOWTO pages on the |ns3| wiki
+that describe how to set up a virtual test network using VMware and how to run a
+set of example (client server) simulations that use ``Emu`` net devices.
+
+* `<http://www.nsnam.org/wiki/index.php/HOWTO_use_VMware_to_set_up_virtual_networks_(Windows)>`_
+* `<http://www.nsnam.org/wiki/index.php/HOWTO_use_ns-3_scripts_to_drive_real_hardware_(experimental)>`_
+
+Once you are over the configuration hurdle, the script changes required to use
+an ``Emu`` device are trivial. The main structural difference is that you will
+need to create an |ns3| simulation script for each node. In the case of the
+HOWTOs above, there is one client script and one server script. The only
+"challenge" is to get the addresses set correctly.
+
+Just as with all other |ns3| net devices, we provide a helper class for the
+``Emu`` net device. The following code snippet illustrates how one would declare
+an EmuHelper and use it to set the "DeviceName" attribute to "eth1" and install
+``Emu`` devices on a group of nodes. You would do this on both the client and
+server side in the case of the HOWTO seen above.::
+
+ EmuHelper emu;
+ emu.SetAttribute ("DeviceName", StringValue ("eth1"));
+ NetDeviceContainer d = emu.Install (n);
+
+The only other change that may be required is to make sure that the address
+spaces (MAC and IP) on the client and server simulations are compatible. First
+the MAC address is set to a unique well-known value in both places (illustrated
+here for one side).::
+
+ //
+ // We've got the devices in place. Since we're using MAC address
+ // spoofing under the sheets, we need to make sure that the MAC addresses
+ // we have assigned to our devices are unique. Ns-3 will happily
+ // automatically assign the same MAC address to the devices in both halves
+ // of our two-script pair, so let's go ahead and just manually change them
+ // to something we ensure is unique.
+ //
+ Ptr<NetDevice> nd = d.Get (0);
+ Ptr<EmuNetDevice> ed = nd->GetObject<EmuNetDevice> ();
+ ed->SetAddress ("00:00:00:00:00:02");
+
+And then the IP address of the client or server is set in the usual way using
+helpers.::
+
+ //
+ // We've got the "hardware" in place. Now we need to add IP addresses.
+ // This is the server half of a two-script pair. We need to make sure
+ // that the addressing in both of these applications is consistent, so
+ // we use provide an initial address in both cases. Here, the client
+ // will reside on one machine running ns-3 with one node having ns-3
+ // with IP address "10.1.1.2" and talk to a server script running in
+ // another ns-3 on another computer that has an ns-3 node with IP
+ // address "10.1.1.3"
+ //
+ Ipv4AddressHelper ipv4;
+ ipv4.SetBase ("10.1.1.0", "255.255.255.0", "0.0.0.2");
+ Ipv4InterfaceContainer i = ipv4.Assign (d);
+
+You will use application helpers to generate traffic exactly as you do in any
+|ns3| simulation script. Note that the server address shown below in a snippet
+from the client, must correspond to the IP address assigned to the server node
+similarly to the snippet above.::
+
+ uint32_t packetSize = 1024;
+ uint32_t maxPacketCount = 2000;
+ Time interPacketInterval = Seconds (0.001);
+ UdpEchoClientHelper client ("10.1.1.3", 9);
+ client.SetAttribute ("MaxPackets", UintegerValue (maxPacketCount));
+ client.SetAttribute ("Interval", TimeValue (interPacketInterval));
+ client.SetAttribute ("PacketSize", UintegerValue (packetSize));
+ ApplicationContainer apps = client.Install (n.Get (0));
+ apps.Start (Seconds (1.0));
+ apps.Stop (Seconds (2.0));
+
+The ``Emu`` net device and helper provide access to ASCII and pcap tracing
+functionality just as other |ns3| net devices to. You enable tracing similarly
+to these other net devices:::
+
+ EmuHelper::EnablePcapAll ("emu-udp-echo-client");
+
+To see an example of a client script using the ``Emu`` net device, see
+``examples/emu-udp-echo-client.cc`` and ``examples/emu-udp-echo-server.cc``
+in the repository `<http://code.nsnam.org/craigdo/ns-3-emu/>`_.
+
+Implementation
+**************
+
+Perhaps the most unusual part of the ``Emu`` and ``Tap`` device implementation
+relates to the requirement for executing some of the code with super-user
+permissions. Rather than force the user to execute the entire simulation as
+root, we provide a small "creator" program that runs as root and does any
+required high-permission sockets work.
+
+We do a similar thing for both the ``Emu`` and the ``Tap`` devices. The
+high-level view is that the ``CreateSocket`` method creates a local interprocess
+(Unix) socket, forks, and executes the small creation program. The small
+program, which runs as suid root, creates a raw socket and sends back the raw
+socket file descriptor over the Unix socket that is passed to it as a parameter.
+The raw socket is passed as a control message (sometimes called ancillary data)
+of type SCM_RIGHTS.
+
+The ``Emu`` net device uses the |ns3| threading and multithreaded real-time
+scheduler extensions. The interesting work in the ``Emu`` device is done when
+the net device is started (``EmuNetDevice::StartDevice ()``). An attribute
+("Start") provides a simulation time at which to spin up the net device. At this
+specified time (which defaults to t=0), the socket creation function is called
+and executes as described above. You may also specify a time at which to stop
+the device using the "Stop" attribute.
+
+Once the (promiscuous mode) socket is created, we bind it to an interface name
+also provided as an attribute ("DeviceName") that is stored internally as
+``m_deviceName``:::
+
+ struct ifreq ifr;
+ bzero (&ifr, sizeof(ifr));
+ strncpy ((char *)ifr.ifr_name, m_deviceName.c_str (), IFNAMSIZ);
+
+ int32_t rc = ioctl (m_sock, SIOCGIFINDEX, &ifr);
+
+ struct sockaddr_ll ll;
+ bzero (&ll, sizeof(ll));
+
+ ll.sll_family = AF_PACKET;
+ ll.sll_ifindex = m_sll_ifindex;
+ ll.sll_protocol = htons(ETH_P_ALL);
+
+ rc = bind (m_sock, (struct sockaddr *)&ll, sizeof (ll));
+
+After the promiscuous raw socket is set up, a separate thread is spawned to do
+reads from that socket and the link state is set to ``Up``.::
+
+ m_readThread = Create<SystemThread> (
+ MakeCallback (&EmuNetDevice::ReadThread, this));
+ m_readThread->Start ();
+
+ NotifyLinkUp ();
+
+The ``EmuNetDevice::ReadThread`` function basically just sits in an infinite
+loop reading from the promiscuous mode raw socket and scheduling packet
+receptions using the real-time simulator extensions.::
+
+ for (;;)
+ {
+ ...
+
+ len = recvfrom (m_sock, buf, bufferSize, 0, (struct sockaddr *)&addr,
+ &addrSize);
+
+ ...
+
+ DynamicCast<RealtimeSimulatorImpl> (Simulator::GetImplementation ())->
+ ScheduleRealtimeNow (
+ MakeEvent (&EmuNetDevice::ForwardUp, this, buf, len));
+
+ ...
+ }
+
+The line starting with our templated DynamicCast function probably deserves a
+comment. It gains access to the simulator implementation object using the
+``Simulator::GetImplementation`` method and then casts to the real-time
+simulator implementation to use the real-time schedule method
+``ScheduleRealtimeNow``. This function will cause a handler for the newly
+received packet to be scheduled for execution at the current real time clock
+value. This will, in turn cause the simulation clock to be advanced to that real
+time value when the scheduled event (``EmuNetDevice::ForwardUp``) is fired.
+
+The ``ForwardUp`` function operates as most other similar |ns3| net device
+methods do. The packet is first filtered based on the destination address. In
+the case of the ``Emu`` device, the MAC destination address will be the address
+of the ``Emu`` device and not the hardware address of the real device. Headers
+are then stripped off and the trace hooks are hit. Finally, the packet is passed
+up the |ns3| protocol stack using the receive callback function of the net
+device.
+
+Sending a packet is equally straightforward as shown below. The first thing we
+do is to add the ethernet header and trailer to the |ns3| ``Packet`` we are
+sending. The source address corresponds to the address of the ``Emu`` device and
+not the underlying native device MAC address. This is where the MAC address
+spoofing is done. The trailer is added and we enqueue and dequeue the packet
+from the net device queue to hit the trace hooks.::
+
+ header.SetSource (source);
+ header.SetDestination (destination);
+ header.SetLengthType (packet->GetSize ());
+ packet->AddHeader (header);
+
+ EthernetTrailer trailer;
+ trailer.CalcFcs (packet);
+ packet->AddTrailer (trailer);
+
+ m_queue->Enqueue (packet);
+ packet = m_queue->Dequeue ();
+
+ struct sockaddr_ll ll;
+ bzero (&ll, sizeof (ll));
+
+ ll.sll_family = AF_PACKET;
+ ll.sll_ifindex = m_sll_ifindex;
+ ll.sll_protocol = htons(ETH_P_ALL);
+
+ rc = sendto (m_sock, packet->PeekData (), packet->GetSize (), 0,
+ reinterpret_cast<struct sockaddr *> (&ll), sizeof (ll));
+
+Finally, we simply send the packet to the raw socket which puts it out on the
+real network.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/emulation-overview.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,71 @@
+.. include:: replace.txt
+
+Emulation Overview
+------------------
+
+|ns3| has been designed for integration into testbed and virtual machine
+environments. We have addressed this need by providing two kinds of net devices.
+The first kind, which we call an ``Emu`` ``NetDevice`` allows |ns3| simulations
+to send data on a "real" network. The second kind, called a ``Tap``
+``NetDevice`` allows a "real" host to participate in an |ns3| simulation as if
+it were one of the simulated nodes. An |ns3| simulation may be constructed with
+any combination of simulated, ``Emu``, or ``Tap`` devices.
+
+One of the use-cases we want to support is that of a testbed. A concrete example
+of an environment of this kind is the ORBIT testbed. ORBIT is a laboratory
+emulator/field trial network arranged as a two dimensional grid of 400 802.11
+radio nodes. We integrate with ORBIT by using their "imaging" process to load
+and run |ns3| simulations on the ORBIT array. We use our ``Emu`` ``NetDevice``
+to drive the hardware in the testbed and we can accumulate results either using
+the |ns3| tracing and logging functions, or the native ORBIT data gathering
+techniques. See `<http://www.orbit-lab.org/>`_ for details on the ORBIT
+testbed.
+
+A simulation of this kind is shown in the following figure:
+
+.. _testbed:
+
+.. figure:: figures/testbed.*
+
+ Example Implementation of Testbed Emulation.
+
+You can see that there are separate hosts, each running a subset of a "global"
+simulation. Instead of an |ns3| channel connecting the hosts, we use real
+hardware provided by the testbed. This allows |ns3| applications and protocol
+stacks attached to a simulation node to communicate over real hardware.
+
+We expect the primary use for this configuration will be to generate repeatable
+experimental results in a real-world network environment that includes all of
+the |ns3| tracing, logging, visualization and statistics gathering tools.
+
+In what can be viewed as essentially an inverse configuration, we allow "real"
+machines running native applications and protocol stacks to integrate with an
+|ns3| simulation. This allows for the simulation of large networks connected to
+a real machine, and also enables virtualization. A simulation of this kind is
+shown in the following figure:
+
+.. _emulated-channel:
+
+.. figure:: figures/emulated-channel.*
+
+ Implementation overview of emulated channel.
+
+Here, you will see that there is a single host with a number of virtual machines
+running on it. An |ns3| simulation is shown running in the virtual machine shown
+in the center of the figure. This simulation has a number of nodes with
+associated |ns3| applications and protocol stacks that are talking to an |ns3|
+channel through native simulated |ns3| net devices.
+
+There are also two virtual machines shown at the far left and far right of the
+figure. These VMs are running native (Linux) applications and protocol stacks.
+The VM is connected into the simulation by a Linux Tap net device. The user-mode
+handler for the Tap device is instantiated in the simulation and attached to a
+proxy node that represents the native VM in the simulation. These handlers allow
+the Tap devices on the native VMs to behave as if they were |ns3| net devices in
+the simulation VM. This, in turn, allows the native software and protocol suites
+in the native VMs to believe that they are connected to the simulated |ns3|
+channel.
+
+We expect the typical use case for this environment will be to analyze the
+behavior of native applications and protocol suites in the presence of large
+simulated |ns3| networks.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/emulation.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,8 @@
+Emulation
+---------
+
+.. toctree::
+
+ emulation-overview
+ emu
+ tap
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/energy.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,142 @@
+Energy Framework
+----------------
+
+Energy consumption is a key issue for wireless devices, and wireless network researchers often need to investigate the energy consumption at a node or in the overall network while running network simulations in ns-3. This requires ns-3 to support energy consumption modeling. Further, as concepts such as fuel cells and energy scavenging are becoming viable for low power wireless devices, incorporating the effect of these emerging technologies into simulations requires support for modeling diverse energy sources in ns-3. The ns-3 Energy Framework provides the basis for energy consumption and energy source modeling.
+
+
+Model Description
+=================
+
+The source code for the Energy Framework is currently at: ``src/contrib/energy``.
+
+Design
+******
+
+The ns-3 Energy Framework is composed of 2 parts: Energy Source and Device Energy Model.
+The framework will be implemented into the ``src/contrib/energy/models`` folder.
+
+Energy Source
+#############
+
+The Energy Source represents the power supply on each node. A node can have one or more energy sources, and each energy source can be connected to multiple device energy models. Connecting an energy source to a device energy model implies that the corresponding device draws power from the source. The basic functionality of the Energy Source is to provide energy for devices on the node. When energy is completely drained from the Energy Source, it notifies the devices on node such that each device can react to this event. Further, each node can access the Energy Source Objects for information such as remaining energy or energy fraction (battery level). This enables the implementation of energy aware protocols in ns-3.
+
+In order to model a wide range of power supplies such as batteries, the Energy Source must be able to capture characteristics of these supplies. There are 2 important characteristics or effects related to practical batteries:
+
+* Rate Capacity Effect: Decrease of battery lifetime when the current draw is higher than the rated value of the battery.
+* Recovery Effect: Increase of battery lifetime when the battery is alternating between discharge and idle states.
+
+In order to incorporate the Rate Capacity Effect, the Energy Source uses current draw from all devices on the same node to calculate energy consumption. The Energy Source polls all devices on the same node periodically to calculate the total current draw and hence the energy consumption. When a device changes state, its corresponding Device Energy Model will notify the Energy Source of this change and new total current draw will be calculated.
+
+The Energy Source base class keeps a list of devices (Device Energy Model objects) using the particular Energy Source as power supply. When energy is completely drained, the Energy Source will notify all devices on this list. Each device can then handle this event independently, based on the desired behavior when power supply is drained.
+
+Device Energy Model
+###################
+
+The Device Energy Model is the energy consumption model of a device on node. It is designed to be a state based model where each device is assumed to have a number of states, and each state is associated with a power consumption value. Whenever the state of the device changes, the corresponding Device Energy Model will notify the Energy Source of the new current draw of the device. The Energy Source will then calculate the new total current draw and update the remaining energy.
+
+The Device Energy Model can also be used for devices that do not have finite number of states. For example, in an electric vehicle, the current draw of the motor is determined by its speed. Since the vehicle's speed can take continuous values within a certain range, it is infeasible to define a set of discrete states of operation. However, by converting the speed value into current directly, the same set of Device Energy Model APIs can still be used.
+
+Future Work
+***********
+
+For Device Energy Models, we are planning to include support for other PHY layer models provided in ns-3 such as WiMAX. For Energy Sources, we are planning to included new types of Energy Sources such as energy scavenging.
+
+References
+**********
+
+.. [1] ns-2 Energy model: http://www.cubinlab.ee.unimelb.edu.au/~jrid/Docs/Manuel-NS2/node204.html
+.. [2] H. Wu, S. Nabar and R. Poovendran. An Energy Framework for the Network Simulator 3 (ns-3).
+.. [3] M. Handy and D. Timmermann. Simulation of mobile wireless networks with accurate
+ modelling of non-linear battery effects. In Proc. of Applied simulation and Modeling
+ (ASM), 2003.
+.. [4] D. N. Rakhmatov and S. B. Vrudhula. An analytical high-level battery model for use in energy
+ management of portable electronic systems. In Proc. of IEEE/ACM International Conference on
+ Computer Aided Design (ICCAD’01), pages 488–493, November 2001.
+.. [5] D. N. Rakhmatov, S. B. Vrudhula, and D. A. Wallach. Battery lifetime prediction for
+ energy-aware computing. In Proc. of the 2002 International Symposium on Low Power
+ Electronics and Design (ISLPED’02), pages 154–159, 2002.
+
+Usage
+=====
+
+The main way that ns-3 users will typically interact with the Energy Framework is through the helper API and through the publicly visible attributes of the framework. The helper API is defined in ``src/contrib/energy/helper/*.h``.
+
+In order to use the energy framework, the user must install an Energy Source for the node of interest and the corresponding Device Energy Model for the network devices. Energy Source (objects) are aggregated onto each node by the Energy Source Helper. In order to allow multiple energy sources per node, we aggregate an Energy Source Container rather than directly aggregating a source object.
+
+The Energy Source object also keeps a list of Device Energy Model objects using the source as power supply. Device Energy Model objects are installed onto the Energy Source by the Device Energy Model Helper. User can access the Device Energy Model objects through the Energy Source object to obtain energy consumption information of individual devices.
+
+
+Examples
+********
+
+The example ``examples/energy/`` contain some basic code that shows how to set up the framework.
+
+Helpers
+*******
+
+Energy Source Helper
+####################
+
+Base helper class for Energy Source objects, this helper Aggregates Energy Source object onto a node. Child implementation of this class creates the actual Energy Source object.
+
+Device Energy Model Helper
+##########################
+
+Base helper class for Device Energy Model objects, this helper attaches Device Energy Model objects onto Energy Source objects. Child implementation of this class creates the actual Device Energy Model object.
+
+Attributes
+**********
+
+Attributes differ between Energy Sources and Devices Energy Models implementations, please look at the specific child class for details.
+
+Basic Energy Source
+###################
+
+* ``BasicEnergySourceInitialEnergyJ``: Initial energy stored in basic energy source.
+* ``BasicEnergySupplyVoltageV``: Initial supply voltage for basic energy source.
+* ``PeriodicEnergyUpdateInterval``: Time between two consecutive periodic energy updates.
+
+RV Battery Model
+################
+
+* ``RvBatteryModelPeriodicEnergyUpdateInterval``: RV battery model sampling interval.
+* ``RvBatteryModelOpenCircuitVoltage``: RV battery model open circuit voltage.
+* ``RvBatteryModelCutoffVoltage``: RV battery model cutoff voltage.
+* ``RvBatteryModelAlphaValue``: RV battery model alpha value.
+* ``RvBatteryModelBetaValue``: RV battery model beta value.
+* ``RvBatteryModelNumOfTerms``: The number of terms of the infinite sum for estimating battery level.
+
+WiFi Radio Energy Model
+#######################
+
+* ``IdleCurrentA``: The default radio Idle current in Ampere.
+* ``CcaBusyCurrentA``: The default radio CCA Busy State current in Ampere.
+* ``TxCurrentA``: The radio Tx current in Ampere.
+* ``RxCurrentA``: The radio Rx current in Ampere.
+* ``SwitchingCurrentA``: The default radio Channel Switch current in Ampere.
+
+Tracing
+*******
+
+Traced values differ between Energy Sources and Devices Energy Models implementations, please look at the specific child class for details.
+
+Basic Energy Source
+###################
+
+* ``RemainingEnergy``: Remaining energy at BasicEnergySource.
+
+RV Battery Model
+################
+
+* ``RvBatteryModelBatteryLevel``: RV battery model battery level.
+* ``RvBatteryModelBatteryLifetime``: RV battery model battery lifetime.
+
+WiFi Radio Energy Model
+#######################
+
+* ``TotalEnergyConsumption``: Total energy consumption of the radio device.
+
+Validation
+**********
+
+Comparison of the Energy Framework against actual devices have not been performed. Current implementation of the Energy Framework is checked numerically for computation errors. The RV battery model is validated by comparing results with what was presented in the original RV battery model paper.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/figures Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,1 @@
+../figures
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/flow-monitor.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,8 @@
+Flow Monitor
+------------
+
+*Placeholder chapter*
+
+This feature was added as contributed code (``src/contrib``) in *ns-3.6* and to
+the main distribution for *ns-3.7*. A paper on this feature is published in the
+proceedings of NSTools: `<http://www.nstools.org/techprog.shtml>`_.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/helpers.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,37 @@
+.. include:: replace.txt
+
+Helpers
+-------
+
+The above chapters introduced you to various |ns3| programming concepts such as
+smart pointers for reference-counted memory management, attributes, namespaces,
+callbacks, etc. Users who work at this low-level API can interconnect |ns3|
+objects with fine granulariy. However, a simulation program written entirely
+using the low-level API would be quite long and tedious to code. For this
+reason, a separate so-called "helper API" has been overlaid on the core |ns3|
+API. If you have read the |ns3| tutorial, you will already be familiar with the
+helper API, since it is the API that new users are typically introduced to
+first. In this chapter, we introduce the design philosophy of the helper API
+and contrast it to the low-level API. If you become a heavy user of |ns3|, you
+will likely move back and forth between these APIs even in the same program.
+
+The helper API has a few goals:
+
+#. the rest of ``src/`` has no dependencies on the helper API; anything that can
+ be done with the helper API can be coded also at the low-level API
+#. **Containers:** Often simulations will need to do a number of identical
+ actions to groups of objects. The helper API makes heavy use of containers of
+ similar objects to which similar or identical operations can be performed.
+#. The helper API is not generic; it does not strive to maximize code reuse. So,
+ programming constructs such as polymorphism and templates that achieve code
+ reuse are not as prevalent. For instance, there are separate CsmaNetDevice
+ helpers and PointToPointNetDevice helpers but they do not derive from a
+ common NetDevice base class.
+#. The helper API typically works with stack-allocated (vs. heap-allocated)
+ objects. For some programs, |ns3| users may not need to worry about any low
+ level Object Create or Ptr handling; they can make do with containers of
+ objects and stack-allocated helpers that operate on them.
+
+The helper API is really all about making |ns3| programs easier to write and
+read, without taking away the power of the low-level interface. The rest of this
+chapter provides some examples of the programming conventions of the helper API.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/index.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,17 @@
+.. only:: html or latex
+
+ Welcome to ns-3's documentation!
+ ================================
+
+ Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ organization
+ core
+ nodes-and-devices
+ emulation
+ internet-models
+ applications
+ support
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/internet-models.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,11 @@
+Internet Models
+---------------
+
+.. toctree::
+
+ sockets-api
+ internet-stack
+ ipv4
+ ipv6
+ routing
+ tcp
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/internet-stack.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,231 @@
+.. include:: replace.txt
+
+Internet Stack
+--------------
+
+Internet stack aggregation
+**************************
+
+A bare class :cpp:class:`Node` is not very useful as-is; other objects must be
+aggregated to it to provide useful node functionality.
+
+The |ns3| source code directory ``src/internet-stack`` provides implementation
+of TCP/IPv4- and IPv6-related components. These include IPv4, ARP, UDP, TCP,
+IPv6, Neighbor Discovery, and other related protocols.
+
+Internet Nodes are not subclasses of class Node; they are simply Nodes that have
+had a bunch of IPv4-related objects aggregated to them. They can be put together
+by hand, or via a helper function :cpp:func:`InternetStackHelper::Install ()`
+which does the following to all nodes passed in as arguments:::
+
+ void
+ InternetStackHelper::Install (Ptr<Node> node) const
+ {
+ if (node->GetObject<Ipv4> () != 0)
+ {
+ NS_FATAL_ERROR ("InternetStackHelper::Install(): Aggregating "
+ "an InternetStack to a node with an existing Ipv4 object");
+ return;
+ }
+
+ CreateAndAggregateObjectFromTypeId (node, "ns3::ArpL3Protocol");
+ CreateAndAggregateObjectFromTypeId (node, "ns3::Ipv4L3Protocol");
+ CreateAndAggregateObjectFromTypeId (node, "ns3::Icmpv4L4Protocol");
+ CreateAndAggregateObjectFromTypeId (node, "ns3::UdpL4Protocol");
+ node->AggregateObject (m_tcpFactory.Create<Object> ());
+ Ptr<PacketSocketFactory> factory = CreateObject<PacketSocketFactory> ();
+ node->AggregateObject (factory);
+ // Set routing
+ Ptr<Ipv4> ipv4 = node->GetObject<Ipv4> ();
+ Ptr<Ipv4RoutingProtocol> ipv4Routing = m_routing->Create (node);
+ ipv4->SetRoutingProtocol (ipv4Routing);
+ }
+
+Where multiple implementations exist in |ns3| (TCP, IP routing), these objects
+are added by a factory object (TCP) or by a routing helper (m_routing).
+
+Note that the routing protocol is configured and set outside this
+function. By default, the following protocols are added to Ipv4:::
+
+ InternetStackHelper::InternetStackHelper ()
+ {
+ SetTcp ("ns3::TcpL4Protocol");
+ static Ipv4StaticRoutingHelper staticRouting;
+ static Ipv4GlobalRoutingHelper globalRouting;
+ static Ipv4ListRoutingHelper listRouting;
+ listRouting.Add (staticRouting, 0);
+ listRouting.Add (globalRouting, -10);
+ SetRoutingHelper (listRouting);
+ }
+
+By default, IPv4 and IPv6 are enabled.
+
+Internet Node structure
++++++++++++++++++++++++
+
+An IPv4-capable Node (an |ns3| Node augmented by aggregation to have one or more
+IP stacks) has the following internal structure.
+
+Layer-3 protocols
+~~~~~~~~~~~~~~~~~
+
+At the lowest layer, sitting above the NetDevices, are the "layer 3" protocols,
+including IPv4, IPv6 (in the future), and ARP. The class
+:cpp:class:`Ipv4L3Protocol` is an implementation class whose public interface is
+typically class :cpp:class:`Ipv4` (found in src/node directory), but the
+Ipv4L3Protocol public API is also used internally in the src/internet-stack
+directory at present.
+
+In class Ipv4L3Protocol, one method described below is ``Receive ()``:::
+
+ /**
+ * Lower layer calls this method after calling L3Demux::Lookup
+ * The ARP subclass needs to know from which NetDevice this
+ * packet is coming to:
+ * - implement a per-NetDevice ARP cache
+ * - send back arp replies on the right device
+ */
+ void Receive( Ptr<NetDevice> device, Ptr<const Packet> p, uint16_t protocol,
+ const Address &from, const Address &to, NetDevice::PacketType packetType);
+
+First, note that the ``Receive ()`` function has a matching signature to the
+ReceiveCallback in the class :cpp:class:`Node`. This function pointer is
+inserted into the Node's protocol handler when ``AddInterface ()`` is called.
+The actual registration is done
+with a statement such as follows:::
+
+ RegisterProtocolHandler ( MakeCallback (&Ipv4Protocol::Receive, ipv4),
+ Ipv4L3Protocol::PROT_NUMBER, 0);
+
+The Ipv4L3Protocol object is aggregated to the Node; there is only one such
+Ipv4L3Protocol object. Higher-layer protocols that have a packet to send down to
+the Ipv4L3Protocol object can call ``GetObject<Ipv4L3Protocol> ()`` to obtain a
+pointer, as follows:::
+
+ Ptr<Ipv4L3Protocol> ipv4 = m_node->GetObject<Ipv4L3Protocol> ();
+ if (ipv4 != 0)
+ {
+ ipv4->Send (packet, saddr, daddr, PROT_NUMBER);
+ }
+
+This class nicely demonstrates two techniques we exploit in |ns3| to bind
+objects together: callbacks, and object aggregation.
+
+Once IPv4 routing has determined that a packet is for the local node, it
+forwards it up the stack. This is done with the following function:::
+
+ void
+ Ipv4L3Protocol::LocalDeliver (Ptr<const Packet> packet, Ipv4Header const&ip, uint32_t iif)
+
+The first step is to find the right Ipv4L4Protocol object, based on IP protocol
+number. For instance, TCP is registered in the demux as protocol number 6.
+Finally, the ``Receive()`` function on the Ipv4L4Protocol (such as
+``TcpL4Protocol::Receive`` is called.
+
+We have not yet introduced the class Ipv4Interface. Basically, each NetDevice is
+paired with an IPv4 representation of such device. In Linux, this class
+:cpp:class:`Ipv4Interface` roughly corresponds to the ``struct in_device``; the
+main purpose is to provide address-family specific information (addresses) about
+an interface.
+
+The IPv6 implementation follows a similar architecture.
+
+Layer-4 protocols and sockets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We next describe how the transport protocols, sockets, and applications tie
+together. In summary, each transport protocol implementation is a socket
+factory. An application that needs a new socket
+
+For instance, to create a UDP socket, an application would use a code snippet
+such as the following:::
+
+ Ptr<Udp> udpSocketFactory = GetNode ()->GetObject<Udp> ();
+ Ptr<Socket> m_socket = socketFactory->CreateSocket ();
+ m_socket->Bind (m_local_address);
+ ...
+
+The above will query the node to get a pointer to its UDP socket factory, will
+create one such socket, and will use the socket with an API similar to the
+C-based sockets API, such as ``Connect ()`` and ``Send ()``. See the chapter on
+|ns3| sockets for more information.
+
+We have described so far a socket factory (e.g. ``class Udp``) and a socket,
+which may be specialized (e.g., class :cpp:class:`UdpSocket`). There are a few
+more key objects that relate to the specialized task of demultiplexing a packet
+to one or more receiving sockets. The key object in this task is class
+:cpp:class:`Ipv4EndPointDemux`. This demultiplexer stores objects of class
+:cpp:class:`Ipv4EndPoint`. This class holds the addressing/port tuple (local
+port, local address, destination port, destination address) associated with the
+socket, and a receive callback. This receive callback has a receive function
+registered by the socket. The ``Lookup ()`` function to Ipv4EndPointDemux
+returns a list of Ipv4EndPoint objects (there may be a list since more than one
+socket may match the packet). The layer-4 protocol copies the packet to each
+Ipv4EndPoint and calls its ``ForwardUp ()`` method, which then calls the
+``Receive ()`` function registered by the socket.
+
+An issue that arises when working with the sockets API on real
+systems is the need to manage the reading from a socket, using
+some type of I/O (e.g., blocking, non-blocking, asynchronous, ...).
+|ns3| implements an asynchronous model for socket I/O; the application
+sets a callback to be notified of received data ready to be read, and the
+callback is invoked by the transport protocol when data is available.
+This callback is specified as follows:::
+
+ void Socket::SetRecvCallback (Callback<void, Ptr<Socket>,
+ Ptr<Packet>, const Address&> receivedData);
+
+The data being received is conveyed in the Packet data buffer. An example
+usage is in class :cpp:class:`PacketSink`:::
+
+ m_socket->SetRecvCallback (MakeCallback(&PacketSink::HandleRead, this));
+
+To summarize, internally, the UDP implementation is organized as follows:
+
+* a ``UdpImpl`` class that implements the UDP socket factory functionality
+
+* a ``UdpL4Protocol`` class that implements the protocol logic that is
+ socket-independent
+* a ``UdpSocketImpl`` class that implements socket-specific aspects of UDP
+* a class called ``Ipv4EndPoint`` that stores the addressing tuple (local port,
+ local address, destination port, destination address) associated with the
+ socket, and a receive callback for the socket.
+
+Ipv4-capable node interfaces
+++++++++++++++++++++++++++++
+
+Many of the implementation details, or internal objects themselves, of
+Ipv4-capable Node objects are not exposed at the simulator public API. This
+allows for different implementations; for instance, replacing the native |ns3|
+models with ported TCP/IP stack code.
+
+The C++ public APIs of all of these objects is found in the ``src/node``
+directory, including principally:
+
+* ``socket.h``
+* ``tcp.h``
+* ``udp.h``
+* ``ipv4.h``
+
+These are typically base class objects that implement the default values used in
+the implementation, implement access methods to get/set state variables, host
+attributes, and implement publicly-available methods exposed to clients such as
+``CreateSocket``.
+
+Example path of a packet
+++++++++++++++++++++++++
+
+These two figures show an example stack trace of how packets flow through the
+Internet Node objects.
+
+.. _internet-node-send:
+
+.. figure:: figures/internet-node-send.*
+
+ Send path of a packet.
+
+.. _internet-node-recv:
+
+.. figure:: figures/internet-node-recv.*
+
+ Receive path of a packet.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/ipv4.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,6 @@
+.. include:: replace.txt
+
+IPv4
+----
+
+*Placeholder chapter*
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/ipv6.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,10 @@
+.. include:: replace.txt
+
+IPv6
+----
+
+*Placeholder chapter*
+
+IPv6 models are being added to ns-3. A paper on the IPv6 models was published in
+WNS2 2008: `<http://lsiit.u-strasbg.fr/Publications/2008/VMM08/>`_.
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/logging.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,7 @@
+.. include:: replace.txt
+
+Logging
+-------
+
+*This chapter not yet written. For now, the ns-3 tutorial contains logging
+information.*
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/lte.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,366 @@
+LTE Module
+----------
+
+This chapter describes the ns-3 :cpp:class:`ns3::LteNetDevice` and related models.
+By adding :cpp:class:`ns3::LteNetDevice` objects to ns-3 nodes, one can create models
+of 3GPP E-UTRAN infrastructure and Long Term Evolution (LTE) networks.
+
+Below, we list some more details about what ns-3 LTE models cover but, in
+summary, the most important features of the ns-3 model are:
+
+* a basic implementation of both the User Equipment (UE) and the enhanced NodeB (eNB) devices,
+* RRC entities for both the UE and the eNB,
+* a state-of-the-art Adaptive Modulation and Coding (AMC) scheme for the downlink
+* the management of the data radio bearers (with their QoS parameters), the MAC queues and the RLC instances,
+* Channel Quality Indicator (CQI) management,
+* support for both uplink and downlik packet scheduling,
+* a PHY layer model with Resource Block level granularity
+* a channel model with the outdoor E-UTRAN propagation loss model.
+
+Model Description
+*****************
+
+The source code for the LTE models lives in the directory
+``src/devices/lte``.
+
+Design
+======
+
+The LTE model provides a basic implementation of LTE devices, including propagation models and
+PHY and MAC layers. It allow to simulate an E-UTRAN interface where one eNB and several UEs can
+communicate among them using a shared downlink (uplink) channel.
+
+The PHY layer has been developed extending the Spectrum Framework [1]_. The MAC model, instead,
+has been developed extending and adding some features to the base class :cpp:class:`ns3::NetDevice`.
+
+
+Physical layer
+##############
+
+A :cpp:class:`ns3::LtePhy` class models the LTE PHY layer.
+
+Basic functionalities of the PHY layer are: (i) transmit packets coming from the device to the channel; (ii) receive packets from the channel; (ii) evaluate the quality of the channel from the Signal To Noise ratio of the received signal; and (iii) forward received packets to the device.
+
+Both the PHY and channel have been developed extending :cpp:class:`ns3::SpectrumPhy` and
+:cpp:class:`ns3::SpectrumChannel` classes, respectively.
+
+The module implements an FDD channel access. In FDD channel access, downlink and uplink
+transmissions work together in the time but using a different set of frequencies.
+Since DL and UL are indipendent between them, the PHY is composed by couple of
+:cpp:class:`ns3::LteSpectrumPhy` object (i.e., implemented into the
+:cpp:class:`ns3::LteSpectrumPhy` class); one for the downlink and one for the uplink.
+The :cpp:class:`ns3::LtePhy` stores and manages both downlink and uplink
+:cpp:class:`ns3::LteSpectrumPhy` elements.
+
+In order to customize all physical functionalities for both UE and eNB devices, dedicated
+classes have been inherited from ones described before. In particular,
+:cpp:class:`ns3::UePhy` and :cpp:class:`ns3::EnbPhy` classes, inherited from
+the :cpp:class:`ns3::LtePhy` class, implement the PHY layer for the UE and the
+eNB, respectively. In the same way, :cpp:class:`ns3::UeLteSpectrumPhy` and
+:cpp:class:`ns3::EnbLteSpectrumPhy` classes,
+inherited from the :cpp:class:`ns3::LteSpectrumPhy`,
+implement the downlink/uplink spectrum channel for the UE and the eNB, respectively.
+
+The figure below shows how UE and eNB can exchange packets through the considered PHY layer.
+
+.. _lte-transmission:
+
+.. figure:: figures/lte-transmission.*
+
+ DL and UL transmision on the LTE network
+
+For the downlink, when the eNB whants to send packets, it calls the ``StartTx`` function to
+send them into the downlink channel. Then, the downlink channel delivers the burst
+of packets to all the :cpp:class:`ns3::UeLteSpectrumPhy` attached to it, handling the
+``StartRx`` function.
+When the UE receives packets, it executes the following tasks:
+
+* compute the SINR for all the sub channel used in the downlink
+
+* create and send CQI feedbacks
+
+* forward all the received packets to the device
+
+The uplink works similary to the previous one.
+
+Propagation Loss Models
+#######################
+
+A proper propagation loss model has been developed for the LTE E-UTRAN interface (see [2]_ and [3]_).
+It is used by the PHY layer to compute the loss due to the propagation.
+
+The LTE propagation loss model is composed by 4 different models (shadowing, multipath,
+penetration loss and path loss) [2]_:
+
+* Pathloss: :math:`PL = 128.1 + (37.6 * log10 (R))`, where R is the distance between the
+ UE and the eNB in Km.
+
+* Multipath: Jakes model
+
+* PenetrationLoss: 10 dB
+
+* Shadowing: log-normal distribution (mean=0dB, standard deviation=8dB)
+
+Every time that the ``LteSpectrumPHY::StartRx ()`` function is called, the
+``SpectrumInterferenceModel`` is used to computed the SINR, as proposed in [3]_. Then,
+the network device uses the AMC module to map the SINR to a proper CQI and to send it
+to the eNB using the ideal control channel.
+
+LTE Devices
+###########
+
+All the common functionalities of the LTE network devices have been defined into
+the :cpp:class:`ns3::LteNetDevice` class. Moreover, the LTE device has been conceived
+as a container of several entities such as MAC, RRC, RLC etc .. For each of these entity
+a dedicated class has been developed.
+
+For each device are defined the following entity/element
+
+* the LTE PHY layer (described in the previous sub section)
+
+* rrc entity
+
+* mac entity
+
+* rlc entity
+
+The module is perfectly integrated into the whole ns-3 project: it is already possible
+to attach to each device a TCP/IP protocol stack and all the implemented applications
+(i.e., udp client/server, trace based, etc..).
+
+
+The RRC Entity
+##############
+
+RRC entity is implemented by the :cpp:class:`ns3::RrcEntity` class, and provides only the
+Radio Bearer management functionality.
+A dedicated bearer is created for each downlink flow.
+
+The RRC entity performs the classification of the packets coming from the upper
+layer into the corresponding Radio Bearer. This classification is
+based on the information provided by the class :cpp:class:`ns3::IpcsClassifierRecord`.
+
+
+
+The MAC Entity
+##############
+
+Class :cpp:class:`ns3::MacEntity` provides a basic implementation of the MAC entity for
+the LTE device. Moreover, :cpp:class:`ns3::EnbMacEntity` and :cpp:class:`ns3::UeMacEntity classes,
+inherited from the previous one, provides an implementation for the eNB and the UE MAC entity,
+respectively.
+In all MAC entities is defined the AMC module [4]_. Furthermore, into the
+:cpp:class:`ns3::EnbMacEntity` class are defined also both uplink and downlink schedulers.
+
+Every time the PHY layer of the UE receives a packet form the channel, it calls the AMC module,
+define into the MAC entity, in order to convert the SINR of the received signal to CQI feedbacks.
+Every sub frame, the eNB performs both uplink and downlink radio resource allocation. Actually only
+a simple packet scheduler has been implemented that is able to send, every sub frame, only one
+packet in the downlink.
+
+
+The RLC Entity
+##############
+
+The RLC entity performs an interface between the MAC layer and the MAC queue for a given bearer.
+Actually, only the RLC Transport Mode has been implemented.
+
+
+Control Channel
+###############
+
+Control channel keeps a very important role in LTE networks. In fact, it is responsible of the
+transmission of several information (i.e., CQI feedback, allocation map, etc...). For this reason,
+also in a framework oriented to data transmision, it is necesary to find a tecnique for exchange
+these information. To this aim, an ideal control channel will be developed.
+Using ideal control messages, both UE and eNB can exchange control information without simulating
+a realistic transmission over the LTE channel.
+
+Two types of control messages have been implemented: the Pdcch Map Ideal Control Message and the
+Cqi Ideal Control Message. The first one is used by the eNB to send the uplink and downlink
+resource mapping to all registered UE. In particular, this message carries information about
+UEs that have been scheduled in the ul/dl, a list of assigned sub channels and the selected
+MCS for the transmission.
+The second one, instead, is used by the UE to send CQI feedbacks to the eNB.
+
+
+
+Scope and Limitations
+=====================
+
+The framework has been designed in order to support data transmission for both uplink and
+downlink. It is important to note that downlin and uplink transmissions are managed by the
+packet scheduler that works at the eNB. It decides, in fact, what UEs should be scheduled
+every TTI and what radio resource should be allocated to them.
+
+In the current implementation, the downlink transmission is administrated by the downlink
+packet scheduler. Furthermore, no packet scheduler for uplink transmission has been developed.
+As a consequence, for the downlink packet are sent only after scheduling decisions; for the uplink,
+instead, packet are sent directly, without any scheduling decisions.
+
+Finally, the transmission of control messages (such as CQI feedbacks, PDCCH, etc..) is done by an
+ideal control channel.
+
+
+Future Work
+===========
+
+In the future, several LTE features will be developed in order to improve the proposed module.
+
+In particular, for the near future have been scheduled the following implementations:
+
+* a more efficient design for the RRM (Radio resource management)
+
+* a complete packet scheduler (i.e., a simple round robin scheme, maximum througput and
+ proportional fair allocation schemes) for both downlink and uplink, in order to support
+ a standard compliant packet transmission
+
+* ideal PDCCH control messages
+
+* a standard compliant RLC entity
+
+* PHY error model
+
+
+
+References
+==========
+
+.. [1] N. Baldo and M. Miozzo, Spectrum-aware Channel and PHY layer modeling for ns3, Proceedings
+ of ICST NSTools 2009, Pisa, Italy. The framework is designed to simulate only data
+ transmissions. For the transmission of control messages (such as CQI feedback, PDCCH,
+ etc..) will be used an ideal control channel).
+
+.. [2] 3GPP TS 25.814 ( http://www.3gpp.org/ftp/specs/html-INFO/25814.htm )
+
+.. [3] Giuseppe Piro, Luigi Alfredo Grieco, Gennaro Boggia, and Pietro Camarda", A Two-level
+ Scheduling Algorithm for QoS Support in the Downlink of LTE Cellular Networks", Proc. of
+ European Wireless, EW2010, Lucca, Italy, Apr., 2010 ( draft version is available on
+ http://telematics.poliba.it/index.php?option=com_jombib&task=showbib&id=330 )
+
+.. [4] 3GPP R1-081483 (available on
+ http://www.3gpp.org/ftp/tsg_ran/WG1_RL1/TSGR1_52b/Docs/R1-081483.zip )
+
+
+Usage
+*****
+
+The main way that users who write simulation scripts will typically
+interact with the LTE models is through the helper API and through
+the publicly visible attributes of the model.
+
+The helper API is defined in ``src/devices/lte/helper/lte-helper.h``.
+
+The example ``src/devices/lte/examples/`` contain some basic
+code that shows how to set up the model in order to simualte an
+E-UTRAN downlink transmission.
+
+Examples
+========
+
+``src/devices/lte/examples/lte-device.cc`` shows how it is possible to set up the LTE module::
+
+ NodeContainer ueNodes;
+ NodeContainer enbNodes;
+
+ ueNodes.Create (1);
+ enbNodes.Create (1);
+
+ LteHelper lte;
+
+ NetDeviceContainer ueDevs, enbDevs;
+ ueDevs = lte.Install (ueNodes, LteHelper::DEVICE_TYPE_USER_EQUIPMENT);
+ enbDevs = lte.Install (enbNodes, LteHelper::DEVICE_TYPE_ENODEB);
+
+
+The helper method :cpp:func:`ns3::LteHelper::Install` creates LTE device,
+the DL, UL physical layer and attach the to proper LTE channels.
+
+
+Moreover, to simulate a complete LTE system, it is necessary to define
+other information, as expressed in what follows:
+
+#. install IP protocol stack::
+
+ InternetStackHelper stack;
+ stack.Install (ueNodes);
+ stack.Install (enbNodes);
+ Ipv4AddressHelper address;
+ address.SetBase ("10.1.1.0", "255.255.255.0");
+ Ipv4InterfaceContainer UEinterfaces = address.Assign (ueDevs);
+ Ipv4InterfaceContainer ENBinterface = address.Assign (enbDevs);
+
+
+#. register UE to a given eNB::
+
+ Ptr<EnbNetDevice> enb = enbDevs.Get (0)->GetObject<EnbNetDevice> ();
+ Ptr<UeNetDevice> ue = ueDevs.Get (i)->GetObject<UeNetDevice> ();
+ lte.RegisterUeToTheEnb (ue, enb);
+
+
+#. create the mobility model for each device::
+
+ Ptr<ConstantPositionMobilityModel> enbMobility = new ConstantPositionMobilityModel ();
+ enbMobility->SetPosition (Vector (0.0, 0.0, 0.0));
+ lte.AddMobility (enb->GetPhy (), enbMobility);
+
+ Ptr<ConstantVelocityMobilityModel> ueMobility = new ConstantVelocityMobilityModel ();
+ ueMobility->SetPosition (Vector (30.0, 0.0, 0.0));
+ ueMobility->SetVelocity (Vector (30.0, 0.0, 0.0));
+ lte.AddMobility (ue->GetPhy (), ueMobility);
+
+
+#. define a set of sub channels to use for dl and ul transmission::
+
+ std::vector<int> dlSubChannels;
+ for (int i = 0; i < 25; i++)
+ {
+ dlSubChannels.push_back (i);
+ }
+ std::vector<int> ulSubChannels;
+ for (int i = 50; i < 100; i++)
+ {
+ ulSubChannels.push_back (i);
+ }
+
+ enb->GetPhy ()->SetDownlinkSubChannels (dlSubChannels);
+ enb->GetPhy ()->SetUplinkSubChannels (ulSubChannels);
+ ue->GetPhy ()->SetDownlinkSubChannels (dlSubChannels);
+ ue->GetPhy ()->SetUplinkSubChannels (ulSubChannels);
+
+
+#. define a channel realization for the PHY model::
+
+ lte.AddDownlinkChannelRealization (enbMobility, ueMobility, ue->GetPhy ());
+
+
+Helpers
+=======
+
+Attributes
+==========
+
+Tracing
+=======
+
+Logging
+=======
+
+Caveats
+=======
+
+Validation
+**********
+
+In the ``src/devices/lte/example/lte-amc.cc`` has been developed an important example
+that shows the proper functioning of both AMC module and Channel model.
+The analyzed scenario is composed by two nodes: a eNB and a single UE
+(registered to the eNB). The UE moves into the cell using the
+:cpp:class:`ns3::ConstantVelocityMobilityModel`, along a radial direction.
+The proposed example describes how the channel quality decreases as the distance
+between UE and eNB increases.
+As a conseguence, the total bit rate (in bits per TTI) available to the UE
+decreases as the distance between nodes increases, as expected.
+
+
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/mesh.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,10 @@
+.. include:: replace.txt
+
+Mesh NetDevice
+--------------
+
+*Placeholder chapter*
+
+The Mesh NetDevice based on 802.11s was added in *ns-3.6*. An overview
+presentation by Kirill Andreev was published at the wns-3 workshop
+in 2009: `<http://www.nsnam.org/wiki/index.php/Wns3-2009>`_.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/new-models.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,569 @@
+.. include:: replace.txt
+
+Creating a new ns-3 model
+-------------------------
+
+This chapter walks through the design process of an |ns3| model. In many
+research cases, users will not be satisfied to merely adapt existing models, but
+may want to extend the core of the simulator in a novel way. We will use the
+example of adding an ErrorModel to a simple |ns3| link as a motivating example
+of how one might approach this problem and proceed through a design and
+implementation.
+
+Design-approach
+***************
+
+Consider how you want it to work; what should it do. Think about these things:
+
+* *functionality:* What functionality should it have? What attributes or
+ configuration is exposed to the user?
+* *reusability:* How much should others be able to reuse my design? Can I
+ reuse code from |ns2| to get started? How does a user integrate the model
+ with the rest of another simulation?
+* *dependencies:* How can I reduce the introduction of outside dependencies on
+ my new code as much as possible (to make it more modular)? For instance,
+ should I avoid any dependence on IPv4 if I want it to also be used by IPv6?
+ Should I avoid any dependency on IP at all?
+
+Do not be hesitant to contact the ns-3-users or ns-developers list if you have
+questions. In particular, it is important to think about the public API of your
+new model and ask for feedback. It also helps to let others know of your work in
+case you are interested in collaborators.
+
+Example: ErrorModel
++++++++++++++++++++
+
+An error model exists in |ns2|. It allows packets to be passed to a stateful
+object that determines, based on a random variable, whether the packet is
+corrupted. The caller can then decide what to do with the packet (drop it,
+etc.).
+
+The main API of the error model is a function to pass a packet to, and the
+return value of this function is a boolean that tells the caller whether any
+corruption occurred. Note that depending on the error model, the packet data
+buffer may or may not be corrupted. Let's call this function "IsCorrupt()".
+
+So far, in our design, we have:::
+
+ class ErrorModel
+ {
+ public:
+ /**
+ * \returns true if the Packet is to be considered as errored/corrupted
+ * \param pkt Packet to apply error model to
+ */
+ bool IsCorrupt (Ptr<Packet> pkt);
+ };
+
+Note that we do not pass a const pointer, thereby allowing the function to
+modify the packet if IsCorrupt() returns true. Not all error models will
+actually modify the packet; whether or not the packet data buffer is corrupted
+should be documented.
+
+We may also want specialized versions of this, such as in |ns2|, so although it
+is not the only design choice for polymorphism, we assume that we will subclass
+a base class ErrorModel for specialized classes, such as RateErrorModel,
+ListErrorModel, etc, such as is done in |ns2|.
+
+You may be thinking at this point, "Why not make IsCorrupt() a virtual method?".
+That is one approach; the other is to make the public non-virtual function
+indirect through a private virtual function (this in C++ is known as the non
+virtual interface idiom and is adopted in the |ns3| ErrorModel class).
+
+Next, should this device have any dependencies on IP or other protocols? We do
+not want to create dependencies on Internet protocols (the error model should be
+applicable to non-Internet protocols too), so we'll keep that in mind later.
+
+Another consideration is how objects will include this error model. We envision
+putting an explicit setter in certain NetDevice implementations, for example.::
+
+ /**
+ * Attach a receive ErrorModel to the PointToPointNetDevice.
+ *
+ * The PointToPointNetDevice may optionally include an ErrorModel in
+ * the packet receive chain.
+ *
+ * @see ErrorModel
+ * @param em Ptr to the ErrorModel.
+ */
+ void PointToPointNetDevice::SetReceiveErrorModel(Ptr<ErrorModel> em);
+
+Again, this is not the only choice we have (error models could be aggregated to
+lots of other objects), but it satisfies our primary use case, which is to allow
+a user to force errors on otherwise successful packet transmissions, at the
+NetDevice level.
+
+After some thinking and looking at existing |ns2| code, here is a sample API of
+a base class and first subclass that could be posted for initial review:::
+
+ class ErrorModel
+ {
+ public:
+ ErrorModel ();
+ virtual ~ErrorModel ();
+ bool IsCorrupt (Ptr<Packet> pkt);
+ void Reset (void);
+ void Enable (void);
+ void Disable (void);
+ bool IsEnabled (void) const;
+ private:
+ virtual bool DoCorrupt (Ptr<Packet> pkt) = 0;
+ virtual void DoReset (void) = 0;
+ };
+
+ enum ErrorUnit
+ {
+ EU_BIT,
+ EU_BYTE,
+ EU_PKT
+ };
+
+ // Determine which packets are errored corresponding to an underlying
+ // random variable distribution, an error rate, and unit for the rate.
+ class RateErrorModel : public ErrorModel
+ {
+ public:
+ RateErrorModel ();
+ virtual ~RateErrorModel ();
+ enum ErrorUnit GetUnit (void) const;
+ void SetUnit (enum ErrorUnit error_unit);
+ double GetRate (void) const;
+ void SetRate (double rate);
+ void SetRandomVariable (const RandomVariable &ranvar);
+ private:
+ virtual bool DoCorrupt (Ptr<Packet> pkt);
+ virtual void DoReset (void);
+ };
+
+
+Scaffolding
+***********
+
+Let's say that you are ready to start implementing; you have a fairly clear
+picture of what you want to build, and you may have solicited some initial
+review or suggestions from the list. One way to approach the next step
+(implementation) is to create scaffolding and fill in the details as the design
+matures.
+
+This section walks through many of the steps you should consider to define
+scaffolding, or a non-functional skeleton of what your model will eventually
+implement. It is usually good practice to not wait to get these details
+integrated at the end, but instead to plumb a skeleton of your model into the
+system early and then add functions later once the API and integration seems
+about right.
+
+Note that you will want to modify a few things in the below presentation for
+your model since if you follow the error model verbatim, the code you produce
+will collide with the existing error model. The below is just an outline of how
+ErrorModel was built that you can adapt to other models.
+
+Review the ns-3 coding style document
++++++++++++++++++++++++++++++++++++++
+
+At this point, you may want to pause and read the |ns3| coding style document,
+especially if you are considering to contribute your code back to the project.
+The coding style document is linked off the main project page: `ns-3 coding
+style <http://www.nsnam.org/codingstyle.html>`_.
+
+Decide where in the source tree the model will reside in
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+All of the |ns3| model source code is in the directory ``src/``. You will need
+to choose which subdirectory it resides in. If it is new model code of some
+sort, it makes sense to put it into the ``src/`` directory somewhere,
+particularly for ease of integrating with the build system.
+
+In the case of the error model, it is very related to the packet class, so it
+makes sense to implement this in the ``src/common/`` directory where |ns3|
+packets are implemented.
+
+waf and wscript
++++++++++++++++
+
+|ns3| uses the `Waf <http://www.freehackers.org/~tnagy/waf.html>`_ build system.
+You will want to integrate your new |ns3| uses the Waf build system. You will
+want to integrate your new source files into this system. This requires that you
+add your files to the ``wscript`` file found in each directory.
+
+Let's start with empty files error-model.h and error-model.cc, and add this to
+``src/common/wscript``. It is really just a matter of adding the .cc file to the
+rest of the source files, and the .h file to the list of the header files.
+
+Now, pop up to the top level directory and type "./waf --check". You
+shouldn't have broken anything by this operation.
+
+include guards
+++++++++++++++
+
+Next, let's add some `include guards
+<http://en.wikipedia.org/wiki/Include_guard>`_ in our header file.::
+
+ #ifndef ERROR_MODEL_H
+ #define ERROR_MODEL_H
+ ...
+ #endif
+
+namespace ns3
++++++++++++++
+
+|ns3| uses the |ns3| `namespace
+<http://en.wikipedia.org/wiki/Namespace_(computer_science)#Use_in_common_languages>`_
+to isolate its symbols from other namespaces. Typically, a user will next put
+an |ns3| namespace block in both the cc and h file.::
+
+ namespace ns3 {
+ ...
+ }
+
+At this point, we have some skeletal files in which we can start defining
+our new classes. The header file looks like this:::
+
+ #ifndef ERROR_MODEL_H
+ #define ERROR_MODEL_H
+
+ namespace ns3 {
+
+ } // namespace ns3
+ #endif
+
+while the ``error-model.cc`` file simply looks like this:::
+
+ #include "error-model.h"
+
+ namespace ns3 {
+
+ } // namespace ns3
+
+These files should compile since they don't really have any contents. We're now
+ready to start adding classes.
+
+Initial Implementation
+**********************
+
+At this point, we're still working on some scaffolding, but we can begin to
+define our classes, with the functionality to be added later.
+
+use of class Object?
+++++++++++++++++++++
+
+This is an important design step; whether to use class :cpp:class:`Object` as a
+base class for your new classes.
+
+As described in the chapter on the |ns3| :ref:`Object model`, classes that
+inherit from class :cpp:class:`Object` get special properties:
+
+* the |ns3| type and attribute system (see :ref:`Attributes`)
+* an object aggregation system
+* a smart-pointer reference counting system (class Ptr)
+
+Classes that derive from class :cpp:class:`ObjectBase`} get the first two
+properties above, but do not get smart pointers. Classes that derive from class
+:cpp:class:`RefCountBase` get only the smart-pointer reference counting system.
+
+In practice, class :cpp:class:`Object` is the variant of the three above that
+the |ns3| developer will most commonly encounter.
+
+In our case, we want to make use of the attribute system, and we will be passing
+instances of this object across the |ns3| public API, so class
+:cpp:class:`Object` is appropriate for us.
+
+initial classes
++++++++++++++++
+
+One way to proceed is to start by defining the bare minimum functions and see if
+they will compile. Let's review what all is needed to implement when we derive
+from class Object.::
+
+ #ifndef ERROR_MODEL_H
+ #define ERROR_MODEL_H
+
+ #include "ns3/object.h"
+
+ namespace ns3 {
+
+ class ErrorModel : public Object
+ {
+ public:
+ static TypeId GetTypeId (void);
+
+ ErrorModel ();
+ virtual ~ErrorModel ();
+ };
+
+ class RateErrorModel : public ErrorModel
+ {
+ public:
+ static TypeId GetTypeId (void);
+
+ RateErrorModel ();
+ virtual ~RateErrorModel ();
+ };
+ #endif
+
+
+A few things to note here. We need to include ``object.h``. The convention in
+|ns3| is that if the header file is co-located in the same directory, it may be
+included without any path prefix. Therefore, if we were implementing ErrorModel
+in ``src/core`` directory, we could have just said "``#include "object.h"``".
+But we are in ``src/common``, so we must include it as "``#include
+"ns3/object.h"``". Note also that this goes outside the namespace declaration.
+
+Second, each class must implement a static public member function called
+``GetTypeId (void)``.
+
+Third, it is a good idea to implement constructors and destructors rather than
+to let the compiler generate them, and to make the destructor virtual. In C++,
+note also that copy assignment operator and copy constructors are auto-generated
+if they are not defined, so if you do not want those, you should implement those
+as private members. This aspect of C++ is discussed in Scott Meyers' Effective
+C++ book. item 45.
+
+Let's now look at some corresponding skeletal implementation code in the .cc
+file.::
+
+ #include "error-model.h"
+
+ namespace ns3 {
+
+ NS_OBJECT_ENSURE_REGISTERED (ErrorModel);
+
+ TypeId ErrorModel::GetTypeId (void)
+ {
+ static TypeId tid = TypeId ("ns3::ErrorModel")
+ .SetParent<Object> ()
+ ;
+ return tid;
+ }
+
+ ErrorModel::ErrorModel ()
+ {
+ }
+
+ ErrorModel::~ErrorModel ()
+ {
+ }
+
+ NS_OBJECT_ENSURE_REGISTERED (RateErrorModel);
+
+ TypeId RateErrorModel::GetTypeId (void)
+ {
+ static TypeId tid = TypeId ("ns3::RateErrorModel")
+ .SetParent<ErrorModel> ()
+ .AddConstructor<RateErrorModel> ()
+ ;
+ return tid;
+ }
+
+ RateErrorModel::RateErrorModel ()
+ {
+ }
+
+ RateErrorModel::~RateErrorModel ()
+ {
+ }
+
+What is the ``GetTypeId (void)`` function? This function does a few things. It
+registers a unique string into the TypeId system. It establishes the hierarchy
+of objects in the attribute system (via ``SetParent``). It also declares that
+certain objects can be created via the object creation framework
+(``AddConstructor``).
+
+The macro ``NS_OBJECT_ENSURE_REGISTERED (classname)`` is needed also once for
+every class that defines a new GetTypeId method, and it does the actual
+registration of the class into the system. The :ref:`Object model` chapter
+discusses this in more detail.
+
+how to include files from elsewhere
++++++++++++++++++++++++++++++++++++
+
+log component
++++++++++++++
+
+*Here, write a bit about adding |ns3| logging macros. Note that
+LOG_COMPONENT_DEFINE is done outside the namespace ns3*
+
+constructor, empty function prototypes
+++++++++++++++++++++++++++++++++++++++
+
+key variables (default values, attributes)
+++++++++++++++++++++++++++++++++++++++++++
+
+test program 1
+++++++++++++++
+
+Object Framework
+++++++++++++++++
+
+::
+ static const ClassId cid;
+
+ const InterfaceId ErrorModel::iid =
+ MakeInterfaceId ("ErrorModel", Object::iid);
+
+ const ClassId ErrorModel::cid =
+ MakeClassId<ErrorModel> ("ErrorModel", ErrorModel::iid);
+
+Adding-a-sample-script
+**********************
+
+At this point, one may want to try to take the basic scaffolding defined above
+and add it into the system. Performing this step now allows one to use a simpler
+model when plumbing into the system and may also reveal whether any design or
+API modifications need to be made. Once this is done, we will return to building
+out the functionality of the ErrorModels themselves.
+
+Add basic support in the class
+++++++++++++++++++++++++++++++
+
+::
+
+ point-to-point-net-device.h
+ class ErrorModel;
+
+ /**
+ * Error model for receive packet events
+ */
+ Ptr<ErrorModel> m_receiveErrorModel;
+
+Add Accessor
+++++++++++++
+
+::
+
+ void
+ PointToPointNetDevice::SetReceiveErrorModel (Ptr<ErrorModel> em)
+ {
+ NS_LOG_FUNCTION (this << em);
+ m_receiveErrorModel = em;
+ }
+
+ .AddAttribute ("ReceiveErrorModel",
+ "The receiver error model used to simulate packet loss",
+ PointerValue (),
+ MakePointerAccessor (&PointToPointNetDevice::m_receiveErrorModel),
+ MakePointerChecker<ErrorModel> ())
+
+Plumb into the system
++++++++++++++++++++++
+
+::
+
+ void PointToPointNetDevice::Receive (Ptr<Packet> packet)
+ {
+ NS_LOG_FUNCTION (this << packet);
+ uint16_t protocol = 0;
+
+ if (m_receiveErrorModel && m_receiveErrorModel->IsCorrupt (packet) )
+ {
+ //
+ // If we have an error model and it indicates that it is time to lose a
+ // corrupted packet, don't forward this packet up, let it go.
+ //
+ m_dropTrace (packet);
+ }
+ else
+ {
+ //
+ // Hit the receive trace hook, strip off the point-to-point protocol header
+ // and forward this packet up the protocol stack.
+ //
+ m_rxTrace (packet);
+ ProcessHeader(packet, protocol);
+ m_rxCallback (this, packet, protocol, GetRemote ());
+ if (!m_promiscCallback.IsNull ())
+ { m_promiscCallback (this, packet, protocol, GetRemote (),
+ GetAddress (), NetDevice::PACKET_HOST);
+ }
+ }
+ }
+
+Create null functional script
++++++++++++++++++++++++++++++
+
+::
+
+ simple-error-model.cc
+
+ // Error model
+ // We want to add an error model to node 3's NetDevice
+ // We can obtain a handle to the NetDevice via the channel and node
+ // pointers
+ Ptr<PointToPointNetDevice> nd3 = PointToPointTopology::GetNetDevice
+ (n3, channel2);
+ Ptr<ErrorModel> em = Create<ErrorModel> ();
+ nd3->SetReceiveErrorModel (em);
+
+
+ bool
+ ErrorModel::DoCorrupt (Packet& p)
+ {
+ NS_LOG_FUNCTION;
+ NS_LOG_UNCOND("Corrupt!");
+ return false;
+ }
+
+At this point, we can run the program with our trivial ErrorModel plumbed into
+the receive path of the PointToPointNetDevice. It prints out the string
+"Corrupt!" for each packet received at node n3. Next, we return to the error
+model to add in a subclass that performs more interesting error modeling.
+
+Add subclass
+************
+
+The trivial base class ErrorModel does not do anything interesting, but it
+provides a useful base class interface (Corrupt () and Reset ()), forwarded to
+virtual functions that can be subclassed. Let's next consider what we call a
+BasicErrorModel which is based on the |ns2| ErrorModel class (in
+ns-2/queue/errmodel.@{cc,h@}).
+
+What properties do we want this to have, from a user interface perspective? We
+would like for the user to be able to trivially swap out the type of ErrorModel
+used in the NetDevice. We would also like the capability to set configurable
+parameters.
+
+Here are a few simple requirements we will consider:
+
+* Ability to set the random variable that governs the losses (default is
+ UniformVariable)
+* Ability to set the unit (bit, byte, packet, time) of granularity over which
+ errors are applied.
+* Ability to set the rate of errors (e.g. 10^-3) corresponding to the above unit
+ of granularity.
+* Ability to enable/disable (default is enabled)
+
+How to subclass
++++++++++++++++
+
+We declare BasicErrorModel to be a subclass of ErrorModel as follows,::
+
+ class BasicErrorModel : public ErrorModel
+ {
+ public:
+ static TypeId GetTypeId (void);
+ ...
+ private:
+ // Implement base class pure virtual functions
+ virtual bool DoCorrupt (Ptr<Packet> p);
+ virtual bool DoReset (void);
+ ...
+ }
+
+and configure the subclass GetTypeId function by setting a unique TypeId string
+and setting the Parent to ErrorModel:::
+
+ TypeId RateErrorModel::GetTypeId (void)
+ {
+ static TypeId tid = TypeId ("ns3::RateErrorModel")
+ .SetParent<ErrorModel> ()
+ .AddConstructor<RateErrorModel> ()
+ ...
+
+Build-core-functions-and-unit-tests
+***********************************
+
+assert macros
++++++++++++++
+
+Writing unit tests
+++++++++++++++++++
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/nodes-and-devices-overview.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,50 @@
+.. include:: replace.txt
+
+Node and NetDevices Overview
+----------------------------
+
+This chapter describes how |ns3| nodes are put together, and provides a
+walk-through of how packets traverse an internet-based Node.
+
+.. _node-architecture:
+
+.. figure:: figures/node.*
+
+ High-level node architecture
+
+In |ns3|, nodes are instances of :cpp:class:`ns3::Node`. This class may be
+subclassed, but instead, the conceptual model is that we *aggregate* or insert
+objects to it rather than define subclasses.
+
+One might think of a bare |ns3| node as a shell of a computer, to which one may
+add NetDevices (cards) and other innards including the protocols and
+applications. :ref:`node-architecture` illustrates that :cpp:class:`ns3::Node`
+objects contain a list of :cpp:class:`ns3::Application` instances (initially,
+the list is empty), a list of :cpp:class:`ns3::NetDevice` instances (initially,
+the list is empty), a list of :cpp:class:`ns3::Node::ProtocolHandler` instances,
+a unique integer ID, and a system ID (for distributed simulation).
+
+The design tries to avoid putting too many dependencies on the class
+:cpp:class:`ns3::Node`, :cpp:class:`ns3::Application`, or
+:cpp:class:`ns3::NetDevice` for the following:
+
+* IP version, or whether IP is at all even used in the :cpp:class:`ns3::Node`.
+* implementation details of the IP stack.
+
+From a software perspective, the lower interface of applications corresponds to
+the C-based sockets API. The upper interface of :cpp:class:`ns3::NetDevice`
+objects corresponds to the device independent sublayer of the Linux stack.
+Everything in between can be aggregated and plumbed together as needed.
+
+Let's look more closely at the protocol demultiplexer. We want incoming frames
+at layer-2 to be delivered to the right layer-3 protocol such as IPv4. The
+function of this demultiplexer is to register callbacks for receiving packets.
+The callbacks are indexed based on the `EtherType
+<http://en.wikipedia.org/wiki/EtherType>`_ in the layer-2 frame.
+
+Many different types of higher-layer protocols may be connected to the
+NetDevice, such as IPv4, IPv6, ARP, MPLS, IEEE 802.1x, and packet sockets.
+Therefore, the use of a callback-based demultiplexer avoids the need to use a
+common base class for all of these protocols, which is problematic because of
+the different types of objects (including packet sockets) expected to be
+registered there.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/nodes-and-devices.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,16 @@
+Node and NetDevices
+-------------------
+
+.. toctree::
+
+ nodes-and-devices-overview
+ simple
+ point-to-point
+ csma
+ wifi
+ mesh
+ bridge
+ wimax
+ lte
+ uan
+ energy
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/object-model.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,290 @@
+.. include:: replace.txt
+
+Object model
+------------
+
+|ns3| is fundamentally a C++ object system. Objects can be declared and
+instantiated as usual, per C++ rules. |ns3| also adds some features to
+traditional C++ objects, as described below, to provide greater functionality
+and features. This manual chapter is intended to introduce the reader to the
+|ns3| object model.
+
+This section describes the C++ class design for |ns3| objects. In brief,
+several design patterns in use include classic object-oriented design
+(polymorphic interfaces and implementations), separation of interface and
+implementation, the non-virtual public interface design pattern, an object
+aggregation facility, and reference counting for memory management. Those
+familiar with component models such as COM or Bonobo will recognize elements of
+the design in the |ns3| object aggregation model, although the |ns3| design is
+not strictly in accordance with either.
+
+Object-oriented behavior
+************************
+
+C++ objects, in general, provide common object-oriented capabilities
+(abstraction, encapsulation, inheritance, and polymorphism) that are part
+of classic object-oriented design. |ns3| objects make use of these
+properties; for instance:::
+
+ class Address
+ {
+ public:
+ Address ();
+ Address (uint8_t type, const uint8_t *buffer, uint8_t len);
+ Address (const Address & address);
+ Address &operator = (const Address &address);
+ ...
+ private:
+ uint8_t m_type;
+ uint8_t m_len;
+ ...
+ };
+
+Object base classes
+*******************
+
+There are three special base classes used in |ns3|. Classes that inherit
+from these base classes can instantiate objects with special properties.
+These base classes are:
+
+* class :cpp:class:`Object`
+* class :cpp:class:`ObjectBase`
+* class :cpp:class:`SimpleRefCount`
+
+It is not required that |ns3| objects inherit from these class, but
+those that do get special properties. Classes deriving from
+class :cpp:class:`Object` get the following properties.
+
+* the |ns3| type and attribute system (see :ref:`Attributes`)
+* an object aggregation system
+* a smart-pointer reference counting system (class Ptr)
+
+Classes that derive from class :cpp:class:`ObjectBase` get the first two
+properties above, but do not get smart pointers. Classes that derive from class
+:cpp:class:`SimpleRefCount`: get only the smart-pointer reference counting
+system.
+
+In practice, class :cpp:class:`Object` is the variant of the three above that
+the |ns3| developer will most commonly encounter.
+
+Memory management and class Ptr
+*******************************
+
+Memory management in a C++ program is a complex process, and is often done
+incorrectly or inconsistently. We have settled on a reference counting design
+described as follows.
+
+All objects using reference counting maintain an internal reference count to
+determine when an object can safely delete itself. Each time that a pointer is
+obtained to an interface, the object's reference count is incremented by calling
+``Ref()``. It is the obligation of the user of the pointer to explicitly
+``Unref()`` the pointer when done. When the reference count falls to zero, the
+object is deleted.
+
+* When the client code obtains a pointer from the object itself through object
+ creation, or via GetObject, it does not have to increment the reference count.
+* When client code obtains a pointer from another source (e.g., copying a
+ pointer) it must call ``Ref()`` to increment the reference count.
+* All users of the object pointer must call ``Unref()`` to release the
+ reference.
+
+The burden for calling :cpp:func:`Unref()` is somewhat relieved by the use of
+the reference counting smart pointer class described below.
+
+Users using a low-level API who wish to explicitly allocate
+non-reference-counted objects on the heap, using operator new, are responsible
+for deleting such objects.
+
+Reference counting smart pointer (Ptr)
+++++++++++++++++++++++++++++++++++++++
+
+Calling ``Ref()`` and ``Unref()`` all the time would be cumbersome, so |ns3|
+provides a smart pointer class :cpp:class:`Ptr` similar to
+:cpp:class:`Boost::intrusive_ptr`. This smart-pointer class assumes that the
+underlying type provides a pair of ``Ref`` and ``Unref`` methods that are
+expected to increment and decrement the internal refcount of the object
+instance.
+
+This implementation allows you to manipulate the smart pointer as if it was a
+normal pointer: you can compare it with zero, compare it against other pointers,
+assign zero to it, etc.
+
+It is possible to extract the raw pointer from this smart pointer with the
+:cpp:func:`GetPointer` and :cpp:func:`PeekPointer` methods.
+
+If you want to store a newed object into a smart pointer, we recommend you to
+use the CreateObject template functions to create the object and store it in a
+smart pointer to avoid memory leaks. These functions are really small
+convenience functions and their goal is just to save you a small bit of typing.
+
+CreateObject and Create
++++++++++++++++++++++++
+
+Objects in C++ may be statically, dynamically, or automatically created. This
+holds true for |ns3| also, but some objects in the system have some additional
+frameworks available. Specifically, reference counted objects are usually
+allocated using a templated Create or CreateObject method, as follows.
+
+For objects deriving from class :cpp:class:`Object`:::
+
+ Ptr<WifiNetDevice> device = CreateObject<WifiNetDevice> ();
+
+Please do not create such objects using ``operator new``; create them using
+:cpp:func:`CreateObject()` instead.
+
+For objects deriving from class :cpp:class:`SimpleRefCount`, or other objects
+that support usage of the smart pointer class, a templated helper function is
+available and recommended to be used:::
+
+ Ptr<B> b = Create<B> ();
+
+This is simply a wrapper around operator new that correctly handles the
+reference counting system.
+
+In summary, use ``Create<B>`` if B is not an object but just uses reference
+counting (e.g. :cpp:class:`Packet`), and use ``CreateObject<B>`` if B derives
+from :cpp:class:`ns3::Object`.
+
+Aggregation
++++++++++++
+
+The |ns3| object aggregation system is motivated in strong part by a recognition
+that a common use case for |ns2| has been the use of inheritance and
+polymorphism to extend protocol models. For instance, specialized versions of
+TCP such as RenoTcpAgent derive from (and override functions from) class
+TcpAgent.
+
+However, two problems that have arisen in the |ns2| model are downcasts and
+"weak base class." Downcasting refers to the procedure of using a base class
+pointer to an object and querying it at run time to find out type information,
+used to explicitly cast the pointer to a subclass pointer so that the subclass
+API can be used. Weak base class refers to the problems that arise when a class
+cannot be effectively reused (derived from) because it lacks necessary
+functionality, leading the developer to have to modify the base class and
+causing proliferation of base class API calls, some of which may not be
+semantically correct for all subclasses.
+
+|ns3| is using a version of the query interface design pattern to avoid these
+problems. This design is based on elements of the `Component Object Model
+<http://en.wikipedia.org/wiki/Component_Object_Model>`_ and `GNOME Bonobo
+<http://en.wikipedia.org/wiki/Bonobo_(component_model)>`_ although full
+binary-level compatibility of replaceable components is not supported and we
+have tried to simplify the syntax and impact on model developers.
+
+Aggregation example
++++++++++++++++++++
+
+:cpp:class:`Node` is a good example of the use of aggregation in |ns3|. Note
+that there are not derived classes of Nodes in |ns3| such as class
+:cpp:class:`InternetNode`. Instead, components (protocols) are aggregated to a
+node. Let's look at how some Ipv4 protocols are added to a node.::
+
+ static void
+ AddIpv4Stack(Ptr<Node> node)
+ {
+ Ptr<Ipv4L3Protocol> ipv4 = CreateObject<Ipv4L3Protocol> ();
+ ipv4->SetNode (node);
+ node->AggregateObject (ipv4);
+ Ptr<Ipv4Impl> ipv4Impl = CreateObject<Ipv4Impl> ();
+ ipv4Impl->SetIpv4 (ipv4);
+ node->AggregateObject (ipv4Impl);
+ }
+
+Note that the Ipv4 protocols are created using :cpp:func:`CreateObject()`.
+Then, they are aggregated to the node. In this manner, the Node base class does
+not need to be edited to allow users with a base class Node pointer to access
+the Ipv4 interface; users may ask the node for a pointer to its Ipv4 interface
+at runtime. How the user asks the node is described in the next subsection.
+
+Note that it is a programming error to aggregate more than one object of the
+same type to an :cpp:class:`ns3::Object`. So, for instance, aggregation is not
+an option for storing all of the active sockets of a node.
+
+GetObject example
++++++++++++++++++
+
+GetObject is a type-safe way to achieve a safe downcasting and to allow
+interfaces to be found on an object.
+
+Consider a node pointer ``m_node`` that points to a Node object that has an
+implementation of IPv4 previously aggregated to it. The client code wishes to
+configure a default route. To do so, it must access an object within the node
+that has an interface to the IP forwarding configuration. It performs the
+following:::
+
+ Ptr<Ipv4> ipv4 = m_node->GetObject<Ipv4> ();
+
+If the node in fact does not have an Ipv4 object aggregated to it, then the
+method will return null. Therefore, it is good practice to check the return
+value from such a function call. If successful, the user can now use the Ptr to
+the Ipv4 object that was previously aggregated to the node.
+
+Another example of how one might use aggregation is to add optional models to
+objects. For instance, an existing Node object may have an "Energy Model" object
+aggregated to it at run time (without modifying and recompiling the node class).
+An existing model (such as a wireless net device) can then later "GetObject" for
+the energy model and act appropriately if the interface has been either built in
+to the underlying Node object or aggregated to it at run time. However, other
+nodes need not know anything about energy models.
+
+We hope that this mode of programming will require much less need for developers
+to modify the base classes.
+
+Object factories
+****************
+
+A common use case is to create lots of similarly configured objects. One can
+repeatedly call :cpp:func:`CreateObject` but there is also a factory design
+pattern in use in the |ns3| system. It is heavily used in the "helper" API.
+
+Class :cpp:class:`ObjectFactory` can be used to instantiate objects and to
+configure the attributes on those objects::
+
+ void SetTypeId (TypeId tid);
+ void Set (std::string name, const AttributeValue &value);
+ Ptr<T> Create (void) const;
+
+The first method allows one to use the |ns3| TypeId system to specify the type
+of objects created. The second allows one to set attributes on the objects to be
+created, and the third allows one to create the objects themselves.
+
+For example: ::
+
+ ObjectFactory factory;
+ // Make this factory create objects of type FriisPropagationLossModel
+ factory.SetTypeId ("ns3::FriisPropagationLossModel")
+ // Make this factory object change a default value of an attribute, for
+ // subsequently created objects
+ factory.Set ("SystemLoss", DoubleValue (2.0));
+ // Create one such object
+ Ptr<Object> object = m_factory.Create ();
+ factory.Set ("SystemLoss", DoubleValue (3.0));
+ // Create another object
+ Ptr<Object> object = m_factory.Create ();
+
+Downcasting
+***********
+
+A question that has arisen several times is, "If I have a base class pointer
+(Ptr) to an object and I want the derived class pointer, should I downcast (via
+C++ dynamic cast) to get the derived pointer, or should I use the object
+aggregation system to :cpp:func:`GetObject\<> ()` to find a Ptr to the interface
+to the subclass API?"
+
+The answer to this is that in many situations, both techniques will work.
+|ns3| provides a templated function for making the syntax of Object
+dynamic casting much more user friendly:::
+
+ template <typename T1, typename T2>
+ Ptr<T1>
+ DynamicCast (Ptr<T2> const&p)
+ {
+ return Ptr<T1> (dynamic_cast<T1 *> (PeekPointer (p)));
+ }
+
+DynamicCast works when the programmer has a base type pointer and is testing
+against a subclass pointer. GetObject works when looking for different objects
+aggregated, but also works with subclasses, in the same way as DynamicCast. If
+unsure, the programmer should use GetObject, as it works in all cases. If the
+programmer knows the class hierarchy of the object under consideration, it is
+more direct to just use DynamicCast.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/object-names.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,6 @@
+.. include:: replace.txt
+
+Object names
+------------
+
+*Placeholder chapter*
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/organization.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,57 @@
+.. include:: replace.txt
+
+
+Organization
+------------
+
+This manual is organized into several parts with several chapters per part.
+This chapter describes the overall software organization and the
+corresponding organization of this manual.
+
+|ns3| is a discrete-event network simulator in which the simulation core
+and models are implemented in C++. |ns3| is built as a library which may be
+statically or dynamically linked to a C++ main program that defines the
+simulation topology and starts the simulator. |ns3| also exports nearly all
+of its API to Python, allowing Python programs to import an "ns3" module in
+much the same way as in C++.
+
+.. _software-organization:
+
+.. figure:: figures/software-organization.*
+
+ Software organization of |ns3|
+
+The source code for |ns3| is mostly organized in the ``src`` directory and
+can be described by the diagram in :ref:`software-organization`. We will
+work our way from the bottom up; in general, modules only have dependencies
+on modules beneath them in the figure.
+
+We first describe Part 1 of the manual. The simulation core is implemented
+in ``src/core``, and the core is used to build the simulation engine
+``src/simulator``. Packets are fundamental objects in a network simulator
+and are implemented in ``src/packet``. These three simulation modules by
+themselves are intended to comprise a generic simulation core that can be
+used by different kinds of networks, not just Internet-based networks. The
+above modules of |ns3| are independent of specific network and device
+models, which are covered in later parts of this manual.
+
+In addition to the above |ns3| core, we describe also in Part 1 two other
+modules that supplement the core C++-based API. |ns3| programs may access
+all of the API directly or may make use of a so-called *helper API* that
+provides convenient wrappers or encapsulation of low-level API calls. The
+fact that |ns3| programs can be written to two APIs (or a combination
+thereof) is a fundamental aspect of the simulator and is also covered in
+Part 1. We also describe how Python is supported in |ns3| as the last
+chapter of Part 1.
+
+The remainder of the manual is focused on documenting the models and
+supporting capabilities. Part 2 focuses on two fundamental objects in
+|ns3|: the ``Node`` and ``NetDevice``. Two special NetDevice types are
+designed to support network emulation use cases, and emulation is described
+in Part 3. Part 4 is devoted to Internet-related models, including the
+sockets API used by Internet applications. Part 5 covers applications, and
+Part 6 describes additional support for simulation, such as animators.
+
+The project maintains a separate manual devoted to testing and validation
+of |ns3| code (see the `ns-3 Testing and Validation manual
+<http://www.nsnam.org/tutorials.html>`_).
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/packets.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,660 @@
+.. include:: replace.txt
+
+Packets
+-------
+
+The design of the Packet framework of *ns* was heavily guided by a few
+important use-cases:
+
+* avoid changing the core of the simulator to introduce new types of packet
+ headers or trailers
+* maximize the ease of integration with real-world code and systems
+* make it easy to support fragmentation, defragmentation, and, concatenation
+ which are important, especially in wireless systems.
+* make memory management of this object efficient
+* allow actual application data or dummy application bytes for emulated
+ applications
+
+Each network packet contains a byte buffer, a set of byte tags, a set of packet
+tags, and metadata.
+
+The byte buffer stores the serialized content of the headers and trailers added
+to a packet. The serialized representation of these headers is expected to match
+that of real network packets bit for bit (although nothing forces you to do
+this) which means that the content of a packet buffer is expected to be that of
+a real packet.
+
+Fragmentation and defragmentation are quite natural to implement within this
+context: since we have a buffer of real bytes, we can split it in multiple
+fragments and re-assemble these fragments. We expect that this choice will make
+it really easy to wrap our Packet data structure within Linux-style skb or
+BSD-style mbuf to integrate real-world kernel code in the simulator. We also
+expect that performing a real-time plug of the simulator to a real-world network
+will be easy.
+
+One problem that this design choice raises is that it is difficult to
+pretty-print the packet headers without context. The packet metadata describes
+the type of the headers and trailers which were serialized in the byte buffer.
+The maintenance of metadata is optional and disabled by default. To enable it,
+you must call Packet::EnableMetadata() and this will allow you to get non-empty
+output from Packet::Print and Packet::Print.
+
+Also, developers often want to store data in packet objects that is not found
+in the real packets (such as timestamps or flow-ids). The Packet class
+deals with this requirement by storing a set of tags (class Tag).
+We have found two classes of use cases for these tags, which leads to
+two different types of tags. So-called 'byte' tags are used to tag a subset of
+the bytes in the packet byte buffer while 'packet' tags are used to tag the
+packet itself. The main difference between these two kinds of tags is what
+happens when packets are copied, fragmented, and reassembled: 'byte' tags follow
+bytes while 'packet' tags follow packets. Another important difference between
+these two kinds of tags is that byte tags cannot be removed and are expected to
+be written once, and read many times, while packet tags are expected to be
+written once, read many times, and removed exactly once. An example of a 'byte'
+tag is a FlowIdTag which contains a flow id and is set by the application
+generating traffic. An example of a 'packet' tag is a cross-layer QoS class id
+set by an application and processed by a lower-level MAC layer.
+
+Memory management of Packet objects is entirely automatic and extremely
+efficient: memory for the application-level payload can be modeled by a virtual
+buffer of zero-filled bytes for which memory is never allocated unless
+explicitly requested by the user or unless the packet is fragmented or
+serialized out to a real network device. Furthermore, copying, adding, and,
+removing headers or trailers to a packet has been optimized to be virtually free
+through a technique known as Copy On Write.
+
+Packets (messages) are fundamental objects in the simulator and
+their design is important from a performance and resource management
+perspective. There are various ways to design the simulation packet, and
+tradeoffs among the different approaches. In particular, there is a tension
+between ease-of-use, performance, and safe interface design.
+
+Packet design overview
+**********************
+
+Unlike |ns2|, in which Packet objects contain a buffer of C++
+structures corresponding to protocol headers, each network packet in
+|ns3| contains a byte Buffer, a list of byte Tags, a list of
+packet Tags, and a PacketMetadata object:
+
+* The byte buffer stores the serialized content of the chunks added to a packet.
+ The serialized representation of these chunks is expected to match that of
+ real network packets bit for bit (although nothing forces you to do this)
+ which means that the content of a packet buffer is expected to be that of a
+ real packet. Packets can also be created with an arbitrary zero-filled
+ payload for which no real memory is allocated.
+* Each list of tags stores an arbitrarily large set of arbitrary user-provided
+ data structures in the packet. Each Tag is uniquely identified by its type;
+ only one instance of each type of data structure is allowed in a list of tags.
+ These tags typically contain per-packet cross-layer information or flow
+ identifiers (i.e., things that you wouldn't find in the bits on the wire).
+
+.. _packets:
+
+.. figure:: figures/packet.*
+
+ Implementation overview of Packet class.
+
+Figure :ref:`packets` is a high-level overview of the Packet implementation;
+more detail on the byte Buffer implementation is provided later in Figure
+:ref:`buffer`. In |ns3|, the Packet byte buffer is analogous to a Linux skbuff
+or BSD mbuf; it is a serialized representation of the actual data in the packet.
+The tag lists are containers for extra items useful for simulation convenience;
+if a Packet is converted to an emulated packet and put over an actual network,
+the tags are stripped off and the byte buffer is copied directly into a real
+packet.
+
+Packets are reference counted objects. They are handled with smart pointer (Ptr)
+objects like many of the objects in the |ns3| system. One small difference you
+will see is that class Packet does not inherit from class Object or class
+RefCountBase, and implements the Ref() and Unref() methods directly. This was
+designed to avoid the overhead of a vtable in class Packet.
+
+The Packet class is designed to be copied cheaply; the overall design
+is based on Copy on Write (COW). When there are multiple references
+to a packet object, and there is an operation on one of them, only
+so-called "dirty" operations will trigger a deep copy of the packet:
+
+* ``ns3::Packet::AddHeader()``
+* ``ns3::Packet::AddTrailer()``
+* ``both versions of ns3::Packet::AddAtEnd()``
+* ``Packet::RemovePacketTag()``
+
+The fundamental classes for adding to and removing from the byte buffer are
+``class Header`` and ``class Trailer``. Headers are more common but the below
+discussion also largely applies to protocols using trailers. Every protocol
+header that needs to be inserted and removed from a Packet instance should
+derive from the abstract Header base class and implement the private pure
+virtual methods listed below:
+
+* ``ns3::Header::SerializeTo()``
+* ``ns3::Header::DeserializeFrom()``
+* ``ns3::Header::GetSerializedSize()``
+* ``ns3::Header::PrintTo()``
+
+Basically, the first three functions are used to serialize and deserialize
+protocol control information to/from a Buffer. For example, one may define
+@code{class TCPHeader : public Header}. The TCPHeader object will typically
+consist of some private data (like a sequence number) and public interface
+access functions (such as checking the bounds of an input). But the underlying
+representation of the TCPHeader in a Packet Buffer is 20 serialized bytes (plus
+TCP options). The TCPHeader::SerializeTo() function would therefore be designed
+to write these 20 bytes properly into the packet, in network byte order. The
+last function is used to define how the Header object prints itself onto an
+output stream.
+
+Similarly, user-defined Tags can be appended to the packet. Unlike Headers,
+Tags are not serialized into a contiguous buffer but are stored in lists. Tags
+can be flexibly defined to be any type, but there can only be one instance of
+any particular object type in the Tags buffer at any time.
+
+Using the packet interface
+**************************
+
+This section describes how to create and use the ``ns3::Packet`` object.
+
+Creating a new packet
++++++++++++++++++++++
+
+The following command will create a new packet with a new unique Id.::
+
+ Ptr<Packet> pkt = Create<Packet> ();
+
+What is the Uid (unique Id)? It is an internal id that the system uses to
+identify packets. It can be fetched via the following method:::
+
+ uint32_t uid = pkt->GetUid ();
+
+But please note the following. This uid is an internal uid and cannot be counted
+on to provide an accurate counter of how many "simulated packets" of a
+particular protocol are in the system. It is not trivial to make this uid into
+such a counter, because of questions such as what should the uid be when the
+packet is sent over broadcast media, or when fragmentation occurs. If a user
+wants to trace actual packet counts, he or she should look at e.g. the IP ID
+field or transport sequence numbers, or other packet or frame counters at other
+protocol layers.
+
+We mentioned above that it is possible to create packets with zero-filled
+payloads that do not actually require a memory allocation (i.e., the packet may
+behave, when delays such as serialization or transmission delays are computed,
+to have a certain number of payload bytes, but the bytes will only be allocated
+on-demand when needed). The command to do this is, when the packet is
+created:::
+
+ Ptr<Packet> pkt = Create<Packet> (N);
+
+where N is a positive integer.
+
+The packet now has a size of N bytes, which can be verified by the GetSize()
+method:::
+
+ /**
+ * \returns the size in bytes of the packet (including the zero-filled
+ * initial payload)
+ */
+ uint32_t GetSize (void) const;
+
+You can also initialize a packet with a character buffer. The input
+data is copied and the input buffer is untouched. The constructor
+applied is:::
+
+ Packet (uint8_t const *buffer, uint32_t size);
+
+Here is an example:::
+
+ Ptr<Packet> pkt1 = Create<Packet> (reinterpret_cast<const uint8_t*> ("hello"), 5);
+
+Packets are freed when there are no more references to them, as with all |ns3|
+objects referenced by the Ptr class.
+
+Adding and removing Buffer data
++++++++++++++++++++++++++++++++
+
+After the initial packet creation (which may possibly create some fake initial
+bytes of payload), all subsequent buffer data is added by adding objects of
+class Header or class Trailer. Note that, even if you are in the application
+layer, handling packets, and want to write application data, you write it as an
+ns3::Header or ns3::Trailer. If you add a Header, it is prepended to the
+packet, and if you add a Trailer, it is added to the end of the packet. If you
+have no data in the packet, then it makes no difference whether you add a Header
+or Trailer. Since the APIs and classes for header and trailer are pretty much
+identical, we'll just look at class Header here.
+
+The first step is to create a new header class. All new Header classes
+must inherit from class Header, and implement the following methods:
+
+* ``Serialize ()``
+* ``Deserialize ()``
+* ``GetSerializedSize ()``
+* ``Print ()``
+
+To see a simple example of how these are done, look at the UdpHeader class
+headers src/internet-stack/udp-header.cc. There are many other examples within
+the source code.
+
+Once you have a header (or you have a preexisting header), the following
+Packet API can be used to add or remove such headers.::
+
+ /**
+ * Add header to this packet. This method invokes the
+ * Header::GetSerializedSize and Header::Serialize
+ * methods to reserve space in the buffer and request the
+ * header to serialize itself in the packet buffer.
+ *
+ * \param header a reference to the header to add to this packet.
+ */
+ void AddHeader (const Header & header);
+ /**
+ * Deserialize and remove the header from the internal buffer.
+ * This method invokes Header::Deserialize.
+ *
+ * \param header a reference to the header to remove from the internal buffer.
+ * \returns the number of bytes removed from the packet.
+ */
+ uint32_t RemoveHeader (Header &header);
+ /**
+ * Deserialize but does _not_ remove the header from the internal buffer.
+ * This method invokes Header::Deserialize.
+ *
+ * \param header a reference to the header to read from the internal buffer.
+ * \returns the number of bytes read from the packet.
+ */
+ uint32_t PeekHeader (Header &header) const;
+
+For instance, here are the typical operations to add and remove a UDP header.::
+
+ // add header
+ Ptr<Packet> packet = Create<Packet> ();
+ UdpHeader udpHeader;
+ // Fill out udpHeader fields appropriately
+ packet->AddHeader (udpHeader);
+ ...
+ // remove header
+ UdpHeader udpHeader;
+ packet->RemoveHeader (udpHeader);
+ // Read udpHeader fields as needed
+
+Adding and removing Tags
+++++++++++++++++++++++++
+
+There is a single base class of Tag that all packet tags must derive from. They
+are used in two different tag lists in the packet; the lists have different
+semantics and different expected use cases.
+
+As the names imply, ByteTags follow bytes and PacketTags follow packets. What
+this means is that when operations are done on packets, such as fragmentation,
+concatenation, and appending or removing headers, the byte tags keep track of
+which packet bytes they cover. For instance, if a user creates a TCP segment,
+and applies a ByteTag to the segment, each byte of the TCP segment will be
+tagged. However, if the next layer down inserts an IPv4 header, this ByteTag
+will not cover those bytes. The converse is true for the PacketTag; it covers a
+packet despite the operations on it.
+
+PacketTags are limited in size to 20 bytes. This is a modifiable compile-time
+constant in ``src/common/packet-tag-list.h``. ByteTags have no such restriction.
+
+Each tag type must subclass ``ns3::Tag``, and only one instance of
+each Tag type may be in each tag list. Here are a few differences in the
+behavior of packet tags and byte tags.
+
+* **Fragmentation:** As mentioned above, when a packet is fragmented, each
+ packet fragment (which is a new packet) will get a copy of all packet tags,
+ and byte tags will follow the new packet boundaries (i.e. if the fragmented
+ packets fragment across a buffer region covered by the byte tag, both packet
+ fragments will still have the appropriate buffer regions byte tagged).
+* **Concatenation:** When packets are combined, two different buffer regions
+ will become one. For byte tags, the byte tags simply follow the respective
+ buffer regions. For packet tags, only the tags on the first packet survive
+ the merge.
+* **Finding and Printing:** Both classes allow you to iterate over all of the
+ tags and print them.
+* **Removal:** Users can add and remove the same packet tag multiple times on a
+ single packet (AddPacketTag () and RemovePacketTag ()). The packet However,
+ once a byte tag is added, it can only be removed by stripping all byte tags
+ from the packet. Removing one of possibly multiple byte tags is not supported
+ by the current API.
+
+As of *ns-3.5*, Tags are not serialized and deserialized to a buffer when
+``Packet::Serialize ()`` and ``Packet::Deserialize ()`` are called; this is an
+open bug.
+
+If a user wants to take an existing packet object and reuse it as a new packet,
+he or she should remove all byte tags and packet tags before doing so. An
+example is the UdpEchoServer class, which takes the received packet and "turns
+it around" to send back to the echo client.
+
+The Packet API for byte tags is given below.::
+
+ /**
+ * \param tag the new tag to add to this packet
+ *
+ * Tag each byte included in this packet with the
+ * new tag.
+ *
+ * Note that adding a tag is a const operation which is pretty
+ * un-intuitive. The rationale is that the content and behavior of
+ * a packet is _not_ changed when a tag is added to a packet: any
+ * code which was not aware of the new tag is going to work just
+ * the same if the new tag is added. The real reason why adding a
+ * tag was made a const operation is to allow a trace sink which gets
+ * a packet to tag the packet, even if the packet is const (and most
+ * trace sources should use const packets because it would be
+ * totally evil to allow a trace sink to modify the content of a
+ * packet).
+ */
+ void AddByteTag (const Tag &tag) const;
+ /**
+ * \returns an iterator over the set of byte tags included in this packet.
+ */
+ ByteTagIterator GetByteTagIterator (void) const;
+ /**
+ * \param tag the tag to search in this packet
+ * \returns true if the requested tag type was found, false otherwise.
+ *
+ * If the requested tag type is found, it is copied in the user's
+ * provided tag instance.
+ */
+ bool FindFirstMatchingByteTag (Tag &tag) const;
+
+ /**
+ * Remove all the tags stored in this packet.
+ */
+ void RemoveAllByteTags (void);
+
+ /**
+ * \param os output stream in which the data should be printed.
+ *
+ * Iterate over the tags present in this packet, and
+ * invoke the Print method of each tag stored in the packet.
+ */
+ void PrintByteTags (std::ostream &os) const;
+
+The Packet API for packet tags is given below.::
+
+ /**
+ * \param tag the tag to store in this packet
+ *
+ * Add a tag to this packet. This method calls the
+ * Tag::GetSerializedSize and, then, Tag::Serialize.
+ *
+ * Note that this method is const, that is, it does not
+ * modify the state of this packet, which is fairly
+ * un-intuitive.
+ */
+ void AddPacketTag (const Tag &tag) const;
+ /**
+ * \param tag the tag to remove from this packet
+ * \returns true if the requested tag is found, false
+ * otherwise.
+ *
+ * Remove a tag from this packet. This method calls
+ * Tag::Deserialize if the tag is found.
+ */
+ bool RemovePacketTag (Tag &tag);
+ /**
+ * \param tag the tag to search in this packet
+ * \returns true if the requested tag is found, false
+ * otherwise.
+ *
+ * Search a matching tag and call Tag::Deserialize if it is found.
+ */
+ bool PeekPacketTag (Tag &tag) const;
+ /**
+ * Remove all packet tags.
+ */
+ void RemoveAllPacketTags (void);
+
+ /**
+ * \param os the stream in which we want to print data.
+ *
+ * Print the list of 'packet' tags.
+ *
+ * \sa Packet::AddPacketTag, Packet::RemovePacketTag, Packet::PeekPacketTag,
+ * Packet::RemoveAllPacketTags
+ */
+ void PrintPacketTags (std::ostream &os) const;
+
+ /**
+ * \returns an object which can be used to iterate over the list of
+ * packet tags.
+ */
+ PacketTagIterator GetPacketTagIterator (void) const;
+
+Here is a simple example illustrating the use of tags from the
+code in ``src/internet-stack/udp-socket-impl.cc``:::
+
+ Ptr<Packet> p; // pointer to a pre-existing packet
+ SocketIpTtlTag tag
+ tag.SetTtl (m_ipMulticastTtl); // Convey the TTL from UDP layer to IP layer
+ p->AddPacketTag (tag);
+
+This tag is read at the IP layer, then stripped (``src/internet-stack/ipv4-l3-protocol.cc``):::
+
+ uint8_t ttl = m_defaultTtl;
+ SocketIpTtlTag tag;
+ bool found = packet->RemovePacketTag (tag);
+ if (found)
+ {
+ ttl = tag.GetTtl ();
+ }
+
+Fragmentation and concatenation
++++++++++++++++++++++++++++++++
+
+Packets may be fragmented or merged together. For example, to fragment a packet
+``p`` of 90 bytes into two packets, one containing the first 10 bytes and the
+other containing the remaining 80, one may call the following code:::
+
+ Ptr<Packet> frag0 = p->CreateFragment (0, 10);
+ Ptr<Packet> frag1 = p->CreateFragment (10, 90);
+
+As discussed above, the packet tags from ``p`` will follow to both packet
+fragments, and the byte tags will follow the byte ranges as needed.
+
+Now, to put them back together:::
+
+ frag0->AddAtEnd (frag1);
+
+Now frag0 should be equivalent to the original packet ``p``. If, however, there
+were operations on the fragments before being reassembled (such as tag
+operations or header operations), the new packet will not be the same.
+
+Enabling metadata
++++++++++++++++++
+
+We mentioned above that packets, being on-the-wire representations of byte
+buffers, present a problem to print out in a structured way unless the printing
+function has access to the context of the header. For instance, consider a
+tcpdump-like printer that wants to pretty-print the contents of a packet.
+
+To enable this usage, packets may have metadata enabled (disabled by default for
+performance reasons). This class is used by the Packet class to record every
+operation performed on the packet's buffer, and provides an implementation of
+``Packet::Print ()`` method that uses the metadata to analyze the content of the
+packet's buffer.
+
+The metadata is also used to perform extensive sanity checks at runtime when
+performing operations on a Packet. For example, this metadata is used to verify
+that when you remove a header from a packet, this same header was actually
+present at the front of the packet. These errors will be detected and will abort
+the program.
+
+To enable this operation, users will typically insert one or both of these
+statements at the beginning of their programs:::
+
+ Packet::EnablePrinting ();
+ Packet::EnableChecking ();
+
+Sample programs
+***************
+
+See ``samples/main-packet.cc`` and ``samples/main-packet-tag.cc``.
+
+Implementation details
+**********************
+
+Private member variables
+++++++++++++++++++++++++
+
+A Packet object's interface provides access to some private data:::
+
+ Buffer m_buffer;
+ ByteTagList m_byteTagList;
+ PacketTagList m_packetTagList;
+ PacketMetadata m_metadata;
+ mutable uint32_t m_refCount;
+ static uint32_t m_globalUid;
+
+Each Packet has a Buffer and two Tags lists, a PacketMetadata object, and a ref
+count. A static member variable keeps track of the UIDs allocated. The actual
+uid of the packet is stored in the PacketMetadata.
+
+Note:
+that real network packets do not have a UID; the UID is therefore an instance of
+data that normally would be stored as a Tag in the packet. However, it was felt
+that a UID is a special case that is so often used in simulations that it would
+be more convenient to store it in a member variable.
+
+Buffer implementation
++++++++++++++++++++++
+
+Class Buffer represents a buffer of bytes. Its size is automatically adjusted to
+hold any data prepended or appended by the user. Its implementation is optimized
+to ensure that the number of buffer resizes is minimized, by creating new
+Buffers of the maximum size ever used. The correct maximum size is learned at
+runtime during use by recording the maximum size of each packet.
+
+Authors of new Header or Trailer classes need to know the public API of the
+Buffer class. (add summary here)
+
+The byte buffer is implemented as follows: ::
+
+ struct BufferData {
+ uint32_t m_count;
+ uint32_t m_size;
+ uint32_t m_initialStart;
+ uint32_t m_dirtyStart;
+ uint32_t m_dirtySize;
+ uint8_t m_data[1];
+ };
+ struct BufferData *m_data;
+ uint32_t m_zeroAreaSize;
+ uint32_t m_start;
+ uint32_t m_size;
+
+* ``BufferData::m_count``: reference count for BufferData structure
+* ``BufferData::m_size``: size of data buffer stored in BufferData structure
+* ``BufferData::m_initialStart``: offset from start of data buffer where data
+ was first inserted
+* ``BufferData::m_dirtyStart``: offset from start of buffer where every Buffer
+ which holds a reference to this BufferData instance have written data so far
+* ``BufferData::m_dirtySize``: size of area where data has been written so far
+* ``BufferData::m_data``: pointer to data buffer
+* ``Buffer::m_zeroAreaSize``: size of zero area which extends before
+ ``m_initialStart``
+* ``Buffer::m_start``: offset from start of buffer to area used by this buffer
+* ``Buffer::m_size``: size of area used by this Buffer in its BufferData
+ structure
+
+.. _buffer:
+
+.. figure:: figures/buffer.*
+
+ Implementation overview of a packet's byte Buffer.
+
+
+This data structure is summarized in Figure :ref:`buffer`. Each Buffer holds a
+pointer to an instance of a BufferData. Most Buffers should be able to share the
+same underlying BufferData and thus simply increase the BufferData's reference
+count. If they have to change the content of a BufferData inside the Dirty Area,
+and if the reference count is not one, they first create a copy of the
+BufferData and then complete their state-changing operation.
+
+Tags implementation
++++++++++++++++++++
+
+(XXX revise me)
+
+Tags are implemented by a single pointer which points to the start of a
+linked list ofTagData data structures. Each TagData structure points
+to the next TagData in the list (its next pointer contains zero to
+indicate the end of the linked list). Each TagData contains an integer
+unique id which identifies the type of the tag stored in the TagData.::
+
+ struct TagData {
+ struct TagData *m_next;
+ uint32_t m_id;
+ uint32_t m_count;
+ uint8_t m_data[Tags::SIZE];
+ };
+ class Tags {
+ struct TagData *m_next;
+ };
+
+Adding a tag is a matter of inserting a new TagData at the head of the linked
+list. Looking at a tag requires you to find the relevant TagData in the linked
+list and copy its data into the user data structure. Removing a tag and updating
+the content of a tag requires a deep copy of the linked list before performing
+this operation. On the other hand, copying a Packet and its tags is a matter of
+copying the TagData head pointer and incrementing its reference count.
+
+Tags are found by the unique mapping between the Tag type and
+its underlying id. This is why at most one instance of any Tag
+can be stored in a packet. The mapping between Tag type and
+underlying id is performed by a registration as follows:::
+
+ /* A sample Tag implementation
+ */
+ struct MyTag {
+ uint16_t m_streamId;
+ };
+
+Memory management
++++++++++++++++++
+
+*Describe dataless vs. data-full packets.*
+
+Copy-on-write semantics
++++++++++++++++++++++++
+
+The current implementation of the byte buffers and tag list is based on COW
+(Copy On Write). An introduction to COW can be found in Scott Meyer's "More
+Effective C++", items 17 and 29). This design feature and aspects of the public
+interface borrows from the packet design of the Georgia Tech Network Simulator.
+This implementation of COW uses a customized reference counting smart pointer
+class.
+
+What COW means is that copying packets without modifying them is very cheap (in
+terms of CPU and memory usage) and modifying them can be also very cheap. What
+is key for proper COW implementations is being able to detect when a given
+modification of the state of a packet triggers a full copy of the data prior to
+the modification: COW systems need to detect when an operation is "dirty" and
+must therefore invoke a true copy.
+
+Dirty operations:
+
+* ns3::Packet::AddHeader
+* ns3::Packet::AddTrailer
+* both versions of ns3::Packet::AddAtEnd
+* ns3::Packet::RemovePacketTag
+
+Non-dirty operations:
+
+* ns3::Packet::AddPacketTag
+* ns3::Packet::PeekPacketTag
+* ns3::Packet::RemoveAllPacketTags
+* ns3::Packet::AddByteTag
+* ns3::Packet::FindFirstMatchingByteTag
+* ns3::Packet::RemoveAllByteTags
+* ns3::Packet::RemoveHeader
+* ns3::Packet::RemoveTrailer
+* ns3::Packet::CreateFragment
+* ns3::Packet::RemoveAtStart
+* ns3::Packet::RemoveAtEnd
+* ns3::Packet::CopyData
+
+Dirty operations will always be slower than non-dirty operations, sometimes by
+several orders of magnitude. However, even the dirty operations have been
+optimized for common use-cases which means that most of the time, these
+operations will not trigger data copies and will thus be still very fast.
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/point-to-point.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,160 @@
+.. include:: replace.txt
+
+PointToPoint NetDevice
+----------------------
+
+This is the introduction to PointToPoint NetDevice chapter, to complement the
+PointToPoint model doxygen.
+
+Overview of the PointToPoint model
+**********************************
+
+The |ns3| point-to-point model is of a very simple point to point data link
+connecting exactly two PointToPointNetDevice devices over an
+PointToPointChannel. This can be viewed as equivalent to a full duplex RS-232 or
+RS-422 link with null modem and no handshaking.
+
+Data is encapsulated in the Point-to-Point Protocol (PPP -- RFC 1661), however
+the Link Control Protocol (LCP) and associated state machine is not implemented.
+The PPP link is assumed to be established and authenticated at all times.
+
+Data is not framed, therefore Address and Control fields will not be found.
+Since the data is not framed, there is no need to provide Flag Sequence and
+Control Escape octets, nor is a Frame Check Sequence appended. All that is
+required to implement non-framed PPP is to prepend the PPP protocol number for
+IP Version 4 which is the sixteen-bit number 0x21 (see
+`<http://www.iana.org/assignments/ppp-numbers>`_).
+
+The PointToPointNetDevice provides following Attributes:
+
+* Address: The ns3::Mac48Address of the device (if desired);
+* DataRate: The data rate (ns3::DataRate) of the device;
+* TxQueue: The transmit queue (ns3::Queue) used by the device;
+* InterframeGap: The optional ns3::Time to wait between "frames";
+* Rx: A trace source for received packets;
+* Drop: A trace source for dropped packets.
+
+The PointToPointNetDevice models a transmitter section that puts bits on a
+corresponding channel "wire." The DataRate attribute specifies the number of
+bits per second that the device will simulate sending over the channel. In
+reality no bits are sent, but an event is scheduled for an elapsed time
+consistent with the number of bits in each packet and the specified DataRate.
+The implication here is that the receiving device models a receiver section that
+can receive any any data rate. Therefore there is no need, nor way to set a
+receive data rate in this model. By setting the DataRate on the transmitter of
+both devices connected to a given PointToPointChannel one can model a symmetric
+channel; or by setting different DataRates one can model an asymmetric channel
+(e.g., ADSL).
+
+The PointToPointNetDevice supports the assignment of a "receive error model."
+This is an ErrorModel object that is used to simulate data corruption on the
+link.
+
+Point-to-Point Channel Model
+****************************
+
+The point to point net devices are connected via an PointToPointChannel. This
+channel models two wires transmitting bits at the data rate specified by the
+source net device. There is no overhead beyond the eight bits per byte of the
+packet sent. That is, we do not model Flag Sequences, Frame Check Sequences nor
+do we "escape" any data.
+
+The PointToPointChannel provides following Attributes:
+
+
+* Delay: An ns3::Time specifying the speed of light transmission delay for the
+ channel.
+
+Using the PointToPointNetDevice
+*******************************
+
+The PointToPoint net devices and channels are typically created and configured
+using the associated ``PointToPointHelper`` object. The various ns3 device
+helpers generally work in a similar way, and their use is seen in many of our
+example programs and is also covered in the |ns3| tutorial.
+
+The conceptual model of interest is that of a bare computer "husk" into which
+you plug net devices. The bare computers are created using a ``NodeContainer``
+helper. You just ask this helper to create as many computers (we call them
+``Nodes``) as you need on your network:::
+
+ NodeContainer nodes;
+ nodes.Create (2);
+
+Once you have your nodes, you need to instantiate a ``PointToPointHelper`` and
+set any attributes you may want to change. Note that since this is a
+point-to-point (as compared to a point-to-multipoint) there may only be two
+nodes with associated net devices connected by a PointToPointChannel.::
+
+ PointToPointHelper pointToPoint;
+ pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
+ pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));
+
+Once the attributes are set, all that remains is to create the devices and
+install them on the required nodes, and to connect the devices together using a
+PointToPoint channel. When we create the net devices, we add them to a container
+to allow you to use them in the future. This all takes just one line of code.::
+
+ NetDeviceContainer devices = pointToPoint.Install (nodes);
+
+PointToPoint Tracing
+********************
+
+Like all |ns3| devices, the Point-to-Point Model provides a number of trace
+sources. These trace sources can be hooked using your own custom trace code, or
+you can use our helper functions to arrange for tracing to be enabled on devices
+you specify.
+
+Upper-Level (MAC) Hooks
++++++++++++++++++++++++
+
+From the point of view of tracing in the net device, there are several
+interesting points to insert trace hooks. A convention inherited from other
+simulators is that packets destined for transmission onto attached networks pass
+through a single "transmit queue" in the net device. We provide trace hooks at
+this point in packet flow, which corresponds (abstractly) only to a transition
+from the network to data link layer, and call them collectively
+the device MAC hooks.
+
+When a packet is sent to the Point-to-Point net device for transmission it
+always passes through the transmit queue. The transmit queue in the
+PointToPointNetDevice inherits from Queue, and therefore inherits three trace
+sources:::
+
+* An Enqueue operation source (see ns3::Queue::m_traceEnqueue);
+* A Dequeue operation source (see ns3::Queue::m_traceDequeue);
+* A Drop operation source (see ns3::Queue::m_traceDrop).
+
+The upper-level (MAC) trace hooks for the PointToPointNetDevice are, in fact,
+exactly these three trace sources on the single transmit queue of the device.
+
+The m_traceEnqueue event is triggered when a packet is placed on the transmit
+queue. This happens at the time that ns3::PointtoPointNetDevice::Send or
+ns3::PointToPointNetDevice::SendFrom is called by a higher layer to queue a
+packet for transmission. An Enqueue trace event firing should be interpreted
+as only indicating that a higher level protocol has sent a packet to the device.
+
+The m_traceDequeue event is triggered when a packet is removed from the transmit
+queue. Dequeues from the transmit queue can happen in two situations: 1) If the
+underlying channel is idle when PointToPointNetDevice::Send is called, a packet
+is dequeued from the transmit queue and immediately transmitted; 2) a packet
+may be dequeued and immediately transmitted in an internal TransmitCompleteEvent
+that functions much like a transmit complete interrupt service routine. An
+Dequeue trace event firing may be viewed as indicating that the
+PointToPointNetDevice has begun transmitting a packet.
+
+Lower-Level (PHY) Hooks
++++++++++++++++++++++++
+
+Similar to the upper level trace hooks, there are trace hooks available at the
+lower levels of the net device. We call these the PHY hooks. These events fire
+from the device methods that talk directly to the
+PointToPointChannel.
+
+The trace source m_dropTrace is called to indicate a packet that is dropped by
+the device. This happens when a packet is discarded as corrupt due to a receive
+error model indication (see ns3::ErrorModel and the associated attribute
+"ReceiveErrorModel").
+
+The other low-level trace source fires on reception of a packet (see
+ns3::PointToPointNetDevice::m_rxTrace) from the PointToPointChannel.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/python.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,9 @@
+.. include:: replace.txt
+
+Python
+------
+
+**Placeholder chapter**
+
+For now, please see the Python wiki page at
+`<http://www.nsnam.org/wiki/index.php/NS-3_Python_Bindings>`_.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/random-variables.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,289 @@
+.. include:: replace.txt
+
+Random Variables
+----------------
+
+|ns3| contains a built-in pseudo-random number generator (PRNG). It is important
+for serious users of the simulator to understand the functionality,
+configuration, and usage of this PRNG, and to decide whether it is sufficient
+for his or her research use.
+
+Quick Overview
+**************
+
+|ns3| random numbers are provided via instances of
+:cpp:class:`ns3::RandomVariable`.
+
+* by default, |ns3| simulations use a fixed seed; if there is any randomness in
+ the simulation, each run of the program will yield identical results unless
+ the seed and/or run number is changed.
+
+* in *ns-3.3* and earlier, |ns3| simulations used a random seed by default; this
+ marks a change in policy starting with *ns-3.4*.
+
+* to obtain randomness across multiple simulation runs, you must either set the
+ seed differently or set the run number differently. To set a seed, call
+ :cpp:func:`ns3::SeedManager::SetSeed` at the beginning of the program; to set
+ a run number with the same seed, call :cpp:func:`ns3::SeedManager::SetRun` at
+ the beginning of the program; see :ref:`seeding-and-independent-replications`.
+
+* each RandomVariable used in |ns3| has a virtual random number generator
+ associated with it; all random variables use either a fixed or random seed
+ based on the use of the global seed (previous bullet);
+
+* if you intend to perform multiple runs of the same scenario, with different
+ random numbers, please be sure to read the section on how to perform
+ independent replications: :ref:`seeding-and-independent-replications`.
+
+Read further for more explanation about the random number facility for |ns3|.
+
+Background
+**********
+
+Simulations use a lot of random numbers; one study
+found that most network simulations spend as much as 50%
+of the CPU generating random numbers. Simulation users need
+to be concerned with the quality of the (pseudo) random numbers and
+the independence between different streams of random numbers.
+
+Users need to be concerned with a few issues, such as:
+
+* the seeding of the random number generator and whether a
+ simulation outcome is deterministic or not,
+* how to acquire different streams of random numbers that are
+ independent from one another, and
+* how long it takes for streams to cycle
+
+We will introduce a few terms here: a RNG provides a long sequence
+of (pseudo) random numbers.
+The length of this sequence is called the *cycle length*
+or *period*, after which the RNG will repeat itself.
+This sequence can
+be partitioned into disjoint *streams*. A stream of a
+RNG is a contiguous subset or block of the RNG sequence.
+For instance, if the
+RNG period is of length N, and two streams are provided from this
+RNG, then
+the first stream might use the first N/2 values and the second
+stream might produce the second N/2 values. An important property
+here is that the two streams are uncorrelated. Likewise, each
+stream can be partitioned disjointedly to a number of
+uncorrelated *substreams*. The underlying RNG hopefully
+produces a pseudo-random sequence of numbers with a very long
+cycle length, and partitions this into streams and substreams in an
+efficient manner.
+
+|ns3| uses the same underlying random number generator as does |ns2|: the
+MRG32k3a generator from Pierre L'Ecuyer. A detailed description can be found in
+http://www.iro.umontreal.ca/~lecuyer/myftp/papers/streams00.pdf. The MRG32k3a
+generator provides :math:`1.8x10^{19}` independent streams of random numbers,
+each of which consists of :math:`2.3x10^{15}` substreams. Each substream has a
+period (*i.e.*, the number of random numbers before overlap) of
+:math:`7.6x10^{22}`. The period of the entire generator is :math:`3.1x10^{57}`.
+
+
+Class :cpp:class:`ns3::RandomVariable` is the public interface to this
+underlying random number generator. When users create new ``RandomVariables``
+(such as :cpp:class:`ns3::UniformVariable`,
+:cpp:class:`ns3::ExponentialVariable`, etc.), they create an object that uses
+one of the distinct, independent streams of the random number generator.
+Therefore, each object of type :cpp:class:`ns3::RandomVariable` has,
+conceptually, its own "virtual" RNG. Furthermore, each
+:cpp:class:`ns3::RandomVariable` can be configured to use one of the set of
+substreams drawn from the main stream.
+
+An alternate implementation would be to allow each RandomVariable to have its
+own (differently seeded) RNG. However, we cannot guarantee as strongly that the
+different sequences would be uncorrelated in such a case; hence, we prefer to
+use a single RNG and streams and substreams from it.
+
+.. _seeding-and-independent-replications:
+
+Seeding and independent replications
+************************************
+
+|ns3| simulations can be configured to produce deterministic or random results.
+If the |ns3| simulation is configured to use a fixed, deterministic seed with
+the same run number, it should give the same output each time it is run.
+
+By default, |ns3| simulations use a fixed seed and run number. These values
+are stored in two :cpp:class:`ns3::GlobalValue` instances: ``g_rngSeed`` and
+``g_rngRun``.
+
+A typical use case is to run a simulation as a sequence of independent trials,
+so as to compute statistics on a large number of independent runs. The user can
+either change the global seed and rerun the simulation, or can advance the
+substream state of the RNG, which is referred to as incrementing the run number.
+
+A class :cpp:class:`ns3::SeedManager` provides an API to control the seeding and
+run number behavior. This seeding and substream state setting must be called
+before any random variables are created; e.g::
+
+ SeedManager::SetSeed (3); // Changes seed from default of 1 to 3
+ SeedManager::SetRun (7); // Changes run number from default of 1 to 7
+ // Now, create random variables
+ UniformVariable x(0,10);
+ ExponentialVariable y(2902);
+ ...
+
+Which is better, setting a new seed or advancing the substream state? There is
+no guarantee that the streams produced by two random seeds will not overlap.
+The only way to guarantee that two streams do not overlap is to use the
+substream capability provided by the RNG implementation. *Therefore, use the
+substream capability to produce multiple independent runs of the same
+simulation.* In other words, the more statistically rigorous way to configure
+multiple independent replications is to use a fixed seed and to advance the run
+number. This implementation allows for a maximum of :math:`2.3x10^{15}`
+independent replications using the substreams.
+
+For ease of use, it is not necessary to control the seed and run number from
+within the program; the user can set the ``NS_GLOBAL_VALUE`` environment
+variable as follows::
+
+ NS_GLOBAL_VALUE="RngRun=3" ./waf --run program-name
+
+Another way to control this is by passing a command-line argument; since this is
+an |ns3| GlobalValue instance, it is equivalently done such as follows::
+
+ ./waf --command-template="%s --RngRun=3" --run program-name
+
+or, if you are running programs directly outside of waf::
+
+ ./build/optimized/scratch/program-name --RngRun=3
+
+The above command-line variants make it easy to run lots of different
+runs from a shell script by just passing a different RngRun index.
+
+Class RandomVariable
+********************
+
+All random variables should derive from class :cpp:class:`RandomVariable`. This
+base class provides a few static methods for globally configuring the behavior
+of the random number generator. Derived classes provide API for drawing random
+variates from the particular distribution being supported.
+
+Each RandomVariable created in the simulation is given a generator that is a new
+RNGStream from the underlying PRNG. Used in this manner, the L'Ecuyer
+implementation allows for a maximum of :math:`1.8x10^19` random variables. Each
+random variable in a single replication can produce up to :math:`7.6x10^22`
+random numbers before overlapping.
+
+Base class public API
+*********************
+
+Below are excerpted a few public methods of class :cpp:class:`RandomVariable`
+that access the next value in the substream.::
+
+ /**
+ * \brief Returns a random double from the underlying distribution
+ * \return A floating point random value
+ */
+ double GetValue (void) const;
+
+ /**
+ * \brief Returns a random integer integer from the underlying distribution
+ * \return Integer cast of ::GetValue()
+ */
+ uint32_t GetInteger (void) const;
+
+We have already described the seeding configuration above. Different
+RandomVariable subclasses may have additional API.
+
+Types of RandomVariables
+************************
+
+The following types of random variables are provided, and are documented in the
+|ns3| Doxygen or by reading ``src/core/random-variable.h``. Users can also
+create their own custom random variables by deriving from class
+:cpp:class:`RandomVariable`.
+
+* class :cpp:class:`UniformVariable`
+* class :cpp:class:`ConstantVariable`
+* class :cpp:class:`SequentialVariable`
+* class :cpp:class:`ExponentialVariable`
+* class :cpp:class:`ParetoVariable`
+* class :cpp:class:`WeibullVariable`
+* class :cpp:class:`NormalVariable`
+* class :cpp:class:`EmpiricalVariable`
+* class :cpp:class:`IntEmpiricalVariable`
+* class :cpp:class:`DeterministicVariable`
+* class :cpp:class:`LogNormalVariable`
+* class :cpp:class:`TriangularVariable`
+* class :cpp:class:`GammaVariable`
+* class :cpp:class:`ErlangVariable`
+* class :cpp:class:`ZipfVariable`
+
+Semantics of RandomVariable objects
+***********************************
+
+RandomVariable objects have value semantics. This means that they can be passed
+by value to functions. The can also be passed by reference to const.
+RandomVariables do not derive from :cpp:class:`ns3::Object` and we do not use
+smart pointers to manage them; they are either allocated on the stack or else
+users explicitly manage any heap-allocated RandomVariables.
+
+RandomVariable objects can also be used in |ns3| attributes, which means
+that values can be set for them through the |ns3| attribute system.
+An example is in the propagation models for WifiNetDevice:::
+
+ TypeId
+ RandomPropagationDelayModel::GetTypeId (void)
+ {
+ static TypeId tid = TypeId ("ns3::RandomPropagationDelayModel")
+ .SetParent<PropagationDelayModel> ()
+ .AddConstructor<RandomPropagationDelayModel> ()
+ .AddAttribute ("Variable",
+ "The random variable which generates random delays (s).",
+ RandomVariableValue (UniformVariable (0.0, 1.0)),
+ MakeRandomVariableAccessor (&RandomPropagationDelayModel::m_variable),
+ MakeRandomVariableChecker ())
+ ;
+ return tid;
+ }
+
+Here, the |ns3| user can change the default random variable for this
+delay model (which is a UniformVariable ranging from 0 to 1) through
+the attribute system.
+
+Using other PRNG
+****************
+
+There is presently no support for substituting a different underlying
+random number generator (e.g., the GNU Scientific Library or the Akaroa
+package). Patches are welcome.
+
+More advanced usage
+*******************
+
+*To be completed.*
+
+Publishing your results
+***********************
+
+When you publish simulation results, a key piece of configuration
+information that you should always state is how you used the
+the random number generator.
+
+* what seeds you used,
+* what RNG you used if not the default,
+* how were independent runs performed,
+* for large simulations, how did you check that you did not cycle.
+
+It is incumbent on the researcher publishing results to include enough
+information to allow others to reproduce his or her results. It is also
+incumbent on the researcher to convince oneself that the random numbers used
+were statistically valid, and to state in the paper why such confidence is
+assumed.
+
+Summary
+*******
+
+Let's review what things you should do when creating a simulation.
+
+* Decide whether you are running with a fixed seed or random seed; a fixed seed
+ is the default,
+* Decide how you are going to manage independent replications, if applicable,
+* Convince yourself that you are not drawing more random values than the cycle
+ length, if you are running a very long simulation, and
+* When you publish, follow the guidelines above about documenting your use of
+ the random number generator.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/realtime.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,93 @@
+.. include:: replace.txt
+
+RealTime
+--------
+
+|ns3| has been designed for integration into testbed and virtual machine
+environments. To integrate with real network stacks and emit/consume packets, a
+real-time scheduler is needed to try to lock the simulation clock with the
+hardware clock. We describe here a component of this: the RealTime scheduler.
+
+The purpose of the realtime scheduler is to cause the progression of the
+simulation clock to occur synchronously with respect to some external time base.
+Without the presence of an external time base (wall clock), simulation time
+jumps instantly from one simulated time to the next.
+
+Behavior
+********
+
+When using a non-realtime scheduler (the default in |ns3|), the simulator
+advances the simulation time to the next scheduled event. During event
+execution, simulation time is frozen. With the realtime scheduler, the behavior
+is similar from the perspective of simulation models (i.e., simulation time is
+frozen during event execution), but between events, the simulator will attempt
+to keep the simulation clock aligned with the machine clock.
+
+When an event is finished executing, and the scheduler moves to the next event,
+the scheduler compares the next event execution time with the machine clock. If
+the next event is scheduled for a future time, the simulator sleeps until that
+realtime is reached and then executes the next event.
+
+It may happen that, due to the processing inherent in the execution of
+simulation events, that the simulator cannot keep up with realtime. In such a
+case, it is up to the user configuration what to do. There are two |ns3|
+attributes that govern the behavior. The first is
+``ns3::RealTimeSimulatorImpl::SynchronizationMode``. The two entries possible
+for this attribute are ``BestEffort`` (the default) or ``HardLimit``. In
+"BestEffort" mode, the simulator will just try to catch up to realtime by
+executing events until it reaches a point where the next event is in the
+(realtime) future, or else the simulation ends. In BestEffort mode, then, it is
+possible for the simulation to consume more time than the wall clock time. The
+other option "HardLimit" will cause the simulation to abort if the tolerance
+threshold is exceeded. This attribute is
+``ns3::RealTimeSimulatorImpl::HardLimit`` and the default is 0.1 seconds.
+
+A different mode of operation is one in which simulated time is **not** frozen
+during an event execution. This mode of realtime simulation was implemented but
+removed from the |ns3| tree because of questions of whether it would be useful.
+If users are interested in a realtime simulator for which simulation time does
+not freeze during event execution (i.e., every call to ``Simulator::Now()``
+returns the current wall clock time, not the time at which the event started
+executing), please contact the ns-developers mailing list.
+
+Usage
+*****
+
+The usage of the realtime simulator is straightforward, from a scripting
+perspective. Users just need to set the attribute
+``SimulatorImplementationType`` to the Realtime simulator, such as follows: ::
+
+ GlobalValue::Bind ("SimulatorImplementationType",
+ StringValue ("ns3::RealtimeSimulatorImpl"));
+
+There is a script in ``examples/realtime-udp-echo.cc`` that has an example of
+how to configure the realtime behavior. Try: ::
+
+ ./waf --run realtime-udp-echo
+
+Whether the simulator will work in a best effort or hard limit policy fashion is
+governed by the attributes explained in the previous section.
+
+Implementation
+**************
+
+The implementation is contained in the following files:
+
+* ``src/simulator/realtime-simulator-impl.@{cc,h@}``
+* ``src/simulator/wall-clock-synchronizer.@{cc,h@}``
+
+In order to create a realtime scheduler, to a first approximation you just want
+to cause simulation time jumps to consume real time. We propose doing this using
+a combination of sleep- and busy- waits. Sleep-waits cause the calling process
+(thread) to yield the processor for some amount of time. Even though this
+specified amount of time can be passed to nanosecond resolution, it is actually
+converted to an OS-specific granularity. In Linux, the granularity is called a
+Jiffy. Typically this resolution is insufficient for our needs (on the order of
+a ten milliseconds), so we round down and sleep for some smaller number of
+Jiffies. The process is then awakened after the specified number of Jiffies has
+passed. At this time, we have some residual time to wait. This time is generally
+smaller than the minimum sleep time, so we busy-wait for the remainder of the
+time. This means that the thread just sits in a for loop consuming cycles until
+the desired time arrives. After the combination of sleep- and busy-waits, the
+elapsed realtime (wall) clock should agree with the simulation time of the next
+event and the simulation proceeds.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/routing.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,383 @@
+.. include:: replace.txt
+
+Routing overview
+----------------
+
+|ns3| is intended to support traditional routing approaches and protocols,
+support ports of open source routing implementations, and facilitate research
+into unorthodox routing techniques. The overall routing architecture is
+described below in :ref:`Routing architecture`. Users who wish to just read
+about how to configure global routing for wired topologies can read :ref:`Global
+centralized routing`. Unicast routing protocols are described in :ref:`Unicast
+routing`. Multicast routing is documented in :ref:`Multicast routing`.
+
+Routing architecture
+********************
+
+.. _fig-routing:
+
+.. figure:: figures/routing.*
+
+ Overview of routing
+
+
+:ref:`fig-routing` shows the overall routing architecture for Ipv4. The key
+objects are Ipv4L3Protocol, Ipv4RoutingProtocol(s) (a class to which all
+routing/forwarding has been delegated from Ipv4L3Protocol), and Ipv4Route(s).
+
+Ipv4L3Protocol must have at least one Ipv4RoutingProtocol added to it at
+simulation setup time. This is done explicitly by calling
+Ipv4::SetRoutingProtocol ().
+
+The abstract base class Ipv4RoutingProtocol () declares a minimal interface,
+consisting of two methods: RouteOutput () and RouteInput (). For packets
+traveling outbound from a host, the transport protocol will query Ipv4 for the
+Ipv4RoutingProtocol object interface, and will request a route via
+Ipv4RoutingProtocol::RouteOutput (). A Ptr to Ipv4Route object is returned.
+This is analagous to a dst_cache entry in Linux. The Ipv4Route is carried down
+to the Ipv4L3Protocol to avoid a second lookup there. However, some cases (e.g.
+Ipv4 raw sockets) will require a call to RouteOutput()
+directly from Ipv4L3Protocol.
+
+For packets received inbound for forwarding or delivery,
+the following steps occur. Ipv4L3Protocol::Receive() calls
+Ipv4RoutingProtocol::RouteInput(). This passes the packet ownership to the
+Ipv4RoutingProtocol object. There are four callbacks associated with this call:
+
+* LocalDeliver
+* UnicastForward
+* MulticastForward
+* Error
+
+The Ipv4RoutingProtocol must eventually call one of these callbacks for each
+packet that it takes responsibility for. This is basically how the input routing
+process works in Linux.
+
+.. _routing-specialization:
+
+.. figure:: figures/routing-specialization.*
+
+ Ipv4Routing specialization.
+
+This overall architecture is designed to support different routing approaches,
+including (in the future) a Linux-like policy-based routing implementation,
+proactive and on-demand routing protocols, and simple routing protocols for when
+the simulation user does not really care about routing.
+
+:ref:`routing-specialization` illustrates how multiple routing protocols derive
+from this base class. A class Ipv4ListRouting (implementation class
+Ipv4ListRoutingImpl) provides the existing list routing approach in |ns3|. Its
+API is the same as base class Ipv4Routing except for the ability to add multiple
+prioritized routing protocols (Ipv4ListRouting::AddRoutingProtocol(),
+Ipv4ListRouting::GetRoutingProtocol()).
+
+The details of these routing protocols are described below in
+:ref:`Unicast routing`. For now, we will first start with a basic
+unicast routing capability that is intended to globally build routing
+tables at simulation time t=0 for simulation users who do not care
+about dynamic routing.
+
+Global centralized routing
+**************************
+
+Global centralized routing is sometimes called "God" routing; it is a special
+implementation that walks the simulation topology and runs a shortest path
+algorithm, and populates each node's routing tables. No actual protocol overhead
+(on the simulated links) is incurred with this approach. It does have a few
+constraints:
+
+* **Wired only:** It is not intended for use in wireless networks.
+* **Unicast only:** It does not do multicast.
+* **Scalability:** Some users of this on large topologies (e.g. 1000 nodes)
+ have noticed that the current implementation is not very scalable. The global
+ centralized routing will be modified in the future to reduce computations and
+ runtime performance.
+
+Presently, global centralized IPv4 unicast routing over both point-to-point and
+shared (CSMA) links is supported.
+
+By default, when using the |ns3| helper API and the default InternetStackHelper,
+global routing capability will be added to the node, and global routing will be
+inserted as a routing protocol with lower priority than the static routes (i.e.,
+users can insert routes via Ipv4StaticRouting API and they will take precedence
+over routes found by global routing).
+
+Global Unicast Routing API
+++++++++++++++++++++++++++
+
+The public API is very minimal. User scripts include the following:::
+
+ #include "ns3/helper-module.h"
+
+If the default InternetStackHelper is used, then an instance of global routing
+will be aggregated to each node. After IP addresses are configured, the
+following function call will cause all of the nodes that have an Ipv4 interface
+to receive forwarding tables entered automatically by the GlobalRouteManager:::
+
+ Ipv4GlobalRoutingHelper::PopulateRoutingTables ();
+
+*Note:* A reminder that the wifi NetDevice will work but does not take any
+wireless effects into account. For wireless, we recommend OLSR dynamic routing
+described below.
+
+It is possible to call this function again in the midst of a simulation using
+the following additional public function:::
+
+ Ipv4GlobalRoutingHelper::RecomputeRoutingTables ();
+
+which flushes the old tables, queries the nodes for new interface information,
+and rebuilds the routes.
+
+For instance, this scheduling call will cause the tables to be rebuilt
+at time 5 seconds:::
+
+ Simulator::Schedule (Seconds (5),
+ &Ipv4GlobalRoutingHelper::RecomputeRoutingTables);
+
+
+There are two attributes that govern the behavior. The first is
+Ipv4GlobalRouting::RandomEcmpRouting. If set to true, packets are randomly
+routed across equal-cost multipath routes. If set to false (default), only one
+route is consistently used. The second is
+Ipv4GlobalRouting::RespondToInterfaceEvents. If set to true, dynamically
+recompute the global routes upon Interface notification events (up/down, or
+add/remove address). If set to false (default), routing may break unless the
+user manually calls RecomputeRoutingTables() after such events. The default is
+set to false to preserve legacy |ns3| program behavior.
+
+Global Routing Implementation
++++++++++++++++++++++++++++++
+
+This section is for those readers who care about how this is implemented. A
+singleton object (GlobalRouteManager) is responsible for populating the static
+routes on each node, using the public Ipv4 API of that node. It queries each
+node in the topology for a "globalRouter" interface. If found, it uses the API
+of that interface to obtain a "link state advertisement (LSA)" for the router.
+Link State Advertisements are used in OSPF routing, and we follow their
+formatting.
+
+The GlobalRouteManager populates a link state database with LSAs gathered from
+the entire topology. Then, for each router in the topology, the
+GlobalRouteManager executes the OSPF shortest path first (SPF) computation on
+the database, and populates the routing tables on each node.
+
+The quagga (`<http://www.quagga.net>`_) OSPF implementation was used as the
+basis for the routing computation logic. One benefit of following an existing
+OSPF SPF implementation is that OSPF already has defined link state
+advertisements for all common types of network links:
+
+* point-to-point (serial links)
+* point-to-multipoint (Frame Relay, ad hoc wireless)
+* non-broadcast multiple access (ATM)
+* broadcast (Ethernet)
+
+Therefore, we think that enabling these other link types will be more
+straightforward now that the underlying OSPF SPF framework is in place.
+
+Presently, we can handle IPv4 point-to-point, numbered links, as well as shared
+broadcast (CSMA) links, and we do not do equal-cost multipath.
+
+The GlobalRouteManager first walks the list of nodes and aggregates
+a GlobalRouter interface to each one as follows:::
+
+ typedef std::vector < Ptr<Node> >::iterator Iterator;
+ for (Iterator i = NodeList::Begin (); i != NodeList::End (); i++)
+ {
+ Ptr<Node> node = *i;
+ Ptr<GlobalRouter> globalRouter = CreateObject<GlobalRouter> (node);
+ node->AggregateObject (globalRouter);
+ }
+
+This interface is later queried and used to generate a Link State
+Advertisement for each router, and this link state database is
+fed into the OSPF shortest path computation logic. The Ipv4 API
+is finally used to populate the routes themselves.
+
+Unicast routing
+***************
+
+There are presently five unicast routing protocols defined for IPv4 and two for
+IPv6:
+
+* class Ipv4StaticRouting (covering both unicast and multicast)
+* IPv4 Optimized Link State Routing (a MANET protocol defined in `RFC 3626
+ <http://www.ietf.org/rfc/rfc3626.txt>`_)
+* class Ipv4ListRouting (used to store a prioritized list of routing protocols)
+* class Ipv4GlobalRouting (used to store routes computed by the global route
+ manager, if that is used)
+* class Ipv4NixVectorRouting (a more efficient version of global routing that
+ stores source routes in a packet header field)
+* class Ipv6ListRouting (used to store a prioritized list of routing protocols)
+* class Ipv6StaticRouting
+
+In the future, this architecture should also allow someone to implement a
+Linux-like implementation with routing cache, or a Click modular router, but
+those are out of scope for now.
+
+Ipv4ListRouting
++++++++++++++++
+
+This section describes the current default |ns3| Ipv4RoutingProtocol. Typically,
+multiple routing protocols are supported in user space and coordinate to write a
+single forwarding table in the kernel. Presently in |ns3|, the implementation
+instead allows for multiple routing protocols to build/keep their own routing
+state, and the IPv4 implementation will query each one of these routing
+protocols (in some order determined by the simulation author) until a route is
+found.
+
+We chose this approach because it may better facilitate the integration of
+disparate routing approaches that may be difficult to coordinate the writing to
+a single table, approaches where more information than destination IP address
+(e.g., source routing) is used to determine the next hop, and on-demand routing
+approaches where packets must be cached.
+
+Ipv4ListRouting::AddRoutingProtocol
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Class Ipv4ListRouting provides a pure virtual function declaration for the
+method that allows one to add a routing protocol:::
+
+ void AddRoutingProtocol (Ptr<Ipv4RoutingProtocol> routingProtocol,
+ int16_t priority);
+
+This method is implemented by class Ipv4ListRoutingImpl in the internet-stack
+module.
+
+The priority variable above governs the priority in which the routing protocols
+are inserted. Notice that it is a signed int. By default in |ns3|, the helper
+classes will instantiate a Ipv4ListRoutingImpl object, and add to it an
+Ipv4StaticRoutingImpl object at priority zero. Internally, a list of
+Ipv4RoutingProtocols is stored, and and the routing protocols are each consulted
+in decreasing order of priority to see whether a match is found. Therefore, if
+you want your Ipv4RoutingProtocol to have priority lower than the static
+routing, insert it with priority less than 0; e.g.:::
+
+ Ptr<MyRoutingProtocol> myRoutingProto = CreateObject<MyRoutingProtocol> ();
+ listRoutingPtr->AddRoutingProtocol (myRoutingProto, -10);
+
+Upon calls to RouteOutput() or RouteInput(), the list routing object will search
+the list of routing protocols, in priority order, until a route is found. Such
+routing protocol will invoke the appropriate callback and no further routing
+protocols will be searched.
+
+Optimized Link State Routing (OLSR)
++++++++++++++++++++++++++++++++++++
+
+This IPv4 routing protocol was originally ported from the OLSR-UM implementation
+for ns-2. The implementation is found in the src/routing/olsr directory, and an
+example script is in examples/simple-point-to-point-olsr.cc.
+
+Typically, OLSR is enabled in a main program by use of an OlsrHelper class that
+installs OLSR into an Ipv4ListRoutingProtocol object. The following sample
+commands will enable OLSR in a simulation using this helper class along with
+some other routing helper objects. The setting of priority value 10, ahead of
+the staticRouting priority of 0, means that OLSR will be consulted for a route
+before the node's static routing table.::
+
+ NodeContainer c:
+ ...
+ // Enable OLSR
+ NS_LOG_INFO ("Enabling OLSR Routing.");
+ OlsrHelper olsr;
+
+ Ipv4StaticRoutingHelper staticRouting;
+
+ Ipv4ListRoutingHelper list;
+ list.Add (staticRouting, 0);
+ list.Add (olsr, 10);
+
+ InternetStackHelper internet;
+ internet.SetRoutingHelper (list);
+ internet.Install (c);
+
+Once installed,the OLSR "main interface" can be set with the SetMainInterface()
+command. If the user does not specify a main address, the protocol will select
+the first primary IP address that it finds, starting first the loopback
+interface and then the next non-loopback interface found, in order of Ipv4
+interface index. The loopback address of 127.0.0.1 is not selected. In addition,
+a number of protocol constants are defined in olsr-routing-protocol.cc.
+
+Olsr is started at time zero of the simulation, based on a call to
+Object::Start() that eventually calls OlsrRoutingProtocol::DoStart(). Note: a
+patch to allow the user to start and stop the protocol at other times would be
+welcome.
+
+Presently, OLSR is limited to use with an Ipv4ListRouting object, and does not
+respond to dynamic changes to a device's IP address or link up/down
+notifications; i.e. the topology changes are due to loss/gain of connectivity
+over a wireless channel.
+
+Multicast routing
+*****************
+
+The following function is used to add a static multicast route
+to a node:::
+
+ void
+ Ipv4StaticRouting::AddMulticastRoute (Ipv4Address origin,
+ Ipv4Address group,
+ uint32_t inputInterface,
+ std::vector<uint32_t> outputInterfaces);
+
+A multicast route must specify an origin IP address, a multicast group and an
+input network interface index as conditions and provide a vector of output
+network interface indices over which packets matching the conditions are sent.
+
+Typically there are two main types of multicast routes: routes of the first
+kind are used during forwarding. All of the conditions must be explicitly
+provided. The second kind of routes are used to get packets off of a local node.
+The difference is in the input interface. Routes for forwarding will always
+have an explicit input interface specified. Routes off of a node will always
+set the input interface to a wildcard specified by the index
+Ipv4RoutingProtocol::IF\_INDEX\_ANY.
+
+For routes off of a local node wildcards may be used in the origin and multicast
+group addresses. The wildcard used for Ipv4Adresses is that address returned by
+Ipv4Address::GetAny () -- typically "0.0.0.0". Usage of a wildcard allows one to
+specify default behavior to varying degrees.
+
+For example, making the origin address a wildcard, but leaving the multicast
+group specific allows one (in the case of a node with multiple interfaces) to
+create different routes using different output interfaces for each multicast
+group.
+
+If the origin and multicast addresses are made wildcards, you have created
+essentially a default multicast address that can forward to multiple
+interfaces. Compare this to the actual default multicast address that is
+limited to specifying a single output interface for compatibility with
+existing functionality in other systems.
+
+Another command sets the default multicast route:::
+
+ void
+ Ipv4StaticRouting::SetDefaultMulticastRoute (uint32_t outputInterface);
+
+This is the multicast equivalent of the unicast version SetDefaultRoute. We
+tell the routing system what to do in the case where a specific route to a
+destination multicast group is not found. The system forwards packets out the
+specified interface in the hope that "something out there" knows better how to
+route the packet. This method is only used in initially sending packets off of a
+host. The default multicast route is not consulted during forwarding -- exact
+routes must be specified using AddMulticastRoute for that case.
+
+Since we're basically sending packets to some entity we think may know better
+what to do, we don't pay attention to "subtleties" like origin address, nor do
+we worry about forwarding out multiple interfaces. If the default multicast
+route is set, it is returned as the selected route from LookupStatic
+irrespective of origin or multicast group if another specific route is not
+found.
+
+Finally, a number of additional functions are provided to fetch and remove
+multicast routes:::
+
+ uint32_t GetNMulticastRoutes (void) const;
+
+ Ipv4MulticastRoute *GetMulticastRoute (uint32_t i) const;
+
+ Ipv4MulticastRoute *GetDefaultMulticastRoute (void) const;
+
+ bool RemoveMulticastRoute (Ipv4Address origin,
+ Ipv4Address group,
+ uint32_t inputInterface);
+
+ void RemoveMulticastRoute (uint32_t index);
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/simple.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,6 @@
+.. include:: replace.txt
+
+Simple NetDevice
+----------------
+
+*Placeholder chapter*
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/sockets-api.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,205 @@
+.. include:: replace.txt
+
+Sockets APIs
+------------
+
+The `sockets API <http://en.wikipedia.org/wiki/Berkeley_sockets>`_
+is a long-standing API used by user-space applications to access
+network services in the kernel. A *socket* is an abstraction, like
+a Unix file handle, that allows applications to connect to other
+Internet hosts and exchange reliable byte streams and unreliable
+datagrams, among other services.
+
+|ns3| provides two types of sockets APIs, and it is important to
+understand the differences between them. The first is a *native*
+|ns3| API, while the second uses the services of the native API to
+provide a `POSIX-like <http://en.wikipedia.org/wiki/POSIX>`_
+API as part of an overall application process. Both APIs strive
+to be close to the typical sockets API that application writers
+on Unix systems are accustomed to, but the POSIX variant is much
+closer to a real system's sockets API.
+
+ns-3 sockets API
+*****************
+
+The native sockets API for ns-3 provides an interface to various
+types of transport protocols (TCP, UDP) as well as to packet sockets
+and, in the future, Netlink-like sockets. However, users are cautioned
+to understand that the semantics are *not* the exact same as
+one finds in a real system (for an API which is very much aligned
+to real systems, see the next section).
+
+:cpp:class:`ns3::Socket` is defined in ``src/node/socket.h``.
+Readers will note that many public member functions are aligned
+with real sockets function calls, and all other things being equal,
+we have tried to align with a Posix sockets API. However, note that:
+
+* ns-3 applications handle a smart pointer to a Socket object, not
+ a file descriptor;
+
+* there is no notion of synchronous API or a *blocking* API;
+ in fact, the model for interaction between application and socket is
+ one of asynchronous I/O, which is not typically found in real systems
+ (more on this below);
+
+* the C-style socket address structures are not used;
+
+* the API is not a complete sockets API, such as supporting
+ all socket options or all function variants;
+
+* many calls use :cpp:class:`ns3::Packet` class to transfer data
+ between application and socket. This may seem peculiar to
+ pass *Packets* across a stream socket API, but think
+ of these packets as just fancy byte buffers at this level (more
+ on this also below).
+
+Basic operation and calls
+=========================
+
+.. _sockets-overview:
+
+.. figure:: figures/sockets-overview.*
+
+ Implementation overview of native sockets API
+
+Creating sockets
+================
+
+An application that wants to use sockets must first create one.
+On real systems using a C-based API, this is accomplished by calling :c:func:`socket()` ::
+
+ int socket(int domain, int type, int protocol);
+
+which creates a socket in the system and returns an integer descriptor.
+
+In ns-3, we have no equivalent of a system call at the lower layers,
+so we adopt the following model. There are certain *factory*
+objects that can create sockets. Each factory is capable of creating
+one type of socket, and if sockets of a particular type are able to
+be created on a given node, then a factory that can create such sockets
+must be aggregated to the Node::
+
+ static Ptr<Socket> CreateSocket (Ptr<Node> node, TypeId tid);
+
+Examples of TypeIds to pass to this method are :cpp:class:`ns3::TcpSocketFactory`,
+:cpp:class:`ns3::PacketSocketFactory`, and :cpp:class:`ns3::UdpSocketFactory`.
+
+This method returns a smart pointer to a Socket object. Here is an
+example::
+
+ Ptr<Node> n0;
+ // Do some stuff to build up the Node's internet stack
+ Ptr<Socket> localSocket =
+ Socket::CreateSocket (n0, TcpSocketFactory::GetTypeId ());
+
+In some ns-3 code, sockets will not be explicitly created by user's
+main programs, if an ns-3 application does it. For instance, for
+:cpp:class:`ns3::OnOffApplication`, the function :cpp:func:`ns3::OnOffApplication::StartApplication`
+performs the socket creation, and the application holds the socket
+pointer.
+
+Using sockets
+=============
+
+Below is a typical sequence of socket calls for a TCP client in a
+real implementation:
+
+* ``sock = socket(PF_INET, SOCK_STREAM, IPPROTO_TCP);``
+* ``bind(sock, ...);``
+* ``connect(sock, ...);``
+* ``send(sock, ...);``
+* ``recv(sock, ...);``
+* ``close(sock);``
+
+There are analogs to all of these calls in ns-3, but we will focus on
+two aspects here. First, most usage of sockets in real systems
+requires a way to manage I/O between the application and kernel.
+These models include *blocking sockets*, *signal-based I/O*,
+and *non-blocking sockets* with polling. In ns-3, we make use
+of the callback mechanisms to support a fourth mode, which is
+analogous to POSIX *asynchronous I/O*.
+
+In this model, on the sending side, if the :c:func:`send()` call were to
+fail because of insufficient buffers, the application suspends the
+sending of more data until a function registered at the
+:cpp:func:`ns3::Socket::SetSendCallback` callback is invoked.
+An application can also ask the socket how much space is available
+by calling :cpp:func:`ns3::Socket::GetTxAvailable`. A typical sequence
+of events for sending data (ignoring connection setup) might be:
+
+* ``SetSendCallback (MakeCallback(&HandleSendCallback));``
+* ``Send ();``
+* ``Send ();``
+* ...
+* Send fails because buffer is full
+* wait until :cpp:func:`HandleSendCallback` is called
+* :cpp:func:`HandleSendCallback` is called by socket, since space now available
+* ``Send (); // Start sending again``
+
+Similarly, on the receive side, the socket user does not block on
+a call to ``recv()``. Instead, the application sets a callback
+with :cpp:func:`ns3::Socket::SetRecvCallback` in which the socket will notify the
+application when (and how much) there is data to be read, and
+the application then calls :cpp:func:`ns3::Socket::Recv` to read the data until
+no more can be read.
+
+
+Packet vs. buffer variants
+**************************
+
+There are two basic variants of ``Send()`` and ``Recv()`` supported::
+
+ virtual int Send (Ptr<Packet> p) = 0;
+ int Send (const uint8_t* buf, uint32_t size);
+
+ Ptr<Packet> Recv (void);
+ int Recv (uint8_t* buf, uint32_t size);
+
+The non-Packet variants are provided for legacy API reasons. When calling
+the raw buffer variant of :cpp:func:`ns3::Socket::Send`, the buffer is immediately
+written into a Packet and the :cpp:func:`ns3::Socket::Send (Ptr<Packet> p)` is invoked.
+
+Users may find it semantically odd to pass a Packet to a stream socket
+such as TCP. However, do not let the name bother you; think of
+:cpp:class:`ns3::Packet` to be a fancy byte buffer. There are a few reasons why
+the Packet variants are more likely to be preferred in ns-3:
+
+* Users can use the Tags facility of packets to, for example, encode
+ a flow ID or other helper data at the application layer.
+
+* Users can exploit the copy-on-write implementation to avoid
+ memory copies (on the receive side, the conversion back to a
+ ``uint8_t* buf`` may sometimes incur an additional copy).
+
+* Use of Packet is more aligned with the rest of the ns-3 API
+
+Sending dummy data
+******************
+
+Sometimes, users want the simulator to just pretend that there is an
+actual data payload in the packet (e.g. to calculate transmission delay)
+but do not want to actually produce or consume the data. This is
+straightforward to support in ns-3; have applications call
+``Create<Packet> (size);`` instead of ``Create<Packet> (buffer, size);``.
+Similarly, passing in a zero to the pointer argument in the raw buffer
+variants has the same effect. Note that, if some subsequent code tries
+to read the Packet data buffer, the fake buffer will be converted to
+a real (zeroed) buffer on the spot, and the efficiency will be lost there.
+
+Socket options
+**************
+
+*to be completed*
+
+Socket errno
+************
+
+*to be completed*
+
+Example programs
+****************
+
+*to be completed*
+
+POSIX-like sockets API
+**********************
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/statistics.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,11 @@
+.. include:: replace.txt
+
+Statistics
+----------
+
+*Placeholder chapter*
+
+This wiki page: `This wiki page
+<http://www.nsnam.org/wiki/index.php/Statistical_Framework_for_Network_Simulation>`_
+contains information about the proposed statistical framework that is located in
+``src/contrib`` directory.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/support.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,10 @@
+Support
+-------
+
+.. toctree::
+
+ flow-monitor
+ animation
+ statistics
+ new-models
+ troubleshoot
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/tap.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,10 @@
+.. include:: replace.txt
+
+Tap NetDevice
+-------------
+
+*Placeholder chapter*
+
+The Tap NetDevice can be used to allow a host system or virtual machines to
+interact with a simulation. See ``examples/tap/tap-wifi-dumbbell.cc`` for an
+example.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/tcp.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,312 @@
+.. include:: replace.txt
+
+TCP models in ns-3
+------------------
+
+This chapter describes the TCP models available in |ns3|.
+
+Generic support for TCP
+***********************
+
+|ns3| was written to support multiple TCP implementations. The implementations
+inherit from a few common header classes in the ``src/node`` directory, so that
+user code can swap out implementations with minimal changes to the scripts.
+
+There are two important abstract base classes:
+
+* class :cpp:class:`TcpSocket`: This is defined in
+ ``src/node/tcp-socket.@{cc,h@}``. This class exists for hosting TcpSocket
+ attributes that can be reused across different implementations. For instance,
+ ``TcpSocket::SetInitialCwnd()`` can be used for any of the implementations
+ that derive from class :cpp:class:`TcpSocket`.
+* class :cpp:class:`TcpSocketFactory`: This is used by applications to create
+ TCP sockets. A typical usage can be seen in this snippet:::
+
+ // Create the socket if not already created
+ if (!m_socket)
+ {
+ m_socket = Socket::CreateSocket (GetNode(), m_tid);
+ m_socket->Bind (m_local);
+ ...
+ }
+
+The parameter ``m_tid`` controls the TypeId of the actual TCP Socket
+implementation that is instantiated. This way, the application can be written
+generically and different socket implementations can be swapped out by
+specifying the TypeId.
+
+ns-3 TCP
+********
+
+|ns3| contains a port of the TCP model from `GTNetS
+<http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/index.html>`_. This
+model is a full TCP, in that it is bidirectional and attempts to model the
+connection setup and close logic. In fact, it is a more complete implementation
+of the TCP state machine than ns-2's "FullTcp" model. This TCP model was
+originally written by George Riley as part of GTNetS and ported to |ns3| by Raj
+Bhattacharjea.
+
+The implementation of TCP is contained in the following files:::
+
+ src/internet-stack/tcp-header.{cc,h}
+ src/internet-stack/tcp-l4-protocol.{cc,h}
+ src/internet-stack/tcp-socket-factory-impl.{cc,h}
+ src/internet-stack/tcp-socket-impl.{cc,h}
+ src/internet-stack/tcp-typedefs.h
+ src/internet-stack/rtt-estimator.{cc,h}
+ src/internet-stack/sequence-number.{cc,h}
+
+Usage
++++++
+
+The file ``examples/tcp-star-server.cc`` contains an example that
+makes use of ``ns3::OnOffApplication`` and ``ns3::PacketSink``
+applications.
+
+Using the helper functions defined in ``src/helper``, here is how
+one would create a TCP receiver:::
+
+ // Create a packet sink on the star "hub" to receive these packets
+ uint16_t port = 50000;
+ Address sinkLocalAddress(InetSocketAddress (Ipv4Address::GetAny (), port));
+ PacketSinkHelper sinkHelper ("ns3::TcpSocketFactory", sinkLocalAddress);
+ ApplicationContainer sinkApp = sinkHelper.Install (serverNode);
+ sinkApp.Start (Seconds (1.0));
+ sinkApp.Stop (Seconds (10.0));
+
+
+Similarly, the below snippet configures OnOffApplication traffic source to use
+TCP:::
+
+ // Create the OnOff applications to send TCP to the server
+ OnOffHelper clientHelper ("ns3::TcpSocketFactory", Address ());
+
+
+The careful reader will note above that we have specified the TypeId of an
+abstract base class :cpp:class:`TcpSocketFactory`. How does the script tell
+|ns3| that it wants the native |ns3| TCP vs. some other one? Well, when
+internet stacks are added to the node, the default TCP implementation that is
+aggregated to the node is the |ns3| TCP. This can be overridden as we show
+below when using Network Simulation Cradle. So, by default, when using the |ns3|
+helper API, the TCP that is aggregated to nodes with an Internet stack is the
+native |ns3| TCP.
+
+Once a TCP socket is created, you will want to follow conventional socket logic
+and either connect() and send() (for a TCP client) or bind(), listen(), and
+accept() (for a TCP server). :ref:`Sockets API <Sockets APIs>` for a review of
+how sockets are used in |ns3|.
+
+To configure behavior of TCP, a number of parameters are exported through the
+:ref:`Attributes <ns-3 attribute system>`. These are documented in the `Doxygen
+<http://www.nsnam.org/doxygen/classns3_1_1_tcp_socket.html>` for class
+:cpp:class:`TcpSocket`.
+
+Current limitations
++++++++++++++++++++
+
+* Only Tahoe congestion control is presently supported.
+* Only IPv4 is supported (IPv6 support will start to be added after ns-3.6).
+
+Network Simulation Cradle
+*************************
+
+The `Network Simulation Cradle (NSC) <http://www.wand.net.nz/~stj2/nsc/>`_ is a
+framework for wrapping real-world network code into simulators, allowing
+simulation of real-world behavior at little extra cost. This work has been
+validated by comparing situations using a test network with the same situations
+in the simulator. To date, it has been shown that the NSC is able to produce
+extremely accurate results. NSC supports four real world stacks: FreeBSD,
+OpenBSD, lwIP and Linux. Emphasis has been placed on not changing any of the
+network stacks by hand. Not a single line of code has been changed in the
+network protocol implementations of any of the above four stacks. However, a
+custom C parser was built to programmatically change source code.
+
+NSC has previously been ported to |ns2| and OMNeT++, and recently
+was added to |ns3|. This section describes the |ns3| port of NSC and
+how to use it.
+
+Prerequisites
++++++++++++++
+
+Presently, NSC has been tested and shown to work on these platforms:
+Linux i386 and Linux x86-64. NSC does not support powerpc.
+
+Building NSC requires the packages flex and bison.
+
+Configuring and Downloading
++++++++++++++++++++++++++++
+
+Using the ``build.py`` script in ns-3-allinone directory, NSC will be enabled by
+default unless the platform does not support it. To disable it when building
+|ns3|, type:::
+
+./waf configure --disable-nsc
+
+Building and validating
++++++++++++++++++++++++
+
+Building |ns3| with nsc support is the same as building it without; no
+additional arguments are needed for waf. Building nsc may take some time
+compared to |ns3|; it is interleaved in the |ns3| building process.
+
+Try running the regression tests: ``./waf --regression``. If NSC has
+been successfully built, the following test should show up in the results:::
+
+ PASS test-tcp-nsc-lfn
+
+This confirms that NSC is ready to use.
+
+Usage
++++++
+
+There are a few example files. Try::
+
+ ./waf --run tcp-nsc-zoo
+ ./waf --run tcp-nsc-lfn
+
+These examples will deposit some ``.pcap`` files in your directory,
+which can be examined by tcpdump or wireshark.
+
+Let's look at the ``examples/tcp-nsc-zoo.cc`` file for some typical
+usage. How does it differ from using native |ns3| TCP? There is one main
+configuration line, when using NSC and the |ns3| helper API, that needs to be
+set:::
+
+ InternetStackHelper internetStack;
+
+ internetStack.SetNscStack ("liblinux2.6.26.so");
+ // this switches nodes 0 and 1 to NSCs Linux 2.6.26 stack.
+ internetStack.Install (n.Get(0));
+ internetStack.Install (n.Get(1));
+
+
+The key line is the ``SetNscStack``. This tells the InternetStack
+helper to aggregate instances of NSC TCP instead of native |ns3| TCP
+to the remaining nodes. It is important that this function be called
+**before** calling the ``Install()`` function, as shown above.
+
+Which stacks are available to use? Presently, the focus has been on
+Linux 2.6.18 and Linux 2.6.26 stacks for |ns3|. To see which stacks
+were built, one can execute the following find command at the |ns3| top level
+directory:::
+
+ ~/ns-3.2> find nsc -name "*.so" -type f
+ nsc/linux-2.6.18/liblinux2.6.18.so
+ nsc/linux-2.6.26/liblinux2.6.26.so
+
+This tells us that we may either pass the library name liblinux2.6.18.so or
+liblinux2.6.26.so to the above configuration step.
+
+Stack configuration
++++++++++++++++++++
+
+NSC TCP shares the same configuration attributes that are common across TCP
+sockets, as described above and documented in `Doxygen
+<http://www.nsnam.org/doxygen/classns3_1_1_tcp_socket.html>`_
+
+Additionally, NSC TCP exports a lot of configuration variables into the
+|ns3| :ref:`Attributes` system, via a `sysctl <http://en.wikipedia.org/wiki/Sysctl>`_-like interface. In the ``examples/tcp-nsc-zoo`` example, you
+can see the following configuration:::
+
+
+ // this disables TCP SACK, wscale and timestamps on node 1 (the attributes
+ represent sysctl-values).
+ Config::Set ("/NodeList/1/$ns3::Ns3NscStack<linux2.6.26>/net.ipv4.tcp_sack",
+ StringValue ("0"));
+ Config::Set ("/NodeList/1/$ns3::Ns3NscStack<linux2.6.26>/net.ipv4.tcp_timestamps",
+ StringValue ("0"));
+ Config::Set ("/NodeList/1/$ns3::Ns3NscStack<linux2.6.26>/net.ipv4.tcp_window_scaling",
+ StringValue ("0"));
+
+These additional configuration variables are not available to native |ns3| TCP.
+
+NSC API
++++++++
+
+This subsection describes the API that NSC presents to |ns3| or any other
+simulator. NSC provides its API in the form of a number of classes that are
+defined in ``sim/sim_interface.h`` in the nsc directory.
+
+* **INetStack** INetStack contains the 'low level' operations for the operating
+ system network stack, e.g. in and output functions from and to the network
+ stack (think of this as the 'network driver interface'. There are also
+ functions to create new TCP or UDP sockets.
+* **ISendCallback** This is called by NSC when a packet should be sent out to
+ the network. This simulator should use this callback to re-inject the packet
+ into the simulator so the actual data can be delivered/routed to its
+ destination, where it will eventually be handed into Receive() (and eventually
+ back to the receivers NSC instance via INetStack->if_receive() ).
+* **INetStreamSocket** This is the structure defining a particular connection
+ endpoint (file descriptor). It contains methods to operate on this endpoint,
+ e.g. connect, disconnect, accept, listen, send_data/read_data, ...
+* **IInterruptCallback** This contains the wakeup callback, which is called by
+ NSC whenever something of interest happens. Think of wakeup() as a replacement
+ of the operating systems wakeup function: Whenever the operating system would
+ wake up a process that has been waiting for an operation to complete (for
+ example the TCP handshake during connect()), NSC invokes the wakeup() callback
+ to allow the simulator to check for state changes in its connection endpoints.
+
+ns-3 implementation
++++++++++++++++++++
+
+The |ns3| implementation makes use of the above NSC API, and is implemented as
+follows.
+
+The three main parts are:
+
+* :cpp:class:`ns3::NscTcpL4Protocol`: a subclass of Ipv4L4Protocol (and two nsc
+ classes: ISendCallback and IInterruptCallback)
+* :cpp:class:`ns3::NscTcpSocketImpl`: a subclass of TcpSocket
+* :cpp:class:`ns3::NscTcpSocketFactoryImpl`: a factory to create new NSC
+ sockets
+
+``src/internet-stack/nsc-tcp-l4-protocol`` is the main class. Upon
+Initialization, it loads an nsc network stack to use (via dlopen()). Each
+instance of this class may use a different stack. The stack (=shared library) to
+use is set using the SetNscLibrary() method (at this time its called indirectly
+via the internet stack helper). The nsc stack is then set up accordingly (timers
+etc). The NscTcpL4Protocol::Receive() function hands the packet it receives
+(must be a complete tcp/ip packet) to the nsc stack for further processing. To
+be able to send packets, this class implements the nsc send_callback method.
+This method is called by nsc whenever the nsc stack wishes to send a packet out
+to the network. Its arguments are a raw buffer, containing a complete TCP/IP
+packet, and a length value. This method therefore has to convert the raw data to
+a Ptr<Packet> usable by |ns3|. In order to avoid various ipv4 header issues,
+the nsc ip header is not included. Instead, the tcp header and the actual
+payload are put into the Ptr<Packet>, after this the Packet is passed down to
+layer 3 for sending the packet out (no further special treatment is needed in
+the send code path).
+
+This class calls ``ns3::NscTcpSocketImpl`` both from the nsc wakeup() callback
+and from the Receive path (to ensure that possibly queued data is scheduled for
+sending).
+
+
+``src/internet-stack/nsc-tcp-socket-impl`` implements the nsc socket interface.
+Each instance has its own nscTcpSocket. Data that is Send() will be handed to
+the nsc stack via m_nscTcpSocket->send_data(). (and not to nsc-tcp-l4, this is
+the major difference compared to |ns3| TCP). The class also queues up data that
+is Send() before the underlying descriptor has entered an ESTABLISHED state.
+This class is called from the nsc-tcp-l4 class, when the nsc-tcp-l4 wakeup()
+callback is invoked by nsc. nsc-tcp-socket-impl then checks the current
+connection state (SYN_SENT, ESTABLISHED, LISTEN...) and schedules appropriate
+callbacks as needed, e.g. a LISTEN socket will schedule Accept to see if a new
+connection must be accepted, an ESTABLISHED socket schedules any pending data
+for writing, schedule a read callback, etc.
+
+Note that ``ns3::NscTcpSocketImpl`` does not interact with nsc-tcp directly:
+instead, data is redirected to nsc. nsc-tcp calls the nsc-tcp-sockets of a node
+when its wakeup callback is invoked by nsc.
+
+Limitations
++++++++++++
+
+
+* NSC only works on single-interface nodes; attempting to run it on a
+ multi-interface node will cause a program error. This limitation should be
+ fixed by ns-3.7.
+* Cygwin and OS X PPC are not supported
+* The non-Linux stacks of NSC are not supported in |ns3|
+* Not all socket API callbacks are supported
+
+For more information, see `this wiki page <http://www.nsnam.org/wiki/index.php/Network_Simulation_Cradle_Integration>`_.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/tracing.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,1076 @@
+.. include:: replace.txt
+
+Tracing
+-------
+
+The tracing subsystem is one of the most important mechanisms to understand in
+|ns3|. In most cases, |ns3| users will have a brilliant idea for some new and
+improved networking feature. In order to verify that this idea works, the
+researcher will make changes to an existing system and then run experiments to
+see how the new feature behaves by gathering statistics that capture the
+behavior of the feature.
+
+In other words, the whole point of running a simulation is to generate output
+for further study. In |ns3|, the subsystem that enables a researcher to do this
+is the tracing subsystem.
+
+Tracing Motivation
+******************
+
+There are many ways to get information out of a program. The most
+straightforward way is to just directly print the information to the standard
+output, as in, ::
+
+ #include <iostream>
+ ...
+ int main ()
+ {
+ ...
+ std::cout << ``The value of x is `` << x << std::endl;
+ ...
+ }
+
+This is workable in small environments, but as your simulations get more and
+more complicated, you end up with more and more prints and the task of parsing
+and performing computations on the output begins to get harder and harder.
+
+Another thing to consider is that every time a new tidbit is needed, the
+software core must be edited and another print introduced. There is no
+standardized way to control all of this output, so the amount of output tends to
+grow without bounds. Eventually, the bandwidth required for simply outputting
+this information begins to limit the running time of the simulation. The output
+files grow to enormous sizes and parsing them becomes a problem.
+
+|ns3| provides a simple mechanism for logging and providing some control over
+output via *Log Components*, but the level of control is not very fine grained
+at all. The logging module is a relatively blunt instrument.
+
+It is desirable to have a facility that allows one to reach into the core system
+and only get the information required without having to change and recompile the
+core system. Even better would be a system that notified the user when an item
+of interest changed or an interesting event happened.
+
+The |ns3| tracing system is designed to work along those lines and is
+well-integrated with the Attribute and Config substems allowing for relatively
+simple use scenarios.
+
+Overview
+********
+
+The tracing subsystem relies heavily on the |ns3| Callback and Attribute
+mechanisms. You should read and understand the corresponding sections of the
+manual before attempting to understand the tracing system.
+
+The |ns3| tracing system is built on the concepts of independent tracing sources
+and tracing sinks; along with a uniform mechanism for connecting sources to
+sinks.
+
+Trace sources are entities that can signal events that happen in a simulation
+and provide access to interesting underlying data. For example, a trace source
+could indicate when a packet is received by a net device and provide access to
+the packet contents for interested trace sinks. A trace source might also
+indicate when an interesting state change happens in a model. For example, the
+congestion window of a TCP model is a prime candidate for a trace source.
+
+Trace sources are not useful by themselves; they must be connected to other
+pieces of code that actually do something useful with the information provided
+by the source. The entities that consume trace information are called trace
+sinks. Trace sources are generators of events and trace sinks are consumers.
+
+This explicit division allows for large numbers of trace sources to be scattered
+around the system in places which model authors believe might be useful. Unless
+a user connects a trace sink to one of these sources, nothing is output. This
+arrangement allows relatively unsophisticated users to attach new types of sinks
+to existing tracing sources, without requiring editing and recompiling the core
+or models of the simulator.
+
+There can be zero or more consumers of trace events generated by a trace source.
+One can think of a trace source as a kind of point-to-multipoint information
+link.
+
+The "transport protocol" for this conceptual point-to-multipoint link is an
+|ns3| ``Callback``.
+
+Recall from the Callback Section that callback facility is a way to allow two
+modules in the system to communicate via function calls while at the same time
+decoupling the calling function from the called class completely. This is the
+same requirement as outlined above for the tracing system.
+
+Basically, a trace source *is* a callback to which multiple functions may be
+registered. When a trace sink expresses interest in receiving trace events, it
+adds a callback to a list of callbacks held by the trace source. When an
+interesting event happens, the trace source invokes its ``operator()`` providing
+zero or more parameters. This tells the source to go through its list of
+callbacks invoking each one in turn. In this way, the parameter(s) are
+communicated to the trace sinks, which are just functions.
+
+The Simplest Example
+++++++++++++++++++++
+
+It will be useful to go walk a quick example just to reinforce what we've
+said.::
+
+ #include ``ns3/object.h''
+ #include ``ns3/uinteger.h''
+ #include ``ns3/traced-value.h''
+ #include ``ns3/trace-source-accessor.h''
+
+ #include <iostream>
+
+ using namespace ns3;
+
+The first thing to do is include the required files. As mentioned above, the
+trace system makes heavy use of the Object and Attribute systems. The first two
+includes bring in the declarations for those systems. The file,
+``traced-value.h`` brings in the required declarations for tracing data that
+obeys value semantics.
+
+In general, value semantics just means that you can pass the object around, not
+an address. In order to use value semantics at all you have to have an object
+with an associated copy constructor and assignment operator available. We extend
+the requirements to talk about the set of operators that are pre-defined for
+plain-old-data (POD) types. Operator=, operator++, operator--, operator+,
+operator==, etc.
+
+What this all means is that you will be able to trace changes to an object
+made using those operators.::
+
+ class MyObject : public Object
+ {
+ public:
+ static TypeId GetTypeId (void)
+ {
+ static TypeId tid = TypeId ("MyObject")
+ .SetParent (Object::GetTypeId ())
+ .AddConstructor<MyObject> ()
+ .AddTraceSource ("MyInteger",
+ "An integer value to trace.",
+ MakeTraceSourceAccessor (&MyObject::m_myInt))
+ ;
+ return tid;
+ }
+
+ MyObject () {}
+ TracedValue<uint32_t> m_myInt;
+ };
+
+Since the tracing system is integrated with Attributes, and Attributes work with
+Objects, there must be an |ns3| ``Object`` for the trace source to live in. The
+two important lines of code are the ``.AddTraceSource`` and the ``TracedValue``
+declaration.
+
+The ``.AddTraceSource`` provides the "hooks" used for connecting the trace
+source to the outside world. The ``TracedValue`` declaration provides the
+infrastructure that overloads the operators mentioned above and drives the
+callback process.::
+
+ void
+ IntTrace (Int oldValue, Int newValue)
+ {
+ std::cout << ``Traced `` << oldValue << `` to `` << newValue << std::endl;
+ }
+
+This is the definition of the trace sink. It corresponds directly to a callback
+function. This function will be called whenever one of the operators of the
+``TracedValue`` is executed.::
+
+ int
+ main (int argc, char *argv[])
+ {
+ Ptr<MyObject> myObject = CreateObject<MyObject> ();
+
+ myObject->TraceConnectWithoutContext ("MyInteger", MakeCallback(&IntTrace));
+
+ myObject->m_myInt = 1234;
+ }
+
+In this snippet, the first thing that needs to be done is to create the object
+in which the trace source lives.
+
+The next step, the ``TraceConnectWithoutContext``, forms the connection between
+the trace source and the trace sink. Notice the ``MakeCallback`` template
+function. Recall from the Callback section that this creates the specialized
+functor responsible for providing the overloaded ``operator()`` used to "fire"
+the callback. The overloaded operators (++, --, etc.) will use this
+``operator()`` to actually invoke the callback. The
+``TraceConnectWithoutContext``, takes a string parameter that provides the name
+of the Attribute assigned to the trace source. Let's ignore the bit about
+context for now since it is not important yet.
+
+Finally, the line,::
+
+ myObject->m_myInt = 1234;
+
+should be interpreted as an invocation of ``operator=`` on the member variable
+``m_myInt`` with the integer :math:`1234` passed as a parameter. It turns out
+that this operator is defined (by ``TracedValue``) to execute a callback that
+returns void and takes two integer values as parameters -- an old value and a
+new value for the integer in question. That is exactly the function signature
+for the callback function we provided -- ``IntTrace``.
+
+To summarize, a trace source is, in essence, a variable that holds a list of
+callbacks. A trace sink is a function used as the target of a callback. The
+Attribute and object type information systems are used to provide a way to
+connect trace sources to trace sinks. The act of "hitting" a trace source is
+executing an operator on the trace source which fires callbacks. This results in
+the trace sink callbacks registering interest in the source being called with
+the parameters provided by the source.
+
+Using the Config Subsystem to Connect to Trace Sources
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The ``TraceConnectWithoutContext`` call shown above in the simple example is
+actually very rarely used in the system. More typically, the ``Config``
+subsystem is used to allow selecting a trace source in the system using what is
+called a *config path*.
+
+For example, one might find something that looks like the following in the
+system (taken from ``examples/tcp-large-transfer.cc``)::
+
+ void CwndTracer (uint32_t oldval, uint32_t newval) {}
+
+ ...
+
+ Config::ConnectWithoutContext (
+ "/NodeList/0/$ns3::TcpL4Protocol/SocketList/0/CongestionWindow",
+ MakeCallback (&CwndTracer));
+
+This should look very familiar. It is the same thing as the previous example,
+except that a static member function of class ``Config`` is being called instead
+of a method on ``Object``; and instead of an ``Attribute`` name, a path is being
+provided.
+
+The first thing to do is to read the path backward. The last segment of the path
+must be an ``Attribute`` of an ``Object``. In fact, if you had a pointer to the
+``Object`` that has the "CongestionWindow" ``Attribute`` handy (call it
+``theObject``), you could write this just like the previous example:::
+
+ void CwndTracer (uint32_t oldval, uint32_t newval) {}
+
+ ...
+
+ theObject->TraceConnectWithoutContext ("CongestionWindow", MakeCallback (&CwndTracer));
+
+It turns out that the code for ``Config::ConnectWithoutContext`` does exactly
+that. This function takes a path that represents a chain of ``Object`` pointers
+and follows them until it gets to the end of the path and interprets the last
+segment as an ``Attribute`` on the last object. Let's walk through what
+happens.
+
+The leading "/" character in the path refers to a so-called namespace. One of the
+predefined namespaces in the config system is "NodeList" which is a list of all of
+the nodes in the simulation. Items in the list are referred to by indices into the
+list, so "/NodeList/0" refers to the zeroth node in the list of nodes created by
+the simulation. This node is actually a ``Ptr<Node>`` and so is a subclass of
+an :cpp:class:`ns3::Object`.
+
+As described in the :ref:`Object Model` section, |ns3| supports an object
+aggregation model. The next path segment begins with the "$" character which
+indicates a ``GetObject`` call should be made looking for the type that follows.
+When a node is initialized by an ``InternetStackHelper`` a number of interfaces
+are aggregated to the node. One of these is the TCP level four protocol. The
+runtime type of this protocol object is "ns3::TcpL4Protocol". When the
+``GetObject`` is executed, it returns a pointer to the object of this type.
+
+The ``TcpL4Protocol`` class defines an Attribute called "SocketList" which is a
+list of sockets. Each socket is actually an ``ns3::Object`` with its own
+``Attributes``. The items in the list of sockets are referred to by index just
+as in the NodeList, so "SocketList/0" refers to the zeroth socket in the list of
+sockets on the zeroth node in the NodeList -- the first node constructed in the
+simulation.
+
+This socket, the type of which turns out to be an ``ns3::TcpSocketImpl`` defines
+an attribute called "CongestionWindow" which is a ``TracedValue<uint32_t>``.
+The ``Config::ConnectWithoutContext`` now does a,::
+
+ object->TraceConnectWithoutContext ("CongestionWindow", MakeCallback (&CwndTracer));
+
+using the object pointer from "SocketList/0" which makes the connection between
+the trace source defined in the socket to the callback -- ``CwndTracer``.
+
+Now, whenever a change is made to the ``TracedValue<uint32_t>`` representing the
+congestion window in the TCP socket, the registered callback will be executed
+and the function ``CwndTracer`` will be called printing out the old and new
+values of the TCP congestion window.
+
+Using the Tracing API
+*********************
+
+There are three levels of interaction with the tracing system:
+
+* Beginning user can easily control which objects are participating in tracing;
+* Intermediate users can extend the tracing system to modify the output format
+ generated or use existing trace sources in different ways, without modifying
+ the core of the simulator;
+* Advanced users can modify the simulator core to add new tracing sources and
+ sinks.
+
+Using Trace Helpers
+*******************
+
+The |ns3| trace helpers provide a rich environment for configuring and selecting
+different trace events and writing them to files. In previous sections,
+primarily "Building Topologies," we have seen several varieties of the trace
+helper methods designed for use inside other (device) helpers.
+
+Perhaps you will recall seeing some of these variations:::
+
+ pointToPoint.EnablePcapAll ("second");
+ pointToPoint.EnablePcap ("second", p2pNodes.Get (0)->GetId (), 0);
+ csma.EnablePcap ("third", csmaDevices.Get (0), true);
+ pointToPoint.EnableAsciiAll (ascii.CreateFileStream ("myfirst.tr"));
+
+What may not be obvious, though, is that there is a consistent model for all of
+the trace-related methods found in the system. We will now take a little time
+and take a look at the "big picture".
+
+There are currently two primary use cases of the tracing helpers in |ns3|:
+Device helpers and protocol helpers. Device helpers look at the problem of
+specifying which traces should be enabled through a node, device pair. For
+example, you may want to specify that pcap tracing should be enabled on a
+particular device on a specific node. This follows from the |ns3| device
+conceptual model, and also the conceptual models of the various device helpers.
+Following naturally from this, the files created follow a
+<prefix>-<node>-<device> naming convention.
+
+Protocol helpers look at the problem of specifying which traces should be
+enabled through a protocol and interface pair. This follows from the |ns3|
+protocol stack conceptual model, and also the conceptual models of internet
+stack helpers. Naturally, the trace files should follow a
+<prefix>-<protocol>-<interface> naming convention.
+
+The trace helpers therefore fall naturally into a two-dimensional taxonomy.
+There are subtleties that prevent all four classes from behaving identically,
+but we do strive to make them all work as similarly as possible; and whenever
+possible there are analogs for all methods in all classes.::
+
+ | pcap | ascii |
+ -----------------+------+-------|
+ Device Helper | | |
+ -----------------+------+-------|
+ Protocol Helper | | |
+ -----------------+------+-------|
+
+We use an approach called a ``mixin`` to add tracing functionality to our helper
+classes. A ``mixin`` is a class that provides functionality to that is
+inherited by a subclass. Inheriting from a mixin is not considered a form of
+specialization but is really a way to collect functionality.
+
+Let's take a quick look at all four of these cases and their respective
+``mixins``.
+
+Pcap Tracing Device Helpers
++++++++++++++++++++++++++++
+
+The goal of these helpers is to make it easy to add a consistent pcap trace
+facility to an |ns3| device. We want all of the various flavors of pcap tracing
+to work the same across all devices, so the methods of these helpers are
+inherited by device helpers. Take a look at ``src/helper/trace-helper.h`` if you
+want to follow the discussion while looking at real code.
+
+The class ``PcapHelperForDevice`` is a ``mixin`` provides the high level
+functionality for using pcap tracing in an |ns3| device. Every device must
+implement a single virtual method inherited from this class.::
+
+ virtual void EnablePcapInternal (std::string prefix, Ptr<NetDevice> nd, bool promiscuous) = 0;
+
+The signature of this method reflects the device-centric view of the situation
+at this level. All of the public methods inherited from class
+``PcapUserHelperForDevice`` reduce to calling this single device-dependent
+implementation method. For example, the lowest level pcap method,::
+
+ void EnablePcap (std::string prefix, Ptr<NetDevice> nd, bool promiscuous = false, bool explicitFilename = false);
+
+will call the device implementation of ``EnablePcapInternal`` directly. All
+other public pcap tracing methods build on this implementation to provide
+additional user-level functionality. What this means to the user is that all
+device helpers in the system will have all of the pcap trace methods available;
+and these methods will all work in the same way across devices if the device
+implements ``EnablePcapInternal`` correctly.
+
+Pcap Tracing Device Helper Methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ void EnablePcap (std::string prefix, Ptr<NetDevice> nd, bool promiscuous = false, bool explicitFilename = false);
+ void EnablePcap (std::string prefix, std::string ndName, bool promiscuous = false, bool explicitFilename = false);
+ void EnablePcap (std::string prefix, NetDeviceContainer d, bool promiscuous = false);
+ void EnablePcap (std::string prefix, NodeContainer n, bool promiscuous = false);
+ void EnablePcap (std::string prefix, uint32_t nodeid, uint32_t deviceid, bool promiscuous = false);
+ void EnablePcapAll (std::string prefix, bool promiscuous = false);
+
+In each of the methods shown above, there is a default parameter called
+``promiscuous`` that defaults to false. This parameter indicates that the trace
+should not be gathered in promiscuous mode. If you do want your traces to
+include all traffic seen by the device (and if the device supports a promiscuous
+mode) simply add a true parameter to any of the calls above. For example,::
+
+ Ptr<NetDevice> nd;
+ ...
+ helper.EnablePcap ("prefix", nd, true);
+
+will enable promiscuous mode captures on the ``NetDevice`` specified by ``nd``.
+
+The first two methods also include a default parameter called
+``explicitFilename`` that will be discussed below.
+
+You are encouraged to peruse the Doxygen for class ``PcapHelperForDevice`` to
+find the details of these methods; but to summarize ...
+
+You can enable pcap tracing on a particular node/net-device pair by providing a
+``Ptr<NetDevice>`` to an ``EnablePcap`` method. The ``Ptr<Node>`` is implicit
+since the net device must belong to exactly one ``Node``. For example,::
+
+ Ptr<NetDevice> nd;
+ ...
+ helper.EnablePcap ("prefix", nd);
+
+You can enable pcap tracing on a particular node/net-device pair by providing a
+``std::string`` representing an object name service string to an ``EnablePcap``
+method. The ``Ptr<NetDevice>`` is looked up from the name string. Again, the
+``<Node>`` is implicit since the named net device must belong to exactly one
+``Node``. For example,::
+
+ Names::Add ("server" ...);
+ Names::Add ("server/eth0" ...);
+ ...
+ helper.EnablePcap ("prefix", "server/ath0");
+
+You can enable pcap tracing on a collection of node/net-device pairs by
+providing a ``NetDeviceContainer``. For each ``NetDevice`` in the container the
+type is checked. For each device of the proper type (the same type as is
+managed by the device helper), tracing is enabled. Again, the ``<Node>`` is
+implicit since the found net device must belong to exactly one ``Node``. For
+example,::
+
+ NetDeviceContainer d = ...;
+ ...
+ helper.EnablePcap ("prefix", d);
+
+You can enable pcap tracing on a collection of node/net-device pairs by
+providing a ``NodeContainer``. For each ``Node`` in the ``NodeContainer`` its
+attached ``NetDevices`` are iterated. For each ``NetDevice`` attached to each
+node in the container, the type of that device is checked. For each device of
+the proper type (the same type as is managed by the device helper), tracing is
+enabled.::
+
+ NodeContainer n;
+ ...
+ helper.EnablePcap ("prefix", n);
+
+You can enable pcap tracing on the basis of node ID and device ID as well as
+with explicit ``Ptr``. Each ``Node`` in the system has an integer node ID and
+each device connected to a node has an integer device ID.::
+
+ helper.EnablePcap ("prefix", 21, 1);
+
+Finally, you can enable pcap tracing for all devices in the system, with the
+same type as that managed by the device helper.::
+
+ helper.EnablePcapAll ("prefix");
+
+Pcap Tracing Device Helper Filename Selection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Implicit in the method descriptions above is the construction of a complete
+filename by the implementation method. By convention, pcap traces in the |ns3|
+system are of the form ``<prefix>-<node id>-<device id>.pcap``
+
+As previously mentioned, every node in the system will have a system-assigned
+node id; and every device will have an interface index (also called a device id)
+relative to its node. By default, then, a pcap trace file created as a result
+of enabling tracing on the first device of node 21 using the prefix "prefix"
+would be ``prefix-21-1.pcap``.
+
+You can always use the |ns3| object name service to make this more clear. For
+example, if you use the object name service to assign the name "server" to node
+21, the resulting pcap trace file name will automatically become,
+``prefix-server-1.pcap`` and if you also assign the name "eth0" to the device,
+your pcap file name will automatically pick this up and be called
+``prefix-server-eth0.pcap``.
+
+Finally, two of the methods shown above,::
+
+ void EnablePcap (std::string prefix, Ptr<NetDevice> nd, bool promiscuous = false, bool explicitFilename = false);
+ void EnablePcap (std::string prefix, std::string ndName, bool promiscuous = false, bool explicitFilename = false);
+
+have a default parameter called ``explicitFilename``. When set to true, this
+parameter disables the automatic filename completion mechanism and allows you to
+create an explicit filename. This option is only available in the methods which
+enable pcap tracing on a single device.
+
+For example, in order to arrange for a device helper to create a single
+promiscuous pcap capture file of a specific name (``my-pcap-file.pcap``) on a
+given device, one could:::
+
+ Ptr<NetDevice> nd;
+ ...
+ helper.EnablePcap ("my-pcap-file.pcap", nd, true, true);
+
+The first ``true`` parameter enables promiscuous mode traces and the second
+tells the helper to interpret the ``prefix`` parameter as a complete filename.
+
+Ascii Tracing Device Helpers
+++++++++++++++++++++++++++++
+
+The behavior of the ascii trace helper ``mixin`` is substantially similar to
+the pcap version. Take a look at ``src/helper/trace-helper.h`` if you want to
+follow the discussion while looking at real code.
+
+The class ``AsciiTraceHelperForDevice`` adds the high level functionality for
+using ascii tracing to a device helper class. As in the pcap case, every device
+must implement a single virtual method inherited from the ascii trace
+``mixin``.::
+
+ virtual void EnableAsciiInternal (Ptr<OutputStreamWrapper> stream, std::string prefix, Ptr<NetDevice> nd) = 0;
+
+The signature of this method reflects the device-centric view of the situation
+at this level; and also the fact that the helper may be writing to a shared
+output stream. All of the public ascii-trace-related methods inherited from
+class ``AsciiTraceHelperForDevice`` reduce to calling this single device-
+dependent implementation method. For example, the lowest level ascii trace
+methods,::
+
+ void EnableAscii (std::string prefix, Ptr<NetDevice> nd);
+ void EnableAscii (Ptr<OutputStreamWrapper> stream, Ptr<NetDevice> nd);
+
+will call the device implementation of ``EnableAsciiInternal`` directly,
+providing either a valid prefix or stream. All other public ascii tracing
+methods will build on these low-level functions to provide additional user-level
+functionality. What this means to the user is that all device helpers in the
+system will have all of the ascii trace methods available; and these methods
+will all work in the same way across devices if the devices implement
+``EnablAsciiInternal`` correctly.
+
+Ascii Tracing Device Helper Methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ void EnableAscii (std::string prefix, Ptr<NetDevice> nd);
+ void EnableAscii (Ptr<OutputStreamWrapper> stream, Ptr<NetDevice> nd);
+
+ void EnableAscii (std::string prefix, std::string ndName);
+ void EnableAscii (Ptr<OutputStreamWrapper> stream, std::string ndName);
+
+ void EnableAscii (std::string prefix, NetDeviceContainer d);
+ void EnableAscii (Ptr<OutputStreamWrapper> stream, NetDeviceContainer d);
+
+ void EnableAscii (std::string prefix, NodeContainer n);
+ void EnableAscii (Ptr<OutputStreamWrapper> stream, NodeContainer n);
+
+ void EnableAscii (std::string prefix, uint32_t nodeid, uint32_t deviceid);
+ void EnableAscii (Ptr<OutputStreamWrapper> stream, uint32_t nodeid, uint32_t deviceid);
+
+ void EnableAsciiAll (std::string prefix);
+ void EnableAsciiAll (Ptr<OutputStreamWrapper> stream);
+
+You are encouraged to peruse the Doxygen for class ``TraceHelperForDevice`` to
+find the details of these methods; but to summarize ...
+
+There are twice as many methods available for ascii tracing as there were for
+pcap tracing. This is because, in addition to the pcap-style model where traces
+from each unique node/device pair are written to a unique file, we support a
+model in which trace information for many node/device pairs is written to a
+common file. This means that the <prefix>-<node>-<device> file name generation
+mechanism is replaced by a mechanism to refer to a common file; and the number
+of API methods is doubled to allow all combinations.
+
+Just as in pcap tracing, you can enable ascii tracing on a particular
+node/net-device pair by providing a ``Ptr<NetDevice>`` to an ``EnableAscii``
+method. The ``Ptr<Node>`` is implicit since the net device must belong to
+exactly one ``Node``. For example,::
+
+ Ptr<NetDevice> nd;
+ ...
+ helper.EnableAscii ("prefix", nd);
+
+In this case, no trace contexts are written to the ascii trace file since they
+would be redundant. The system will pick the file name to be created using the
+same rules as described in the pcap section, except that the file will have the
+suffix ".tr" instead of ".pcap".
+
+If you want to enable ascii tracing on more than one net device and have all
+traces sent to a single file, you can do that as well by using an object to
+refer to a single file:::
+
+ Ptr<NetDevice> nd1;
+ Ptr<NetDevice> nd2;
+ ...
+ Ptr<OutputStreamWrapper> stream = asciiTraceHelper.CreateFileStream ("trace-file-name.tr");
+ ...
+ helper.EnableAscii (stream, nd1);
+ helper.EnableAscii (stream, nd2);
+
+In this case, trace contexts are written to the ascii trace file since they
+are required to disambiguate traces from the two devices. Note that since the
+user is completely specifying the file name, the string should include the ".tr"
+for consistency.
+
+You can enable ascii tracing on a particular node/net-device pair by providing a
+``std::string`` representing an object name service string to an
+``EnablePcap`` method. The ``Ptr<NetDevice>`` is looked up from the name
+string. Again, the ``<Node>`` is implicit since the named net device must
+belong to exactly one ``Node``. For example,::
+
+ Names::Add ("client" ...);
+ Names::Add ("client/eth0" ...);
+ Names::Add ("server" ...);
+ Names::Add ("server/eth0" ...);
+ ...
+ helper.EnableAscii ("prefix", "client/eth0");
+ helper.EnableAscii ("prefix", "server/eth0");
+
+This would result in two files named ``prefix-client-eth0.tr`` and
+``prefix-server-eth0.tr`` with traces for each device in the respective trace
+file. Since all of the EnableAscii functions are overloaded to take a stream
+wrapper, you can use that form as well:::
+
+ Names::Add ("client" ...);
+ Names::Add ("client/eth0" ...);
+ Names::Add ("server" ...);
+ Names::Add ("server/eth0" ...);
+ ...
+ Ptr<OutputStreamWrapper> stream = asciiTraceHelper.CreateFileStream ("trace-file-name.tr");
+ ...
+ helper.EnableAscii (stream, "client/eth0");
+ helper.EnableAscii (stream, "server/eth0");
+
+This would result in a single trace file called ``trace-file-name.tr`` that
+contains all of the trace events for both devices. The events would be
+disambiguated by trace context strings.
+
+You can enable ascii tracing on a collection of node/net-device pairs by
+providing a ``NetDeviceContainer``. For each ``NetDevice`` in the container the
+type is checked. For each device of the proper type (the same type as is managed
+by the device helper), tracing is enabled. Again, the ``<Node>`` is implicit
+since the found net device must belong to exactly one ``Node``. For example,::
+
+ NetDeviceContainer d = ...;
+ ...
+ helper.EnableAscii ("prefix", d);
+
+This would result in a number of ascii trace files being created, each of which
+follows the <prefix>-<node id>-<device id>.tr convention. Combining all of the
+traces into a single file is accomplished similarly to the examples above:::
+
+ NetDeviceContainer d = ...;
+ ...
+ Ptr<OutputStreamWrapper> stream = asciiTraceHelper.CreateFileStream ("trace-file-name.tr");
+ ...
+ helper.EnableAscii (stream, d);
+
+You can enable ascii tracing on a collection of node/net-device pairs by
+providing a ``NodeContainer``. For each ``Node`` in the ``NodeContainer`` its
+attached ``NetDevices`` are iterated. For each ``NetDevice`` attached to each
+node in the container, the type of that device is checked. For each device of
+the proper type (the same type as is managed by the device helper), tracing is
+enabled.::
+
+ NodeContainer n;
+ ...
+ helper.EnableAscii ("prefix", n);
+
+This would result in a number of ascii trace files being created, each of which
+follows the <prefix>-<node id>-<device id>.tr convention. Combining all of the
+traces into a single file is accomplished similarly to the examples above:
+
+You can enable pcap tracing on the basis of node ID and device ID as well as
+with explicit ``Ptr``. Each ``Node`` in the system has an integer node ID and
+each device connected to a node has an integer device ID.::
+
+ helper.EnableAscii ("prefix", 21, 1);
+
+Of course, the traces can be combined into a single file as shown above.
+
+Finally, you can enable pcap tracing for all devices in the system, with the
+same type as that managed by the device helper.::
+
+ helper.EnableAsciiAll ("prefix");
+
+This would result in a number of ascii trace files being created, one for
+every device in the system of the type managed by the helper. All of these
+files will follow the <prefix>-<node id>-<device id>.tr convention. Combining
+all of the traces into a single file is accomplished similarly to the examples
+above.
+
+Ascii Tracing Device Helper Filename Selection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Implicit in the prefix-style method descriptions above is the construction of
+the complete filenames by the implementation method. By convention, ascii traces
+in the |ns3| system are of the form ``<prefix>-<node id>-<device id>.tr``.
+
+As previously mentioned, every node in the system will have a system-assigned
+node id; and every device will have an interface index (also called a device id)
+relative to its node. By default, then, an ascii trace file created as a result
+of enabling tracing on the first device of node 21, using the prefix "prefix",
+would be ``prefix-21-1.tr``.
+
+You can always use the |ns3| object name service to make this more clear. For
+example, if you use the object name service to assign the name "server" to node
+21, the resulting ascii trace file name will automatically become,
+``prefix-server-1.tr`` and if you also assign the name "eth0" to the device,
+your ascii trace file name will automatically pick this up and be called
+``prefix-server-eth0.tr``.
+
+Pcap Tracing Protocol Helpers
++++++++++++++++++++++++++++++
+
+The goal of these ``mixins`` is to make it easy to add a consistent pcap trace
+facility to protocols. We want all of the various flavors of pcap tracing to
+work the same across all protocols, so the methods of these helpers are
+inherited by stack helpers. Take a look at ``src/helper/trace-helper.h`` if you
+want to follow the discussion while looking at real code.
+
+In this section we will be illustrating the methods as applied to the protocol
+``Ipv4``. To specify traces in similar protocols, just substitute the
+appropriate type. For example, use a ``Ptr<Ipv6>`` instead of a ``Ptr<Ipv4>``
+and call ``EnablePcapIpv6`` instead of ``EnablePcapIpv4``.
+
+The class ``PcapHelperForIpv4`` provides the high level functionality for using
+pcap tracing in the ``Ipv4`` protocol. Each protocol helper enabling these
+methods must implement a single virtual method inherited from this class. There
+will be a separate implementation for ``Ipv6``, for example, but the only
+difference will be in the method names and signatures. Different method names
+are required to disambiguate class ``Ipv4`` from ``Ipv6`` which are both derived
+from class ``Object``, and methods that share the same signature.::
+
+ virtual void EnablePcapIpv4Internal (std::string prefix, Ptr<Ipv4> ipv4, uint32_t interface) = 0;
+
+The signature of this method reflects the protocol and interface-centric view of
+the situation at this level. All of the public methods inherited from class
+``PcapHelperForIpv4`` reduce to calling this single device-dependent
+implementation method. For example, the lowest level pcap method,::
+
+ void EnablePcapIpv4 (std::string prefix, Ptr<Ipv4> ipv4, uint32_t interface);
+
+will call the device implementation of ``EnablePcapIpv4Internal`` directly. All
+other public pcap tracing methods build on this implementation to provide
+additional user-level functionality. What this means to the user is that all
+protocol helpers in the system will have all of the pcap trace methods
+available; and these methods will all work in the same way across protocols if
+the helper implements ``EnablePcapIpv4Internal`` correctly.
+
+Pcap Tracing Protocol Helper Methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These methods are designed to be in one-to-one correspondence with the ``Node``-
+and ``NetDevice``- centric versions of the device versions. Instead of
+``Node`` and ``NetDevice`` pair constraints, we use protocol and interface
+constraints.
+
+Note that just like in the device version, there are six methods:::
+
+ void EnablePcapIpv4 (std::string prefix, Ptr<Ipv4> ipv4, uint32_t interface);
+ void EnablePcapIpv4 (std::string prefix, std::string ipv4Name, uint32_t interface);
+ void EnablePcapIpv4 (std::string prefix, Ipv4InterfaceContainer c);
+ void EnablePcapIpv4 (std::string prefix, NodeContainer n);
+ void EnablePcapIpv4 (std::string prefix, uint32_t nodeid, uint32_t interface);
+ void EnablePcapIpv4All (std::string prefix);
+
+You are encouraged to peruse the Doxygen for class ``PcapHelperForIpv4`` to find
+the details of these methods; but to summarize ...
+
+You can enable pcap tracing on a particular protocol/interface pair by providing
+a ``Ptr<Ipv4>`` and ``interface`` to an ``EnablePcap`` method. For example,::
+
+ Ptr<Ipv4> ipv4 = node->GetObject<Ipv4> ();
+ ...
+ helper.EnablePcapIpv4 ("prefix", ipv4, 0);
+
+You can enable pcap tracing on a particular node/net-device pair by providing a
+``std::string`` representing an object name service string to an ``EnablePcap``
+method. The ``Ptr<Ipv4>`` is looked up from the name string. For example,::
+
+ Names::Add ("serverIPv4" ...);
+ ...
+ helper.EnablePcapIpv4 ("prefix", "serverIpv4", 1);
+
+You can enable pcap tracing on a collection of protocol/interface pairs by
+providing an ``Ipv4InterfaceContainer``. For each ``Ipv4`` / interface pair in
+the container the protocol type is checked. For each protocol of the proper type
+(the same type as is managed by the device helper), tracing is enabled for the
+corresponding interface. For example,::
+
+ NodeContainer nodes;
+ ...
+ NetDeviceContainer devices = deviceHelper.Install (nodes);
+ ...
+ Ipv4AddressHelper ipv4;
+ ipv4.SetBase ("10.1.1.0", "255.255.255.0");
+ Ipv4InterfaceContainer interfaces = ipv4.Assign (devices);
+ ...
+ helper.EnablePcapIpv4 ("prefix", interfaces);
+
+You can enable pcap tracing on a collection of protocol/interface pairs by
+providing a ``NodeContainer``. For each ``Node`` in the ``NodeContainer`` the
+appropriate protocol is found. For each protocol, its interfaces are enumerated
+and tracing is enabled on the resulting pairs. For example,::
+
+ NodeContainer n;
+ ...
+ helper.EnablePcapIpv4 ("prefix", n);
+
+You can enable pcap tracing on the basis of node ID and interface as well. In
+this case, the node-id is translated to a ``Ptr<Node>`` and the appropriate
+protocol is looked up in the node. The resulting protocol and interface are used
+to specify the resulting trace source.::
+
+ helper.EnablePcapIpv4 ("prefix", 21, 1);
+
+Finally, you can enable pcap tracing for all interfaces in the system, with
+associated protocol being the same type as that managed by the device helper.::
+
+ helper.EnablePcapIpv4All ("prefix");
+
+Pcap Tracing Protocol Helper Filename Selection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Implicit in all of the method descriptions above is the construction of the
+complete filenames by the implementation method. By convention, pcap traces
+taken for devices in the |ns3| system are of the form ``<prefix>-<node
+id>-<device id>.pcap``. In the case of protocol traces, there is a one-to-one
+correspondence between protocols and ``Nodes``. This is because protocol
+``Objects`` are aggregated to ``Node Objects``. Since there is no global
+protocol id in the system, we use the corresponding node id in file naming.
+Therefore there is a possibility for file name collisions in automatically
+chosen trace file names. For this reason, the file name convention is changed
+for protocol traces.
+
+As previously mentioned, every node in the system will have a system-assigned
+node id. Since there is a one-to-one correspondence between protocol instances
+and node instances we use the node id. Each interface has an interface id
+relative to its protocol. We use the convention "<prefix>-n<node id>-i<interface
+id>.pcap" for trace file naming in protocol helpers.
+
+Therefore, by default, a pcap trace file created as a result of enabling tracing
+on interface 1 of the Ipv4 protocol of node 21 using the prefix "prefix"
+would be "prefix-n21-i1.pcap".
+
+You can always use the |ns3| object name service to make this more clear.
+For example, if you use the object name service to assign the name "serverIpv4"
+to the Ptr<Ipv4> on node 21, the resulting pcap trace file name will
+automatically become, "prefix-nserverIpv4-i1.pcap".
+
+Ascii Tracing Protocol Helpers
+++++++++++++++++++++++++++++++
+
+The behavior of the ascii trace helpers is substantially similar to the pcap
+case. Take a look at ``src/helper/trace-helper.h`` if you want to follow the
+discussion while looking at real code.
+
+In this section we will be illustrating the methods as applied to the protocol
+``Ipv4``. To specify traces in similar protocols, just substitute the
+appropriate type. For example, use a ``Ptr<Ipv6>`` instead of a ``Ptr<Ipv4>``
+and call ``EnableAsciiIpv6`` instead of ``EnableAsciiIpv4``.
+
+The class ``AsciiTraceHelperForIpv4`` adds the high level functionality for
+using ascii tracing to a protocol helper. Each protocol that enables these
+methods must implement a single virtual method inherited from this class.::
+
+ virtual void EnableAsciiIpv4Internal (Ptr<OutputStreamWrapper> stream, std::string prefix,
+ Ptr<Ipv4> ipv4, uint32_t interface) = 0;
+
+The signature of this method reflects the protocol- and interface-centric view
+of the situation at this level; and also the fact that the helper may be writing
+to a shared output stream. All of the public methods inherited from class
+``PcapAndAsciiTraceHelperForIpv4`` reduce to calling this single device-
+dependent implementation method. For example, the lowest level ascii trace
+methods,::
+
+ void EnableAsciiIpv4 (std::string prefix, Ptr<Ipv4> ipv4, uint32_t interface);
+ void EnableAsciiIpv4 (Ptr<OutputStreamWrapper> stream, Ptr<Ipv4> ipv4, uint32_t interface);
+
+will call the device implementation of ``EnableAsciiIpv4Internal`` directly,
+providing either the prefix or the stream. All other public ascii tracing
+methods will build on these low-level functions to provide additional user-level
+functionality. What this means to the user is that all device helpers in the
+system will have all of the ascii trace methods available; and these methods
+will all work in the same way across protocols if the protocols implement
+``EnablAsciiIpv4Internal`` correctly.
+
+Ascii Tracing Device Helper Methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ void EnableAsciiIpv4 (std::string prefix, Ptr<Ipv4> ipv4, uint32_t interface);
+ void EnableAsciiIpv4 (Ptr<OutputStreamWrapper> stream, Ptr<Ipv4> ipv4, uint32_t interface);
+
+ void EnableAsciiIpv4 (std::string prefix, std::string ipv4Name, uint32_t interface);
+ void EnableAsciiIpv4 (Ptr<OutputStreamWrapper> stream, std::string ipv4Name, uint32_t interface);
+
+ void EnableAsciiIpv4 (std::string prefix, Ipv4InterfaceContainer c);
+ void EnableAsciiIpv4 (Ptr<OutputStreamWrapper> stream, Ipv4InterfaceContainer c);
+
+ void EnableAsciiIpv4 (std::string prefix, NodeContainer n);
+ void EnableAsciiIpv4 (Ptr<OutputStreamWrapper> stream, NodeContainer n);
+
+ void EnableAsciiIpv4 (std::string prefix, uint32_t nodeid, uint32_t deviceid);
+ void EnableAsciiIpv4 (Ptr<OutputStreamWrapper> stream, uint32_t nodeid, uint32_t interface);
+
+ void EnableAsciiIpv4All (std::string prefix);
+ void EnableAsciiIpv4All (Ptr<OutputStreamWrapper> stream);
+
+You are encouraged to peruse the Doxygen for class ``PcapAndAsciiHelperForIpv4``
+to find the details of these methods; but to summarize ...
+
+There are twice as many methods available for ascii tracing as there were for
+pcap tracing. This is because, in addition to the pcap-style model where traces
+from each unique protocol/interface pair are written to a unique file, we
+support a model in which trace information for many protocol/interface pairs is
+written to a common file. This means that the <prefix>-n<node id>-<interface>
+file name generation mechanism is replaced by a mechanism to refer to a common
+file; and the number of API methods is doubled to allow all combinations.
+
+Just as in pcap tracing, you can enable ascii tracing on a particular
+protocol/interface pair by providing a ``Ptr<Ipv4>`` and an ``interface`` to an
+``EnableAscii`` method. For example,::
+
+ Ptr<Ipv4> ipv4;
+ ...
+ helper.EnableAsciiIpv4 ("prefix", ipv4, 1);
+
+In this case, no trace contexts are written to the ascii trace file since they
+would be redundant. The system will pick the file name to be created using the
+same rules as described in the pcap section, except that the file will have the
+suffix ".tr" instead of ".pcap".
+
+If you want to enable ascii tracing on more than one interface and have all
+traces sent to a single file, you can do that as well by using an object to
+refer to a single file. We have already something similar to this in the "cwnd"
+example above:::
+
+ Ptr<Ipv4> protocol1 = node1->GetObject<Ipv4> ();
+ Ptr<Ipv4> protocol2 = node2->GetObject<Ipv4> ();
+ ...
+ Ptr<OutputStreamWrapper> stream = asciiTraceHelper.CreateFileStream ("trace-file-name.tr");
+ ...
+ helper.EnableAsciiIpv4 (stream, protocol1, 1);
+ helper.EnableAsciiIpv4 (stream, protocol2, 1);
+
+In this case, trace contexts are written to the ascii trace file since they are
+required to disambiguate traces from the two interfaces. Note that since the
+user is completely specifying the file name, the string should include the ".tr"
+for consistency.
+
+You can enable ascii tracing on a particular protocol by providing a
+``std::string`` representing an object name service string to an ``EnablePcap``
+method. The ``Ptr<Ipv4>`` is looked up from the name string. The ``<Node>`` in
+the resulting filenames is implicit since there is a one-to-one correspondence
+between protocol instances and nodes, For example,::
+
+ Names::Add ("node1Ipv4" ...);
+ Names::Add ("node2Ipv4" ...);
+ ...
+ helper.EnableAsciiIpv4 ("prefix", "node1Ipv4", 1);
+ helper.EnableAsciiIpv4 ("prefix", "node2Ipv4", 1);
+
+This would result in two files named "prefix-nnode1Ipv4-i1.tr" and
+"prefix-nnode2Ipv4-i1.tr" with traces for each interface in the respective
+trace file. Since all of the EnableAscii functions are overloaded to take a
+stream wrapper, you can use that form as well:::
+
+ Names::Add ("node1Ipv4" ...);
+ Names::Add ("node2Ipv4" ...);
+ ...
+ Ptr<OutputStreamWrapper> stream = asciiTraceHelper.CreateFileStream ("trace-file-name.tr");
+ ...
+ helper.EnableAsciiIpv4 (stream, "node1Ipv4", 1);
+ helper.EnableAsciiIpv4 (stream, "node2Ipv4", 1);
+
+This would result in a single trace file called "trace-file-name.tr" that
+contains all of the trace events for both interfaces. The events would be
+disambiguated by trace context strings.
+
+You can enable ascii tracing on a collection of protocol/interface pairs by
+providing an ``Ipv4InterfaceContainer``. For each protocol of the proper type
+(the same type as is managed by the device helper), tracing is enabled for the
+corresponding interface. Again, the ``<Node>`` is implicit since there is a
+one-to-one correspondence between each protocol and its node. For example,::
+
+ NodeContainer nodes;
+ ...
+ NetDeviceContainer devices = deviceHelper.Install (nodes);
+ ...
+ Ipv4AddressHelper ipv4;
+ ipv4.SetBase ("10.1.1.0", "255.255.255.0");
+ Ipv4InterfaceContainer interfaces = ipv4.Assign (devices);
+ ...
+ ...
+ helper.EnableAsciiIpv4 ("prefix", interfaces);
+
+This would result in a number of ascii trace files being created, each of which
+follows the <prefix>-n<node id>-i<interface>.tr convention. Combining all of the
+traces into a single file is accomplished similarly to the examples above:::
+
+ NodeContainer nodes;
+ ...
+ NetDeviceContainer devices = deviceHelper.Install (nodes);
+ ...
+ Ipv4AddressHelper ipv4;
+ ipv4.SetBase ("10.1.1.0", "255.255.255.0");
+ Ipv4InterfaceContainer interfaces = ipv4.Assign (devices);
+ ...
+ Ptr<OutputStreamWrapper> stream = asciiTraceHelper.CreateFileStream ("trace-file-name.tr");
+ ...
+ helper.EnableAsciiIpv4 (stream, interfaces);
+
+You can enable ascii tracing on a collection of protocol/interface pairs by
+providing a ``NodeContainer``. For each ``Node`` in the ``NodeContainer`` the
+appropriate protocol is found. For each protocol, its interfaces are enumerated
+and tracing is enabled on the resulting pairs. For example,::
+
+ NodeContainer n;
+ ...
+ helper.EnableAsciiIpv4 ("prefix", n);
+
+This would result in a number of ascii trace files being created, each of which
+follows the <prefix>-<node id>-<device id>.tr convention. Combining all of the
+traces into a single file is accomplished similarly to the examples above:
+
+You can enable pcap tracing on the basis of node ID and device ID as well. In
+this case, the node-id is translated to a ``Ptr<Node>`` and the appropriate
+protocol is looked up in the node. The resulting protocol and interface are
+used to specify the resulting trace source.::
+
+ helper.EnableAsciiIpv4 ("prefix", 21, 1);
+
+Of course, the traces can be combined into a single file as shown above.
+
+Finally, you can enable ascii tracing for all interfaces in the system, with
+associated protocol being the same type as that managed by the device helper.::
+
+ helper.EnableAsciiIpv4All ("prefix");
+
+This would result in a number of ascii trace files being created, one for
+every interface in the system related to a protocol of the type managed by the
+helper. All of these files will follow the <prefix>-n<node id>-i<interface.tr
+convention. Combining all of the traces into a single file is accomplished
+similarly to the examples above.
+
+Ascii Tracing Device Helper Filename Selection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Implicit in the prefix-style method descriptions above is the construction of
+the complete filenames by the implementation method. By convention, ascii traces
+in the |ns3| system are of the form "<prefix>-<node id>-<device id>.tr."
+
+As previously mentioned, every node in the system will have a system-assigned
+node id. Since there is a one-to-one correspondence between protocols and nodes
+we use to node-id to identify the protocol identity. Every interface on a given
+protocol will have an interface index (also called simply an interface) relative
+to its protocol. By default, then, an ascii trace file created as a result of
+enabling tracing on the first device of node 21, using the prefix "prefix",
+would be "prefix-n21-i1.tr". Use the prefix to disambiguate multiple protocols
+per node.
+
+You can always use the |ns3| object name service to make this more clear.
+For example, if you use the object name service to assign the name "serverIpv4"
+to the protocol on node 21, and also specify interface one, the resulting ascii
+trace file name will automatically become, "prefix-nserverIpv4-1.tr".
+
+Tracing implementation details
+******************************
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/troubleshoot.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,82 @@
+.. include:: replace.txt
+
+Troubleshooting
+---------------
+
+This chapter posts some information about possibly common errors in building
+or running |ns3| programs.
+
+Please note that the wiki
+(`<http://www.nsnam.org/wiki/index.php/Troubleshooting>`_) may have contributed
+items.
+
+Build errors
+************
+
+Run-time errors
+***************
+
+Sometimes, errors can occur with a program after a successful build. These are
+run-time errors, and can commonly occur when memory is corrupted or pointer
+values are unexpectedly null.
+
+Here is an example of what might occur:::
+
+ ns-old:~/ns-3-nsc$ ./waf --run tcp-point-to-point
+ Entering directory `/home/tomh/ns-3-nsc/build'
+ Compilation finished successfully
+ Command ['/home/tomh/ns-3-nsc/build/debug/examples/tcp-point-to-point'] exited with code -11
+
+The error message says that the program terminated unsuccessfully, but it is
+not clear from this information what might be wrong. To examine more
+closely, try running it under the `gdb debugger
+<http://sources.redhat.com/gdb/>`_:::
+
+ ns-old:~/ns-3-nsc$ ./waf --run tcp-point-to-point --command-template="gdb %s"
+ Entering directory `/home/tomh/ns-3-nsc/build'
+ Compilation finished successfully
+ GNU gdb Red Hat Linux (6.3.0.0-1.134.fc5rh)
+ Copyright 2004 Free Software Foundation, Inc.
+ GDB is free software, covered by the GNU General Public License, and you are
+ welcome to change it and/or distribute copies of it under certain conditions.
+ Type "show copying" to see the conditions.
+ There is absolutely no warranty for GDB. Type "show warranty" for details.
+ This GDB was configured as "i386-redhat-linux-gnu"...Using host libthread_db
+ library "/lib/libthread_db.so.1".
+
+ (gdb) run
+ Starting program: /home/tomh/ns-3-nsc/build/debug/examples/tcp-point-to-point
+ Reading symbols from shared object read from target memory...done.
+ Loaded system supplied DSO at 0xf5c000
+
+ Program received signal SIGSEGV, Segmentation fault.
+ 0x0804aa12 in main (argc=1, argv=0xbfdfefa4)
+ at ../examples/tcp-point-to-point.cc:136
+ 136 Ptr<Socket> localSocket = socketFactory->CreateSocket ();
+ (gdb) p localSocket
+ $1 = {m_ptr = 0x3c5d65}
+ (gdb) p socketFactory
+ $2 = {m_ptr = 0x0}
+ (gdb) quit
+ The program is running. Exit anyway? (y or n) y
+
+Note first the way the program was invoked-- pass the command to run as an
+argument to the command template "gdb %s".
+
+This tells us that there was an attempt to dereference a null pointer
+socketFactory.
+
+Let's look around line 136 of tcp-point-to-point, as gdb suggests:::
+
+ Ptr<SocketFactory> socketFactory = n2->GetObject<SocketFactory> (Tcp::iid);
+ Ptr<Socket> localSocket = socketFactory->CreateSocket ();
+ localSocket->Bind ();
+
+The culprit here is that the return value of GetObject is not being checked and
+may be null.
+
+Sometimes you may need to use the `valgrind memory checker
+<http://valgrind.org>`_ for more subtle errors. Again, you invoke the use of
+valgrind similarly:::
+
+ ns-old:~/ns-3-nsc$ ./waf --run tcp-point-to-point --command-template="valgrind %s"
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/uan.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,421 @@
+UAN Framework
+-------------
+
+Underwater Acoustics Networks is a research field that, in the last year, is gathering attention from researchers all over the world. In fact, the need for underwater wireless communications exists in applications such as remote control in offshore oil industry [1]_, pollution monitoring in environmental systems, speech transmission between divers, mapping of the ocean floor, mine counter measures [4]_, seismic monitoring of ocean faults as well as climate changes monitoring. Unfortunately, making on-field measurements is very expensive and there are no commonly accepted standard to base on. Hence, the priority to make research work going on, it is to realize a complete simulation framework that researchers can use to experiment, make tests and make performance evaluation and comparison.
+
+The NS-3 UAN module is a first step in this direction, trying to offer a reliable and realistic tool. In fact, the UAN module offers accurate modelling of the underwater acoustic channel, a model of the WHOI acoustic modem (one of the widely used acoustic modems)[6]_ and its communications performance, and some MAC protocols.
+
+This project integrates the efforts of UAN module, extending it to make a simulation framework that researchers will be able to use for their aims. The extension consists of an Autonomous Underwater Vehicle (AUV) simulator (navigation and movement) along with an implementation of AUV batteries. Moreover, it will be implemented, a power model for a generic acoustic modem and, the physicals layers will be modified to use such model. For the moment, the UAN module can be used to make some sort of performance comparisons of the available MAC protocols, or tests the communication channel. With this extension, researchers will be able to use the framework to develop and evaluate their "applications". An application, is intended as a more complete concept, including each parts of the UAN module integrated with the framework's extensions. Then, the final result is a complete simulation stack for underwater network applications.
+
+
+Model Description
+*****************
+
+The source code for the UAN Framework lives in the directory
+``src/devices/uan``, ``src/devices/uan/auv`` and in ``src/contrib/energy`` for the contribution on
+the li-ion battery model.
+
+The UAN Framework is composed of two main parts:
+
+* the AUV mobility models, including Electric motor propelled AUV (REMUS class [3]_ [4]_ ) and Seaglider [5]_ models
+
+* the energy models, including AUV energy models, AUV energy sources (batteries) and an acoustic modem energy model
+
+As enabling component for the energy models, a Li-Ion batteries energy source has been implemented basing on [7]_ [8]_.
+
+Design
+======
+
+The development of the UAN Framework for ns-3 is composed by three consecutive steps. The first one is the development of the AUV simulator, the second one is the development of the UAN energy models and the third one is the integration of such components with the existing modules, UAN module and Energy Model. The module is implemented into the ``/src/contrib/uan`` folder for the part regarding acoustic modem energy model and in ``/src/contrib/uan/auv`` for the part regarding the AUV simulator.
+
+
+AUV mobility models
+###################
+
+The AUV mobility models have been designed as in the follows.
+
+Use cases
+^^^^^^^^^
+
+The user will be able to:
+
+* program the AUV to navigate over a path of waypoints
+* control the velocity of the AUV
+* control the depth of the AUV
+* control the direction of the AUV
+* control the pitch of the AUV
+* tell the AUV to emerge or submerge to a specified depth
+
+AUV mobility models design
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Implement a model of the navigation of AUV. This involves implementing two classes modelling the two major categories of AUVs: electric motor propelled (like REMUS class [3]_ [4]_) and "sea gliders" [5]_.
+The classic AUVs are submarine-like devices, propelled by an electric motor linked with a propeller. Instead, the "sea glider" class exploits small changes in its buoyancy that, in conjunction with wings, can convert vertical motion to horizontal. So, a glider will reach a point into the water by describing a "saw-tooth" movement.
+Modelling the AUV navigation, involves in considering a real-world AUV class thus, taking into account maximum speed, directional capabilities, emerging and submerging times.
+Regarding the sea gliders, it is modelled the characteristic saw-tooth movement, with AUV's speed driven by buoyancy and glide angle.
+
+.. _auvmobilitymodel:
+
+.. figure:: figures/auvmobility-classes.*
+
+ AUV's mobility model classes overview
+
+An :cpp:class:`ns3::AuvMobilityModel` interface has been designed to give users a generic interface to access AUV's navigation functions.
+The AuvMobilityModel interface is implemented by the RemusMobilityModel and the GliderMobilityModel classes. The AUV's mobility models organization it is shown in :ref:`auvmobilitymodel`.
+Both models use a constant velocity movement, thus the AuvMobilityModel interface derives from the ConstantVelocityMobilityModel. The two classes hold the navigation parameters for the two different AUVs, like maximum pitch angles, maximum operating depth, maximum and minimum speed values. The Glider model holds also some extra parameters like maximum buoyancy values, and maximum and minimum glide slopes.
+Both classes, RemusMobilityModel and GliderMobilityModel, handle also the AUV power consumption, utilizing the relative power models.
+Has been modified the WaypointMobilityModel to let it use a generic underlying ConstantVelocityModel to validate the waypoints and, to keep trace of the node's position. The default model is the classic ConstantVelocityModel but, for example in case of REMUS mobility model, the user can install the AUV mobility model into the waypoint model and then validating the waypoints against REMUS navigation constraints.
+
+
+Energy models
+#############
+
+The energy models have been designed as in the follows.
+
+Use cases
+^^^^^^^^^
+
+The user will be able to:
+
+* use a specific power profile for the acoustic modem
+* use a specific energy model for the AUV
+* trace the power consumption of AUV navigation, through AUV's energy model
+* trace the power consumprion underwater acoustic communications, through acoustic modem power profile
+
+We have integrated the Energy Model with the UAN module, to implement energy handling. We have implemented a specific energy model for the two AUV classes and, an energy source for Lithium batteries. This will be really useful for researchers to keep trace of the AUV operational life.
+We have implemented also an acoustic modem power profile, to keep trace of its power consumption. This can be used to compare protocols specific power performance. In order to use such power profile, the acoustic transducer physical layer has been modified to use the modem power profile. We have decoupled the physical layer from the transducer specific energy model, to let the users change the different energy models without changing the physical layer.
+
+
+AUV energy models
+^^^^^^^^^^^^^^^^^
+
+Basing on the Device Energy Model interface, it has been implemented a specific energy model for the two AUV classes (REMUS and Seaglider). This models reproduce the AUV's specific power consumption to give users accurate information. This model can be naturally used to evaluates the AUV operating life, as well as mission-related power consumption, etc. Have been developed two AUV energy models:
+
+* GliderEnergyModel, computes the power consumption of the vehicle based on the current buoyancy value and vertical speed [5]_
+* RemusEnergyModel, computes the power consumption of the vehicle based on the current speed, as it is propelled by a brush-less electric motor
+
+.. note::
+
+ TODO extend a little bit
+
+
+AUV energy sources
+^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+ [TODO]
+
+
+Acoustic modem energy model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Basing on the Device Energy Model interface, has been implemented a generic energy model for acoustic modem. The model allows to trace four modem's power-states: Sleep, Idle, Receiving, Transmitting. The default parameters for the energy model are set to fit those of the WHOI μmodem. The class follows pretty closely the RadioEnergyModel class as the transducer behaviour is pretty close to that of a wifi radio.
+
+The default power consumption values implemented into the model are as follows [6]:
+
++--------------+---------------------+
+| Modem State | Power Consumption |
++--------------+---------------------+
+| TX | 50 W |
++--------------+---------------------+
+| RX | 158 mW |
++--------------+---------------------+
+| Idle | 158 mW |
++--------------+---------------------+
+| Sleep | 5.8 mW |
++--------------+---------------------+
+
+
+UAN module energy modifications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The UAN module has been modified in order to utilize the implemented energy classes. Specifically, it has been modified the physical layer of the UAN module. It Has been implemented an UpdatePowerConsumption method that takes the modem's state as parameter. It checks if an energy source is installed into the node and, in case, it then use the AcousticModemEnergyModel to update the power consumption with the current modem's state. The modem power consumption's update takes place whenever the modem changes its state.
+
+A user should take into account that, if the the power consumption handling is enabled (if the node has an energy source installed), all the communications processes will terminate whether the node depletes all the energy source.
+
+
+Li-Ion batteries model
+^^^^^^^^^^^^^^^^^^^^^^
+
+A generic Li-Ion battery model has been implemented based on [7][8]. The model can be fitted to any type of Li-Ion battery simply changing the model's parameters The default values are fitted for the Panasonic CGR18650DA Li-Ion Battery [9].
+[TODO insert figure]
+As shown in figure the model approximates very well the Li-Ion cells.
+Regarding Seagliders, the batteries used into the AUV are Electrochem 3B36 Lithium / Sulfuryl Chloride cells [10]. Also with this cell type, the model seems to approximates the different discharge curves pretty well, as shown in the figure.
+
+.. note::
+
+ should I insert the li-ion model deatils here? I think it is better to put them into an Energy-related chapter..
+
+Scope and Limitations
+=====================
+
+The framework is designed to simulate AUV's behaviour. We have modeled the navigation and power consumption behaviour of REMUS class and Seaglider AUVs.
+The communications stack, associated with the AUV, can be modified depending on simulation needs. Usually, the default underwater stack is being used, composed of an half duplex acoustic modem, an Aloha MAC protocol and a generic physical layer.
+
+Regarding the AUV energy consumption, the user should be aware that the level of accuracy differs for the two classes:
+
+* Seaglider, high level of accuracy, thanks to the availability of detailed information on AUV's components and behaviour [5] [10]. Have been modeled both the navigation power consumption and the Li battery packs (according to [5]).
+* REMUS, medium level of accuracy, due to the lack of publicly available information on AUV's components. We have approximated the power consumption of the AUV's motor with a linear behaviour and, the energy source uses an ideal model (BasicEnergySource) with a power capacity equal to that specified in [4].
+
+Future Work
+===========
+
+Some ideas could be :
+
+* insert a data logging capability
+* modify the framework to use sockets (enabling the possibility to use applications)
+* introduce some more MAC protocols
+* modify the physical layer to let it consider the doppler spread (problematic in underwater environments)
+* introduce OFDM modulations
+
+References
+==========
+
+.. [1] BINGHAM, D.; DRAKE, T.; HILL, A.; LOTT, R.; The Application of Autonomous Underwater Vehicle (AUV) Technology in the Oil Industry – Vision and Experiences, URL: http://www.fig.net/pub/fig_2002/Ts4-4/TS4_4_bingham_etal.pdf
+.. [2] AUVfest2008: Underwater mines; URL: http://oceanexplorer.noaa.gov/explorations/08auvfest/background/mines/mines.html
+.. [3] Hydroinc Products; URL: http://www.hydroidinc.com/products.html
+.. [4] WHOI, Autonomous Underwater Vehicle, REMUS; URL: http://www.whoi.edu/page.do?pid=29856
+.. [5] Eriksen, C.C., T.J. Osse, R.D. Light, T. Wen, T.W. Lehman, P.L. Sabin, J.W. Ballard, and A.M.
+ Chiodi. Seaglider: A Long-Range Autonomous Underwater Vehicle for Oceanographic Research,
+ IEEE Journal of Oceanic Engineering, 26, 4, October 2001.
+ URL: http://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=972073&userType=inst
+.. [6] L. Freitag, M. Grund, I. Singh, J. Partan, P. Koski, K. Ball, and W. Hole, The whoi
+ micro-modem: an acoustic communications and navigation system for multiple platforms,
+ In Proc. IEEE OCEANS05 Conf, 2005. URL: http://ieeexplore.ieee.org/iel5/10918/34367/01639901.pdf
+.. [7] C. M. Shepherd, "Design of Primary and Secondary Cells - Part 3.
+ Battery discharge equation," U.S. Naval Research Laboratory, 1963
+.. [8] Tremblay, O.; Dessaint, L.-A.; Dekkiche, A.-I., "A Generic Battery Model for the
+ Dynamic Simulation of Hybrid Electric Vehicles," Ecole de Technologie Superieure,
+ Universite du Quebec, 2007 URL: http://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=4544139
+.. [9] Panasonic CGR18650DA Datasheet, URL: http://www.panasonic.com/industrial/includes/pdf/Panasonic_LiIon_CGR18650DA.pdf
+.. [10] Electrochem 3B36 Datasheet, URL: http://www.electrochem.com.cn/products/Primary/HighRate/CSC/3B36.pdf
+
+Usage
+*****
+
+The main way that users who write simulation scripts will typically
+interact with the UAN Framework is through the helper API and through
+the publicly visible attributes of the model.
+
+The helper API is defined in ``src/devices/uan/helper/acoustic-modem-energy-model-helper.{cc,h}`` and in ``/src/devices/uan/auv/helper/...{cc,h}``.
+
+The example folder ``src/devices/uan/auv/examples/`` contain some basic code that shows how to set up and use the models.
+further examples can be found into the Unit tests in ``src/devices/uan/auv/test/...cc``
+
+Examples
+========
+
+Examples of the Framework's usage can be found into the examples folder. There are mobility related examples and uan related ones.
+
+Mobility Model Examples
+#######################
+
+* ``auv-energy-model``:
+ In this example we show the basic usage of an AUV energy model.
+ Specifically, we show how to create a generic node, adding to it a basic energy source
+ and consuming energy from the energy source. In this example we show the basic usage of
+ an AUV energy model.
+
+ The Seaglider AUV power consumption depends on buoyancy and vertical speed values, so we simulate a 20 seconds movement at 0.3 m/s of vertical speed and 138g of buoyancy. Then a 20 seconds movement at 0.2 m/s of vertical speed and 138g of buoyancy and then a stop of 5 seconds.
+
+ The required energy will be drained by the model basing on the given buoyancy/speed values, from the energy source installed onto the node. We finally register a callback to the TotalEnergyConsumption traced value.
+
+
+* ``auv-mobility``:
+ In this example we show how to use the AuvMobilityHelper to install an AUV mobility model into a (set of) node. Then we make the AUV to submerge to a depth of 1000 meters. We then set a callback function called on reaching of the target depth.
+ The callback then makes the AUV to emerge to water surface (0 meters). We set also a callback function called on reaching of the target depth.
+ The emerge callback then, stops the AUV.
+
+ During the whole navigation process, the AUV's position is tracked by the TracePos function and plotted into a Gnuplot graph.
+
+
+* ``waypoint-mobility``:
+ We show how to use the WaypointMobilityModel with a non-standard ConstantVelocityMobilityModel.
+ We first create a waypoint model with an underlying RemusMobilityModel setting the mobility trace with two waypoints.
+ We then create a waypoint model with an underlying GliderMobilityModel setting the waypoints separately with the AddWaypoint method.
+ The AUV's position is printed out every seconds.
+
+
+UAN Examples
+############
+
+* ``li-ion-energy-source``
+ In this simple example, we show how to create and drain energy from a LiIonEnergySource.
+ We make a series of discharge calls to the energy source class, with different current drain and durations, until all the energy is depleted from the cell (i.e. the voltage of the cell goes below the threshold level).
+ Every 20 seconds we print out the actual cell voltage to verify that it follows the discharge curve [9].
+ At the end of the example it is verified that after the energy depletion call, the cell voltage is below the threshold voltage.
+
+
+* ``uan-energy-auv``
+ This is a comprehensive example where all the project's components are used.
+ We setup two nodes, one fixed surface gateway equipped with an acoustic modem and a moving Seaglider AUV with an acoustic modem too.
+ Using the waypoint mobility model with an underlying GliderMobilityModel, we make the glider descend to -1000 meters and then emerge to the water surface.
+ The AUV sends a generic 17-bytes packet every 10 seconds during the navigation process. The gateway receives the packets and stores the total bytes amount.
+ At the end of the simulation are shown the energy consumptions of the two nodes and the networking stats.
+
+
+Helpers
+=======
+
+In this section we give an overview of the available helpers and their behaviour.
+
+
+AcousticModemEnergyModelHelper
+##############################
+
+This helper installs AcousticModemEnergyModel into UanNetDevice objects only. It requires an UanNetDevice and an EnergySource as input objects.
+
+The helper creates an AcousticModemEnergyModel with default parameters and associate it with the given energy source. It configures an EnergyModelCallback and an EnergyDepletionCallback. The depletion callback can be configured as a parameter.
+
+
+AuvGliderHelper
+###############
+
+Installs into a node (or set of nodes) the Seaglider's features:
+
+* waypoint model with underlying glider mobility model
+
+* glider energy model
+
+* glider energy source
+
+* micro modem energy model
+
+The glider mobility model is the GliderMobilityModel with default parameters.
+The glider energy model is the GliderEnergyModel with default parameters.
+
+Regarding the energy source, the Seaglider features two battery packs, one for motor power and one for digital-analog power.
+Each pack is composed of 12 (10V) and 42 (24V) lithium chloride DD-cell batteries, respectively [5]. The total power capacity is around 17.5 MJ (3.9 MJ + 13.6 MJ).
+In the original version of the Seaglider there was 18 + 63 D-cell with a total power capacity of 10MJ.
+
+The packs design is as follows:
+
+* 10V - 3 in-series string x 4 strings = 12 cells - typical capacity ~100 Ah
+
+* 24V - 7 in-series-strings x 6 strings = 42 cells - typical capacity ~150 Ah
+
+Battery cells are Electrochem 3B36, with 3.6 V nominal voltage and 30.0 Ah nominal capacity.
+The 10V battery pack is associated with the electronic devices, while the 24V one is associated with the pump motor.
+
+The micro modem energy model is the MicroModemEnergyModel with default parameters.
+
+AuvRemusHelper
+##############
+
+Install into a node (or set of nodes) the REMUS features:
+
+* waypoint model with REMUS mobility model validation
+
+* REMUS energy model
+
+* REMUS energy source
+
+* micro modem energy model
+
+The REMUS mobility model is the RemusMobilityModel with default parameters.
+The REMUS energy model is the RemusEnergyModel with default parameters.
+
+Regarding the energy source, the REMUS features a rechargeable lithium ion battery pack rated 1.1 kWh @ 27 V (40 Ah) in operating conditions (specifications from [3] and Hydroinc European salesman).
+Since more detailed information about battery pack were not publicly available, the energy source used is a BasicEnergySource.
+
+The micro modem energy model is the MicroModemEnergyModel with default parameters.
+
+
+Attributes
+==========
+
+.. note::
+
+ TODO
+
+Tracing
+=======
+
+.. note::
+
+ TODO
+
+Logging
+=======
+
+.. note::
+
+ TODO
+
+Caveats
+=======
+
+.. note::
+
+ TODO
+
+Validation
+**********
+
+This model has been tested with three UNIT test:
+
+* auv-energy-model
+* auv-mobility
+* li-ion-energy-source
+
+Auv Energy Model
+================
+
+Includes test cases for single packet energy consumption, energy depletion, Glider and REMUS energy consumption.
+The unit test can be found in ``src/devices/uan/auv/test/auv-energy-model-test.cc``.
+
+The single packet energy consumption test do the following:
+
+* creates a two node network, one surface gateway and one fixed node at -500 m of depth
+* install the acoustic communication stack with energy consuption support into the nodes
+* a packet is sent from the underwater node to the gateway
+* it is verified that both, the gateway and the fixed node, have consumed the expected amount of energy from their sources
+
+The energy depletion test do the following steps:
+
+* create a node with an empty energy source
+* try to send a packet
+* verify that the energy depletion callback has been invoked
+
+The Glider energy consumption test do the following:
+
+* create a node with glider capabilities
+* make the vehicle to move to a predetermined waypoint
+* verify that the energy consumed for the navigation is correct, according to the glider specifications
+
+The REMUS energy consumption test do the following:
+
+* create a node with REMUS capabilities
+* make the vehicle to move to a predetermined waypoint
+* verify that the energy consumed for the navigation is correct, according to the REMUS specifications
+
+
+Auv Mobility
+============
+
+Includes test cases for glider and REMUS mobility models.
+The unit test can be found in ``src/devices/uan/auv/test/auv-mobility-test.cc``.
+
+* create a node with glider capabilities
+* set a specified velocity vector and verify if the resulting buoyancy is the one that is supposed to be
+* make the vehicle to submerge to a specified depth and verify if, at the end of the process the position is the one that is supposed to be
+* make the vehicle to emerge to a specified depth and verify if, at the end of the process the position is the one that is supposed to be
+* make the vehicle to navigate to a specified point, using direction, pitch and speed settings and, verify if at the end of the process the position is the one that is supposed to be
+* make the vehicle to navigate to a specified point, using a velocity vector and, verify if at the end of the process the position is the one that is supposed to be
+
+The REMUS mobility model test do the following:
+* create a node with glider capabilities
+* make the vehicle to submerge to a specified depth and verify if, at the end of the process the position is the one that is supposed to be
+* make the vehicle to emerge to a specified depth and verify if, at the end of the process the position is the one that is supposed to be
+* make the vehicle to navigate to a specified point, using direction, pitch and speed settings and, verify if at the end of the process the position is the one that is supposed to be
+* make the vehicle to navigate to a specified point, using a velocity vector and, verify if at the end of the process the position is the one that is supposed to be
+
+Li-Ion Energy Source
+====================
+
+Includes test case for Li-Ion energy source.
+The unit test can be found in ``src/contrib/energy/test/li-ion-energy-source-test.cc``.
+
+The test case verify that after a well-known discharge time with constant current drain, the cell voltage has followed the datasheet discharge curve [9].
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/wifi.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,408 @@
+.. include:: replace.txt
+
+Wifi NetDevice
+--------------
+
+|ns3| nodes can contain a collection of NetDevice objects, much like an actual
+computer contains separate interface cards for Ethernet, Wifi, Bluetooth, etc.
+This chapter describes the |ns3| WifiNetDevice and related models. By adding
+WifiNetDevice objects to |ns3| nodes, one can create models of 802.11-based
+infrastructure and ad hoc networks.
+
+Overview of the model
+*********************
+
+The WifiNetDevice models a wireless network interface controller based
+on the IEEE 802.11 standard. We will go into more detail below but in brief,
+|ns3| provides models for these aspects of 802.11:
+
+* basic 802.11 DCF with **infrastructure** and **adhoc** modes
+* **802.11a** and **802.11b** physical layers
+* QoS-based EDCA and queueing extensions of **802.11e**
+* various propagation loss models including **Nakagami, Rayleigh, Friis,
+ LogDistance, FixedRss, Random**
+* two propagation delay models, a distance-based and random model
+* various rate control algorithms including **Aarf, Arf, Cara, Onoe, Rraa,
+ ConstantRate, and Minstrel**
+* 802.11s (mesh), described in another chapter
+
+The set of 802.11 models provided in |ns3| attempts to provide an accurate
+MAC-level implementation of the 802.11 specification and to provide a
+not-so-slow PHY-level model of the 802.11a specification.
+
+The implementation is modular and provides roughly four levels of models:
+
+* the **PHY layer models**
+* the so-called **MAC low models**: they implement DCF and EDCAF
+* the so-called **MAC high models**: they implement the MAC-level beacon
+ generation, probing, and association state machines, and
+* a set of **Rate control algorithms** used by the MAC low models
+
+There are presently six **MAC high models**, three for non-QoS MACs and three
+for QoS MACs.
+
+* **non-QoS MACs:**
+
+ #. a simple adhoc state machine that does not perform any kind of beacon
+ generation, probing, or association. This state machine is implemented by the
+ ``ns3::AdhocWifiMac`` class.
+ #. an active probing and association state machine that handles automatic
+ re-association whenever too many beacons are missed is implemented by the
+ ``ns3::NqstaWifiMac`` class.
+ #. an access point that generates periodic beacons, and that accepts every
+ attempt to associate. This AP state machine is implemented by the
+ ``ns3::NqapWifiMac`` class.
+
+* **QoS MACs:**
+
+ #. a simple adhoc state machine like above but also able to manage QoS traffic.
+ This state machine is implemented by :cpp:class:`ns3::QadhocWifiMac` class.
+ #. a station state machine like above but also able to manage QoS traffic.
+ Implemented by ``ns3::QstaWifiMac``.
+ #. a QoS access point state machine like above implemented by ``ns3::QapWifiMac``.
+
+With QoS MAC models is possible to work with traffic belonging to four different
+access classes: **AC_VO** for voice traffic, **AC_VI** for video traffic,
+**AC_BE** for best-effort traffic and **AC_BK** for background traffic. In
+order to determine MSDU's access class, every packet forwarded down to these MAC
+layers should be marked using ``ns3::QosTag`` in order to set a TID (traffic id)
+for that packet otherwise it will be considered belonging to **AC_BE** access
+class.
+
+The **MAC low layer** is split into three components:
+
+#. ``ns3::MacLow`` which takes care of RTS/CTS/DATA/ACK transactions.
+#. ``ns3::DcfManager`` and ``ns3::DcfState`` which implements the DCF and EDCAF
+ functions.
+#. ``ns3::DcaTxop`` or ``ns3::EdcaTxopN`` which handle the packet queue,
+ packet fragmentation, and packet retransmissions if they are needed.
+ ``ns3::DcaTxop`` object is used by non-QoS high MACs. ``ns3::EdcaTxopN`` is
+ used by QoS high MACs and performs also QoS operations like 802.11n MSDU
+ aggregation.
+
+There are also several **rate control algorithms** that can be used by the Mac low layer:
+
+* ``ns3::ArfMacStations``
+* ``ns3::AArfMacStations``
+* ``ns3::IdealMacStations``
+* ``ns3::CrMacStations``
+* ``ns3::OnoeMacStations``
+* ``ns3::AmrrMacStations``
+
+The PHY layer implements a single model in the ``ns3::WifiPhy class``: the
+physical layer model implemented there is described fully in a paper entitled
+`Yet Another Network Simulator <http://cutebugs.net/files/wns2-yans.pdf>`_
+Validation results for 802.11b are available in this
+`technical report <http://www.nsnam.org/~pei/80211b.pdf>`_
+
+In |ns3|, nodes can have multiple WifiNetDevices on separate channels, and the
+WifiNetDevice can coexist with other device types; this removes an architectural
+limitation found in ns-2. Presently, however, there is no model for
+cross-channel interference or coupling.
+
+The source code for the Wifi NetDevice lives in the directory
+``src/devices/wifi``.
+
+.. _wifi-architecture:
+
+.. figure:: figures/WifiArchitecture.*
+
+ Wifi NetDevice architecture.
+
+Using the WifiNetDevice
+***********************
+
+The modularity provided by the implementation makes low-level configuration of
+the WifiNetDevice powerful but complex. For this reason, we provide some helper
+classes to perform common operations in a simple matter, and leverage the |ns3|
+attribute system to allow users to control the parametrization of the underlying
+models.
+
+Users who use the low-level |ns3| API and who wish to add a WifiNetDevice to
+their node must create an instance of a WifiNetDevice, plus a number of
+constituent objects, and bind them together appropriately (the WifiNetDevice is
+very modular in this regard, for future extensibility). At the low-level API,
+this can be done with about 20 lines of code (see ``ns3::WifiHelper::Install``,
+and ``ns3::YansWifiPhyHelper::Create``). They also must create, at some point, a
+WifiChannel, which also contains a number of constituent objects (see
+``ns3::YansWifiChannelHelper::Create``).
+
+However, a few helpers are available for users to add these devices and channels
+with only a few lines of code, if they are willing to use defaults, and the
+helpers provide additional API to allow the passing of attribute values to
+change default values. The scripts in ``src/examples`` can be browsed to see how
+this is done.
+
+YansWifiChannelHelper
++++++++++++++++++++++
+
+The YansWifiChannelHelper has an unusual name. Readers may wonder why it is
+named this way. The reference is to the `yans simulator
+<http://cutebugs.net/files/wns2-yans.pdf>`_ from which this model is taken. The
+helper can be used to create a WifiChannel with a default PropagationLoss and
+PropagationDelay model. Specifically, the default is a channel model with a
+propagation delay equal to a constant, the speed of light, and a propagation
+loss based on a log distance model with a reference loss of 46.6777 dB at
+reference distance of 1m.
+
+Users will typically type code such as:::
+
+ YansWifiChannelHelper wifiChannelHelper = YansWifiChannelHelper::Default ();
+ Ptr<WifiChannel> wifiChannel = wifiChannelHelper.Create ();
+
+to get the defaults. Note the distinction above in creating a helper object vs.
+an actual simulation object. In |ns3|, helper objects (used at the helper API
+only) are created on the stack (they could also be created with operator new and
+later deleted). However, the actual |ns3| objects typically inherit from
+``class ns3::Object`` and are assigned to a smart pointer. See the chapter on
+:ref:`Object model` for a discussion of the |ns3| object model, if you are not
+familiar with it.
+
+*Todo: Add notes about how to configure attributes with this helper API*
+
+YansWifiPhyHelper
++++++++++++++++++
+
+Physical devices (base class ``ns3::Phy``) connect to ``ns3::Channel`` models in
+|ns3|. We need to create Phy objects appropriate for the YansWifiChannel; here
+the ``YansWifiPhyHelper`` will do the work.
+
+The YansWifiPhyHelper class configures an object factory to create instances of
+a ``YansWifiPhy`` and adds some other objects to it, including possibly a
+supplemental ErrorRateModel and a pointer to a MobilityModel. The user code is
+typically:::
+
+ YansWifiPhyHelper wifiPhyHelper = YansWifiPhyHelper::Default ();
+ wifiPhyHelper.SetChannel (wifiChannel);
+
+Note that we haven't actually created any WifiPhy objects yet; we've just
+prepared the YansWifiPhyHelper by telling it which channel it is connected to.
+The phy objects are created in the next step.
+
+NqosWifiMacHelper and QosWifiMacHelper
+++++++++++++++++++++++++++++++++++++++
+
+The ``ns3::NqosWifiMacHelper`` and ``ns3::QosWifiMacHelper`` configure an
+object factory to create instances of a ``ns3::WifiMac``. They are used to
+configure MAC parameters like type of MAC. Setting up a non-QoS MAC layers the
+object we use is ``ns3::NqosWifiMacHelper``. For example the following user
+code configures a non-QoS MAC sta:::
+
+ NqosWifiMacHelper wifiMacHelper = NqosWifiMacHelper::Default ();
+ Ssid ssid = Ssid ("ns-3-ssid");
+ wifiMacHelper.SetType ("ns3::NqstaWifiMac", "Ssid", SsidValue (ssid),
+ "ActiveProbing", BooleanValue (false));
+
+Setting up a QoS MACs we use a ``ns3::QosWifiMacHelper`` instead.
+This object could be also used to set:
+
+* a MSDU aggregator for a particular access class in order to use 802.11n MSDU
+ aggregation feature;
+* block ack parameters like threshold (number of packets for which block ack
+ mechanism should be used) and inactivity timeout.
+
+A possible user code:::
+
+ QosWifiMacHelper wifiMacHelper = QosWifiMacHelper::Default ();
+ wifiMacHelper.SetType ("ns3::QapWifiMac",
+ "Ssid", SsidValue (ssid),
+ "BeaconGeneration", BooleanValue (true),
+ "BeaconInterval", TimeValue (Seconds (2.5)));
+ wifiMacHelper.SetMsduAggregatorForAc (AC_VO, "ns3::MsduStandardAggregator",
+ "MaxAmsduSize", UintegerValue (3839));
+ wifiMacHelper.SetBlockAckThresholdForAc (AC_BE, 10);
+ wifiMacHelper.SetBlockAckInactivityTimeoutForAc (AC_BE, 5);
+
+WifiHelper
+++++++++++
+
+We're now ready to create WifiNetDevices. First, let's create
+a WifiHelper with default settings:::
+
+ WifiHelper wifiHelper = WifiHelper::Default ();
+
+What does this do? It sets the RemoteStationManager to
+``ns3::ArfWifiManager``.
+Now, let's use the wifiPhyHelper and wifiMacHelper created above to install WifiNetDevices
+on a set of nodes in a NodeContainer "c":::
+
+ NetDeviceContainer wifiContainer = WifiHelper::Install (wifiPhyHelper, wifiMacHelper, c);
+
+This creates the WifiNetDevice which includes also a WifiRemoteStationManager, a
+WifiMac, and a WifiPhy (connected to the matching WifiChannel).
+
+There are many |ns3| :ref:`Attributes` that can be set on the above helpers to
+deviate from the default behavior; the example scripts show how to do some of
+this reconfiguration.
+
+AdHoc WifiNetDevice configuration
++++++++++++++++++++++++++++++++++
+
+This is a typical example of how a user might configure an adhoc network.
+
+*To be completed*
+
+Infrastructure (Access Point and clients) WifiNetDevice configuration
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+This is a typical example of how a user might configure an access point and a
+set of clients.
+
+*To be completed*
+
+The WifiChannel and WifiPhy models
+**********************************
+
+The WifiChannel subclass can be used to connect together a set of
+``ns3::WifiNetDevice`` network interfaces. The class ``ns3::WifiPhy`` is the
+object within the WifiNetDevice that receives bits from the channel. A
+WifiChannel contains a ``ns3::PropagationLossModel`` and a
+``ns3::PropagationDelayModel`` which can be overridden by the
+WifiChannel::SetPropagationLossModel and the
+WifiChannel::SetPropagationDelayModel methods. By default, no propagation models
+are set.
+
+The WifiPhy models an 802.11a channel, in terms of frequency, modulation, and
+bit rates, and interacts with the PropagationLossModel and PropagationDelayModel
+found in the channel.
+
+This section summarizes the description of the BER calculations found in the
+yans paper taking into account the Forward Error Correction present in 802.11a
+and describes the algorithm we implemented to decide whether or not a packet can
+be successfully received. See `"Yet Another Network Simulator"
+<http://cutebugs.net/files/wns2-yans.pdf>`_ for more details.
+
+The PHY layer can be in one of three states:
+
+#. TX: the PHY is currently transmitting a signal on behalf of its associated
+ MAC
+#. RX: the PHY is synchronized on a signal and is waiting until it has received
+ its last bit to forward it to the MAC.
+#. IDLE: the PHY is not in the TX or RX states.
+
+When the first bit of a new packet is received while the PHY is not IDLE (that
+is, it is already synchronized on the reception of another earlier packet or it
+is sending data itself), the received packet is dropped. Otherwise, if the PHY
+is IDLE, we calculate the received energy of the first bit of this new signal
+and compare it against our Energy Detection threshold (as defined by the Clear
+Channel Assessment function mode 1). If the energy of the packet k is higher,
+then the PHY moves to RX state and schedules an event when the last bit of the
+packet is expected to be received. Otherwise, the PHY stays in IDLE state and
+drops the packet.
+
+The energy of the received signal is assumed to be zero outside of the reception
+interval of packet k and is calculated from the transmission power with a
+path-loss propagation model in the reception interval. where the path loss
+exponent, :math:`n`, is chosen equal to :math:`3`, the reference distance,
+:math:`d_0` is choosen equal to :math:`1.0m` and the reference energy is based
+based on a Friis propagation model.
+
+When the last bit of the packet upon which the PHY is synchronized is received,
+we need to calculate the probability that the packet is received with any error
+to decide whether or not the packet on which we were synchronized could be
+successfully received or not: a random number is drawn from a uniform
+distribution and is compared against the probability of error.
+
+To evaluate the probability of error, we start from the piecewise linear
+functions shown in Figure @ref{fig:snir} and calculate the
+SNIR function.
+
+.. _snir:
+
+.. figure:: figures/snir.*
+
+ SNIR function over time.
+
+From the SNIR function we can derive bit error rates for BPSK and QAM
+modulations. Then, for each interval l where BER is constant, we define the
+upper bound of a probability that an error is present in the chunk of bits
+located in the interval l for packet k. If we assume an AWGN channel, binary
+convolutional coding (which is the case in 802.11a) and hard-decision Viterbi
+decoding, the error rate is thus derived, and the packet error probability for
+packet k can be computed.
+
+WifiChannel configuration
++++++++++++++++++++++++++
+
+WifiChannel models include both a PropagationDelayModel and a
+PropagationLossModel. The following PropagationDelayModels are available:
+
+* ConstantSpeedPropagationDelayModel
+* RandomPropagationDelayModel
+
+The following PropagationLossModels are available:
+
+* RandomPropagationLossModel
+* FriisPropagationLossModel
+* LogDistancePropagationLossModel
+* JakesPropagationLossModel
+* CompositePropagationLossModel
+
+The MAC model
+*************
+
+The 802.11 Distributed Coordination Function is used to calculate when to grant
+access to the transmission medium. While implementing the DCF would have been
+particularly easy if we had used a recurring timer that expired every slot, we
+chose to use the method described in *(missing reference here from Yans paper)*
+where the backoff timer duration is lazily calculated whenever needed since it
+is claimed to have much better performance than the simpler recurring timer
+solution.
+
+The higher-level MAC functions are implemented in a set of other C++ classes and
+deal with:
+
+* packet fragmentation and defragmentation,
+* use of the rts/cts protocol,
+* rate control algorithm,
+* connection and disconnection to and from an Access Point,
+* the MAC transmission queue,
+* beacon generation,
+* msdu aggregation,
+* etc.
+
+Wifi Attributes
+***************
+
+The WifiNetDevice makes heavy use of the |ns3| :ref:`Attributes` subsystem for
+configuration and default value management. Presently, approximately 100 values
+are stored in this system.
+
+For instance, class ``ns-3::WifiMac`` exports these attributes:
+
+* CtsTimeout: When this timeout expires, the RTS/CTS handshake has failed.
+* AckTimeout: When this timeout expires, the DATA/ACK handshake has failed.
+* Sifs: The value of the SIFS constant.
+* EifsNoDifs: The value of EIFS-DIFS
+* Slot: The duration of a Slot.
+* Pifs: The value of the PIFS constant.
+* MaxPropagationDelay: The maximum propagation delay. Unused for now.
+* MaxMsduSize: The maximum size of an MSDU accepted by the MAC layer.This value
+ conforms to the specification.
+* Ssid: The ssid we want to belong to.
+
+Wifi Tracing
+************
+
+*This needs revised/updating based on the latest Doxygen*
+
+|ns3| has a sophisticated tracing infrastructure that allows users to hook into
+existing trace sources, or to define and export new ones.
+
+Wifi-related trace sources that are available by default include:::
+
+* ``ns3::WifiNetDevice``
+
+ * Rx: Received payload from the MAC layer.
+ * Tx: Send payload to the MAC layer.
+
+* ``ns3::WifiPhy``
+
+ * State: The WifiPhy state
+ * RxOk: A packet has been received successfully.
+ * RxError: A packet has been received unsuccessfully.
+ * Tx: Packet transmission is starting.
+
+Briefly, this means, for example, that a user can hook a processing function to
+the "State" tracing hook above and be notified whenever the WifiPhy model
+changes state.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/wimax.rst Thu Dec 30 23:39:27 2010 +0100
@@ -0,0 +1,510 @@
+.. include:: replace.txt
+
+Wimax NetDevice
+---------------
+
+This chapter describes the |ns3| WimaxNetDevice and related models. By
+adding WimaxNetDevice objects to |ns3| nodes, one can create models of
+802.16-based networks. Below, we list some more details about what
+the |ns3| WiMAX models cover but, in summary, the most important features
+of the |ns3| model are:
+
+* a scalable and realistic physical layer and channel model
+* a packet classifier for the IP convergence sublayer
+* efficient uplink and downlink schedulers
+* support for Multicast and Broadcast Service (MBS), and
+* packet tracing functionality
+
+The source code for the WiMAX models lives in the directory
+``src/devices/wimax``.
+
+There have been two academic papers published on this model:
+
+* M.A. Ismail, G. Piro, L.A. Grieco, and T. Turletti, "An Improved IEEE 802.16
+ WiMAX Module for the NS-3 Simulator", SIMUTools 2010 Conference, March 2010.
+* J. Farooq and T. Turletti, "An IEEE 802.16 WiMAX module for the NS-3
+ Simulator," SIMUTools 2009 Conference, March 2009.
+
+
+Scope of the model
+******************
+
+From a MAC perspective, there are two basic modes of operation, that of a
+Subscriber Station (SS) or a Base Station (BS). These are implemented as two
+subclasses of the base class :cpp:class:`ns3::NetDevice`, class
+:cpp:class:`SubscriberStationNetDevice` and class
+:cpp:class:`BaseStationNetDevice`. As is typical in |ns3|, there is also a
+physical layer class :cpp:class:`WimaxPhy` and a channel class
+:cpp:class:`WimaxChannel` which serves to hold the references to all of the
+attached Phy devices. The main physical layer class is the
+:cpp:class:`SimpleOfdmWimaxChannel` class.
+
+Another important aspect of WiMAX is the uplink and downlink scheduler, and
+there are three primary scheduler types implemented:
+
+* SIMPLE: a simple priority based FCFS scheduler
+* RTPS: a real-time polling service (rtPS) scheduler
+* MBQOS: a migration-based uplink scheduler
+
+The following additional aspects of the 802.16 specifications, as well as
+physical layer and channel models, are modelled:
+
+* leverages existing |ns3| wireless propagation loss and delay models, as well
+ as |ns3| mobility models
+* Point-to-Multipoint (PMP) mode and the WirelessMAN-OFDM PHY layer
+* Initial Ranging
+* Service Flow Initialization
+* Management Connection
+* Transport Initialization
+* UGS, rtPS, nrtPS, and BE connections
+
+The following aspects are not presently modelled but would be good topics for
+future extensions:
+
+* OFDMA PHY layer
+* Link adaptation
+* Mesh topologies
+* ARQ
+* ertPS connection
+* packet header suppression
+
+Using the Wimax models
+**********************
+
+The main way that users who write simulation scripts will typically interact
+with the Wimax models is through the helper API and through the publicly visible
+attributes of the model.
+
+The helper API is defined in ``src/helper/wimax-helper.{cc,h}``.
+
+The example ``examples/wimax/wimax-simple.cc`` contains some basic code that
+shows how to set up the model:::
+
+ switch (schedType)
+ {
+ case 0:
+ scheduler = WimaxHelper::SCHED_TYPE_SIMPLE;
+ break;
+ case 1:
+ scheduler = WimaxHelper::SCHED_TYPE_MBQOS;
+ break;
+ case 2:
+ scheduler = WimaxHelper::SCHED_TYPE_RTPS;
+ break;
+ default:
+ scheduler = WimaxHelper::SCHED_TYPE_SIMPLE;
+ }
+
+ NodeContainer ssNodes;
+ NodeContainer bsNodes;
+
+ ssNodes.Create (2);
+ bsNodes.Create (1);
+
+ WimaxHelper wimax;
+
+ NetDeviceContainer ssDevs, bsDevs;
+
+ ssDevs = wimax.Install (ssNodes,
+ WimaxHelper::DEVICE_TYPE_SUBSCRIBER_STATION,
+ WimaxHelper::SIMPLE_PHY_TYPE_OFDM,
+ scheduler);
+ bsDevs = wimax.Install (bsNodes, WimaxHelper::DEVICE_TYPE_BASE_STATION, WimaxHelper::SIMPLE_PHY_TYPE_OFDM, scheduler);
+
+This example shows that there are two subscriber stations and one base station
+created. The helper method ``Install`` allows the user to specify the scheduler
+type, the physical layer type, and the device type.
+
+Different variants of ``Install`` are available; for instance, the example
+``examples/wimax/wimax-multicast.cc`` shows how to specify a non-default channel
+or propagation model:::
+
+ channel = CreateObject<SimpleOfdmWimaxChannel> ();
+ channel->SetPropagationModel (SimpleOfdmWimaxChannel::COST231_PROPAGATION);
+ ssDevs = wimax.Install (ssNodes,
+ WimaxHelper::DEVICE_TYPE_SUBSCRIBER_STATION,
+ WimaxHelper::SIMPLE_PHY_TYPE_OFDM,
+ channel,
+ scheduler);
+ Ptr<WimaxNetDevice> dev = wimax.Install (bsNodes.Get (0),
+ WimaxHelper::DEVICE_TYPE_BASE_STATION,
+ WimaxHelper::SIMPLE_PHY_TYPE_OFDM,
+ channel,
+ scheduler);
+
+Mobility is also supported in the same way as in Wifi models; see the
+``examples/wimax/wimax-multicast.cc``.
+
+Another important concept in WiMAX is that of a service flow. This is a
+unidirectional flow of packets with a set of QoS parameters such as traffic
+priority, rate, scheduling type, etc. The base station is responsible for
+issuing service flow identifiers and mapping them to WiMAX connections. The
+following code from ``examples/wimax/wimax-multicast.cc`` shows how this is
+configured from a helper level:::
+
+ ServiceFlow MulticastServiceFlow = wimax.CreateServiceFlow (ServiceFlow::SF_DIRECTION_DOWN,
+ ServiceFlow::SF_TYPE_UGS,
+ MulticastClassifier);
+
+ bs->GetServiceFlowManager ()->AddMulticastServiceFlow (MulticastServiceFlow, WimaxPhy::MODULATION_TYPE_QPSK_12);
+
+
+Wimax Attributes
+****************
+
+The WimaxNetDevice makes heavy use of the |ns3| :ref:`Attributes` subsystem for
+configuration and default value management. Presently, approximately 60 values
+are stored in this system.
+
+For instance, class :cpp:class:`ns-3::SimpleOfdmWimaxPhy` exports these
+attributes:
+
+* NoiseFigure: Loss (dB) in the Signal-to-Noise-Ratio due to non-idealities in the receiver.
+* TxPower: Transmission power (dB)
+* G: The ratio of CP time to useful time
+* txGain: Transmission gain (dB)
+* RxGain: Reception gain (dB)
+* Nfft: FFT size
+* TraceFilePath: Path to the directory containing SNR to block error rate files
+
+
+For a full list of attributes in these models, consult the Doxygen page that
+lists all attributes for |ns3|.
+
+Wimax Tracing
+*************
+
+|ns3| has a sophisticated tracing infrastructure that allows users to hook into
+existing trace sources, or to define and export new ones.
+
+Many |ns3| users use the built-in Pcap or Ascii tracing, and the
+WimaxHelper has similar APIs:::
+
+ AsciiTraceHelper ascii;
+ WimaxHelper wimax;
+ wimax.EnablePcap ("wimax-program", false);
+ wimax.EnableAsciiAll (ascii.CreateFileStream ("wimax-program.tr");
+
+Unlike other helpers, there is also a special ``EnableAsciiForConnection()``
+method that limits the ascii tracing to a specific device and connection.
+
+These helpers access the low level trace sources that exist in the WiMAX
+physical layer, net device, and queue models. Like other |ns3| trace sources,
+users may hook their own functions to these trace sources if they want to do
+customized things based on the packet events. See the Doxygen List of trace
+sources for a complete list of these sources.
+
+Wimax MAC model
+***************
+
+The 802.16 model provided in |ns3| attempts to provide an accurate MAC and PHY
+level implementation of the 802.16 specification with the Point-to-Multipoint
+(PMP) mode and the WirelessMAN-OFDM PHY layer. The model is mainly composed of
+three layers:
+
+* The convergence sublayer (CS)
+* The MAC CP Common Part Sublayer (MAC-CPS)
+* Physical (PHY) layer
+
+
+The following figure :ref:`WimaxArchitecture` shows the relationships of these
+models.
+
+.. _wimax-architecture:
+
+.. figure:: figures/WimaxArchitecture.*
+
+ WiMAX architecture.
+
+the Convergence Sublayer ++++++++++++++++++++++++
+
+The Convergence sublayer (CS) provided with this module implements the Packet
+CS, designed to work with the packet-based protocols at higher layers. The CS is
+responsible of receiving packet from the higher layer and from peer stations,
+classifying packets to appropriate connections (or service flows) and processing
+packets. It keeps a mapping of transport connections to service flows. This
+enables the MAC CPS identifying the Quality of Service (QoS) parameters
+associated to a transport connection and ensuring the QoS requirements. The CS
+currently employs an IP classifier.
+
+IP Packet Classifier ++++++++++++++++++++
+
+An IP packet classifier is used to map incoming packets to appropriate
+connections based on a set of criteria. The classifier maintains a list of
+mapping rules which associate an IP flow (src IP address and mask, dst IP
+address and mask, src port range, dst port range and protocol) to one of the
+service flows. By analyzing the IP and the TCP/UDP headers the classifier will
+append the incoming packet (from the upper layer) to the queue of the
+appropriate WiMAX connection. Class :cpp:class:`IpcsClassifier` and class
+:cpp:class:`IpcsClassifierRecord` implement the classifier module for both SS
+and BS
+
+@subsection MAC Common Part Sublayer
+
+The MAC Common Part Sublayer (CPS) is the main sublayer of the IEEE 802.16 MAC
+and performs the fundamental functions of the MAC. The module implements the
+Point-Multi-Point (PMP) mode. In PMP mode BS is responsible of managing
+communication among multiple SSs. The key functionalities of the MAC CPS include
+framing and addressing, generation of MAC management messages, SS initialization
+and registration, service flow management, bandwidth management and scheduling
+services. Class :cpp:class:`WimaxNetDevice` represents the MAC layer of a WiMAX
+network device. This class extends the class :cpp:class:`NetDevice` of the |ns3|
+API that provides abstraction of a network device. Class
+:cpp:class:`WimaxNetDevice` is further extended by class
+:cpp:class:`BaseStationNetDevice` and class
+:cpp:class:`SubscriberStationNetDevice`, defining MAC layers of BS and SS,
+respectively. Besides these main classes, the key functions of MAC are
+distributed to several other classes.
+
+Framing and Management Messages
++++++++++++++++++++++++++++++++
+
+The module implements a frame as a fixed duration of time, i.e., frame
+boundaries are defined with respect to time. Each frame is further subdivided
+into downlink (DL) and uplink (UL) subframes. The module implements the Time
+Division Duplex (TDD) mode where DL and UL operate on same frequency but are
+separated in time. A number of DL and UL bursts are then allocated in DL and UL
+subframes, respectively. Since the standard allows sending and receiving bursts
+of packets in a given DL or UL burst, the unit of transmission at the MAC layer
+is a packet burst. The module implements a special PacketBurst data structure
+for this purpose. A packet burst is essentially a list of packets. The BS
+downlink and uplink schedulers, implemented by class :cpp:class:`BSScheduler`
+and class :cpp:class:`UplinkScheduler`, are responsible of generating DL and UL
+subframes, respectively. In the case of DL, the subframe is simulated by
+transmitting consecutive bursts (instances PacketBurst). In case of UL, the
+subframe is divided, with respect to time, into a number of slots. The bursts
+transmitted by the SSs in these slots are then aligned to slot boundaries. The
+frame is divided into integer number of symbols and Physical Slots (PS) which
+helps in managing bandwidth more effectively. The number of symbols per frame
+depends on the underlying implementation of the PHY layer. The size of a DL or
+UL burst is specified in units of symbols.
+
+Network Entry and Initialization
+++++++++++++++++++++++++++++++++
+
+The network entry and initialization phase is basically divided into two
+sub-phases, (1) scanning and synchronization and (2) initial ranging. The entire
+phase is performed by the LinkManager component of SS and BS. Once an SS wants
+to join the network, it first scans the downlink frequencies to search for a
+suitable channel. The search is complete as soon as it detects a PHY frame. The
+next step is to establish synchronization with the BS. Once SS receives a
+Downlink-MAP (DL-MAP) message the synchronization phase is complete and it
+remains synchronized as long as it keeps receiving DL-MAP and Downlink Channel
+Descriptor (DCD) messages. After the synchronization is established, SS waits
+for a Uplink Channel Descriptor (UCD) message to acquire uplink channel
+parameters. Once acquired, the first sub-phase of the network entry and
+initialization is complete. Once synchronization is achieved, the SS waits for a
+UL-MAP message to locate a special grant, called initial ranging interval, in
+the UL subframe. This grant is allocated by the BS Uplink Scheduler at regular
+intervals. Currently this interval is set to 0.5 ms, however the user is enabled
+to modify its value from the simulation script.
+
+Connections and Addressing
+++++++++++++++++++++++++++
+
+All communication at the MAC layer is carried in terms of connections. The
+standard defines a connection as a unidirectional mapping between the SS and
+BS's MAC entities for the transmission of traffic. The standard defines two
+types of connections: management connections for transmitting control messages
+and transport connections for data transmission. A connection is identified by a
+16-bit Connection Identifier (CID). Class :cpp:class:`WimaxConnection` and
+class :cpp:class:`Cid` implement the connection and CID, respectively. Note that
+each connection maintains its own transmission queue where packets to transmit
+on that connection are queued. The ConnectionManager component of BS is
+responsible of creating and managing connections for all SSs.
+
+The two key management connections defined by the standard, namely the Basic and
+Primary management connections, are created and allocated to the SS during the
+ranging process. Basic connection plays an important role throughout the
+operation of SS also because all (unicast) DL and UL grants are directed towards
+SS's Basic CID. In addition to management connections, an SS may have one or
+more transport connections to send data packets. The Connection Manager
+component of SS manages the connections associated to SS. As defined by the
+standard, a management connection is bidirectional, i.e., a pair of downlink and
+uplink connections is represented by the same CID. This feature is implemented
+in a way that one connection (in DL direction) is created by the BS and upon
+receiving the CID the SS then creates an identical connection (in UL direction)
+with the same CID.
+
+Scheduling Services
++++++++++++++++++++
+
+The module supports the four scheduling services defined by the 802.16-2004
+standard:
+
+* Unsolicited Grant Service (UGS)
+* Real-Time Polling Services (rtPS)
+* Non Real-Time Polling Services (nrtPS)
+* Best Effort (BE)
+
+These scheduling services behave differently with respect to how they request
+bandwidth as well as how the it is granted. Each service flow is associated to
+exactly one scheduling service, and the QoS parameter set associated to a
+service flow actually defines the scheduling service it belongs to. When a
+service flow is created the UplinkScheduler calculates necessary parameters such
+as grant size and grant interval based on QoS parameters associated to it.
+
+WiMAX Uplink Scheduler Model
+++++++++++++++++++++++++++++
+
+Uplink Scheduler at the BS decides which of the SSs will be assigned uplink
+allocations based on the QoS parameters associated to a service flow (or
+scheduling service) and bandwidth requests from the SSs. Uplink scheduler
+together with Bandwidth Manager implements the complete scheduling service
+functionality. The standard defines up to four scheduling services (BE, UGS,
+rtPS, nrtPS) for applications with different types of QoS requirements. The
+service flows of these scheduling services behave differently with respect to
+how they request for bandwidth as well as how the bandwidth is granted. The
+module supports all four scheduling services. Each service flow is associated to
+exactly one transport connection and one scheduling service. The QoS parameters
+associated to a service flow actually define the scheduling service it belongs
+to. Standard QoS parameters for UGS, rtPS, nrtPS and BE services, as specified
+in Tables 111a to 111d of the 802.16e amendment, are supported. When a service
+flow is created the uplink scheduler calculates necessary parameters such as
+grant size and allocation interval based on QoS parameters associated to it.
+The current WiMAX module provides three different versions of schedulers.
+
+* The first one is a simple priority-based First Come First Serve (FCFS). For
+ the real-time services (UGS and rtPS) the BS then allocates grants/polls on
+ regular basis based on the calculated interval. For the non real-time services
+ (nrtPS and BE) only minimum reserved bandwidth is guaranteed if available
+ after servicing real-time flows. Note that not all of these parameters are
+ utilized by the uplink scheduler. Also note that currently only service flow
+ with fixed-size packet size are supported, as currently set up in simulation
+ scenario with OnOff application of fixed packet size. This scheduler is
+ implemented by class :cpp:class:`BSSchedulerSimple` and class
+ :cpp:class:`UplinkSchedulerSimple`.
+
+* The second one is similar to first scheduler except by rtPS service flow. All
+ rtPS Connections are able to transmit all packet in the queue according to the
+ available bandwidth. The bandwidth saturation control has been implemented to
+ redistribute the effective available bandwidth to all rtPS that have at least
+ one packet to transmit. The remaining bandwidth is allocated to nrtPS and BE
+ Connections. This scheduler is implemented by class
+ :cpp:class:`BSSchedulerRtps` and class
+ :cpp:class:`UplinkSchedulerRtps`.
+
+* The third one is a Migration-based Quality of Service uplink scheduler This
+ uplink scheduler uses three queues, the low priority queue, the intermediate
+ queue and the high priority queue. The scheduler serves the requests in
+ strict priority order from the high priority queue to the low priority queue.
+ The low priority queue stores the bandwidth requests of the BE service flow.
+ The intermediate queue holds bandwidth requests sent by rtPS and by nrtPS
+ connections. rtPS and nrtPS requests can migrate to the high priority queue to
+ guarantee that their QoS requirements are met. Besides the requests migrated
+ from the intermediate queue, the high priority queue stores periodic grants
+ and unicast request opportunities that must be scheduled in the following
+ frame. To guarantee the maximum delay requirement, the BS assigns a deadline
+ to each rtPS bandwidth request in the intermediate queue. The minimum
+ bandwidth requirement of both rtPS and nrtPS connections is guaranteed over a
+ window of duration T. This scheduler is implemented by class
+ :cpp:class:`UplinkSchedulerMBQoS`.
+
+WiMAX Outbound Schedulers Model
++++++++++++++++++++++++++++++++
+
+Besides the uplink scheduler these are the outbound schedulers at BS and SS side
+(BSScheduler and SSScheduler). The outbound schedulers decide which of the
+packets from the outbound queues will be transmitted in a given allocation. The
+outbound scheduler at the BS schedules the downlink traffic, i.e., packets to be
+transmitted to the SSs in the downlink subframe. Similarly the outbound
+scheduler at a SS schedules the packet to be transmitted in the uplink
+allocation assigned to that SS in the uplink subframe. All three schedulers have
+been implemented to work as FCFS scheduler, as they allocate grants starting
+from highest priority scheduling service to the lower priority one (UGS> rtPS>
+nrtPS> BE). The standard does not suggest any scheduling algorithm and instead
+leaves this decision up to the manufacturers. Of course more sophisticated
+algorithms can be added later if required.
+
+WimaxChannel and WimaxPhy models
+********************************
+
+The module implements the Wireless MAN OFDM PHY specifications as the more
+relevant for implementation as it is the schema chosen by the WiMAX Forum. This
+specification is designed for non-light-of-sight (NLOS) including fixed and
+mobile broadband wireless access. The proposed model uses a 256 FFT processor,
+with 192 data subcarriers. It supports all the seven modulation and coding
+schemes specified by Wireless MAN-OFDM. It is composed of two parts: the channel
+model and the physical model.
+
+Channel model
+*************
+
+The channel model we propose is implemented by the class
+:cpp:class:`SimpleOFDMWimaxChannel` which extends the class
+:cpp:class:`wimaxchannel`. The channel entity has a private structure named
+m_phyList which handles all the physical devices connected to it. When a
+physical device sends a packet (FEC Block) to the channel, the channel handles
+the packet, and then for each physical device connected to it, it calculates the
+propagation delay, the path loss according to a given propagation model and
+eventually forwards the packet to the receiver device. The channel class uses
+the method `GetDistanceFrom()` to calculate the distance between two physical
+entities according to their 3D coordinates. The delay is
+computed as `delay = distance/C`, where `C` is the speed of the light.
+
+Physical model
+**************
+
+The physical layer performs two main operations: (i) It receives a burst from a
+channel and forwards it to the MAC layer, (ii) it receives a burst from the MAC
+layer and transmits it on the channel. In order to reduce the simulation
+complexity of the WiMAX physical layer, we have chosen to model offline part of
+the physical layer. More specifically we have developed an OFDM simulator to
+generate trace files used by the reception process to evaluate if a FEC block
+can be correctly decoded or not.
+
+Transmission Process: A burst is a set of WiMAX MAC PDUs. At the sending
+process, a burst is converted into bit-streams and then splitted into smaller
+FEC blocks which are then sent to the channel with a power equal P_tx.
+
+Reception Process: The reception process includes the following operations:
+
+#. Receive a FEC block from the channel.
+#. Calculate the noise level.
+#. Estimate the signal to noise ratio (SNR) with the following formula.
+#. Determine if a FEC block can be correctly decoded.
+#. Concatenate received FEC blocks to reconstruct the original burst.
+#. Forward the burst to the upper layer.
+
+The developed process to evaluate if a FEC block can be correctly received or
+not uses pre-generated traces. The trace files are generated by an external
+OFDM simulator (described later). A class named SNRToBlockErrorRateManager
+handles a repository containing seven trace files (one for each modulation and
+coding scheme). A repository is specific for a particular channel model.
+
+A trace file is made of 6 columns. The first column provides the SNR value (1),
+whereas the other columns give respectively the bit error rate BER (2), the
+block error rate BlcER(3), the standard deviation on BlcER, and the confidence
+interval (4 and 5). These trace files are loaded into memory by the
+SNRToBlockErrorRateManager entity at the beginning of the simulation.
+
+Currently, The first process uses the first and third columns to determine if a
+FEC block is correctly received. When the physical layer receives a packet with
+an SNR equal to SNR_rx, it asks the SNRToBlockErrorRateManager to return the
+corresponding block error rate BlcER. A random number RAND between 0 and 1 is
+then generated. If RAND is greater than BlcER, then the block is correctly
+received, otherwise the block is considered erroneous and is ignored.
+
+The module provides defaults SNR to block error rate traces in default-traces.h.
+The traces have been generated by an External WiMAX OFDM simulator. The
+simulator is based on an external mathematics and signal processing library IT++
+and includes : a random block generator, a Reed Solomon (RS) coder, a
+convolutional coder, an interleaver, a 256 FFT-based OFDM modulator, a
+multi-path channel simulator and an equalizer. The multipath channel is
+simulated using the TDL_channel class of the IT++ library.
+
+Users can configure the module to use their own traces generated by another OFDM
+simulator or ideally by performing experiments in real environment. For this
+purpose, a path to a repository containing trace files should be provided. If
+no repository is provided the traces form default-traces.h will be loaded. A
+valid repository should contain 7 files, one for each modulation and coding
+scheme.
+
+The names of the files should respect the following format: modulation0.txt for
+modulation 0, modulation1.txt for modulation 1 and so on... The file format
+should be as follows::
+
+ SNR_value1 BER Blc_ER STANDARD_DEVIATION CONFIDENCE_INTERVAL1 CONFIDENCE_INTERVAL2
+ SNR_value2 BER Blc_ER STANDARD_DEVIATION CONFIDENCE_INTERVAL1 CONFIDENCE_INTERVAL2
+ ... ... ... ... ... ...
+ ... ... ... ... ... ...
--- a/doc/manual/statistics.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,10 +0,0 @@
-@node Statistics
-@chapter Statistics
-
-@cartouche
-Placeholder chapter
-@end cartouche
-This wiki page: @*
-@uref{http://www.nsnam.org/wiki/index.php/Statistical_Framework_for_Network_Simulation,,http://www.nsnam.org/wiki/index.php/Statistical_Framework_for_Network_Simulation}
-contains information about the proposed statistical framework that is
-located in @code{src/contrib} directory.
--- a/doc/manual/tap.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,11 +0,0 @@
-@node Tap NetDevice
-@chapter Tap NetDevice
-
-@cartouche
-Placeholder chapter
-@end cartouche
-
-The Tap NetDevice can be used to allow a host system or virtual machines
-to interact with a simulation. See @*
-@code{examples/tap/tap-wifi-dumbbell.cc} for an example.
-
--- a/doc/manual/tcp.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,318 +0,0 @@
-@node TCP
-@chapter TCP models in ns-3
-@anchor{chap:TCP}
-
-This chapter describes the TCP models available in ns-3.
-
-@section Generic support for TCP
-
-ns-3 was written to support multiple TCP implementations. The
-implementations inherit from a few common header classes in the
-@code{src/node} directory, so that user code can swap out implementations
-with minimal changes to the scripts.
-
-There are two important abstract base classes:
-@itemize @bullet
-@item @code{class TcpSocket}: This is defined in @code{src/node/tcp-socket.@{cc,h@}}. This class exists for hosting TcpSocket attributes that can be
-reused across different implementations. For instance,
-@code{TcpSocket::SetInitialCwnd()} can be used for any of the implementations
-that derive from @code{class TcpSocket}.
-@item @code{class TcpSocketFactory}: This is used by applications to
-create TCP sockets. A typical usage can be seen in this snippet:
-@verbatim
- // Create the socket if not already created
- if (!m_socket)
- {
- m_socket = Socket::CreateSocket (GetNode(), m_tid);
- m_socket->Bind (m_local);
- ...
- }
-@end verbatim
-The parameter @code{m_tid} controls the TypeId of the actual TCP Socket
-implementation that is instantiated. This way, the application can be
-written generically and different socket implementations can be swapped out
-by specifying the TypeId.
-@end itemize
-
-@section ns-3 TCP
-
-ns-3 contains a port of the TCP model from
-@uref{http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/index.html,,GTNetS}. This model is a full TCP, in that it is
-bidirectional and attempts to model the connection setup and
-close logic. In fact, it is a more complete implementation of the TCP
-state machine than ns-2's "FullTcp" model. This TCP model was originally
-written by George Riley
-as part of GTNetS and ported to ns-3 by Raj Bhattacharjea.
-
-The implementation of TCP is contained in the following files:
-@verbatim
-src/internet-stack/tcp-header.{cc,h}
-src/internet-stack/tcp-l4-protocol.{cc,h}
-src/internet-stack/tcp-socket-factory-impl.{cc,h}
-src/internet-stack/tcp-socket-impl.{cc,h}
-src/internet-stack/tcp-typedefs.h
-src/internet-stack/rtt-estimator.{cc,h}
-src/internet-stack/sequence-number.{cc,h}
-@end verbatim
-
-@subsection Usage
-
-The file @code{examples/tcp-star-server.cc} contains an example that
-makes use of @code{ns3::OnOffApplication} and @code{ns3::PacketSink}
-applications.
-
-Using the helper functions defined in @code{src/helper}, here is how
-one would create a TCP receiver:
-@verbatim
- // Create a packet sink on the star "hub" to receive these packets
- uint16_t port = 50000;
- Address sinkLocalAddress(InetSocketAddress (Ipv4Address::GetAny (), port));
- PacketSinkHelper sinkHelper ("ns3::TcpSocketFactory", sinkLocalAddress);
- ApplicationContainer sinkApp = sinkHelper.Install (serverNode);
- sinkApp.Start (Seconds (1.0));
- sinkApp.Stop (Seconds (10.0));
-@end verbatim
-
-Similarly, the below snippet configures OnOffApplication traffic
-source to use
-TCP:
-@verbatim
- // Create the OnOff applications to send TCP to the server
- OnOffHelper clientHelper ("ns3::TcpSocketFactory", Address ());
-@end verbatim
-
-The careful reader will note above that we have specified the TypeId
-of an abstract base class @code{TcpSocketFactory}. How does the
-script tell ns-3 that it wants the native ns-3 TCP vs. some other one?
-Well, when internet stacks are added to the node, the default
-TCP implementation that is aggregated to the node is the ns-3 TCP.
-This can be overridden as we show below when using Network
-Simulation Cradle. So, by default, when using the ns-3 helper API,
-the TCP that is aggregated to nodes with an Internet stack is the
-native ns-3 TCP.
-
-Once a TCP socket is created, you will want to follow conventional
-socket logic and either connect() and send() (for a TCP client)
-or bind(), listen(), and accept() (for a TCP server).
-@xref{Sockets APIs,,Sockets API} for a review of how sockets are used
-in ns-3.
-
-To configure behavior of TCP, a number of parameters are exported through
-the @ref{Attributes,,ns-3 attribute system}. These are documented in the
-@uref{http://www.nsnam.org/doxygen/classns3_1_1_tcp_socket.html,,Doxygen}
-for @code{class TcpSocket}.
-
-@subsection Current limitations
-@itemize @bullet
-@item Only Tahoe congestion control is presently supported.
-@item Only IPv4 is supported
-@end itemize
-
-@section Network Simulation Cradle
-
-The @uref{http://www.wand.net.nz/~stj2/nsc/,,Network Simulation Cradle (NSC)}
-is a framework for wrapping real-world network
-code into simulators, allowing simulation of real-world behavior at little
-extra cost. This work has been validated by comparing situations using
-a test network with the same situations in the simulator. To date, it has
-been shown that the NSC is able to produce extremely accurate results.
-NSC supports four real world stacks: FreeBSD, OpenBSD, lwIP and Linux.
-Emphasis has been placed on not changing any of the network stacks by hand.
-Not a single line of code has been changed in the network protocol
-implementations of any of the above four stacks. However, a custom C
-parser was built to programmatically change source code.
-
-NSC has previously been ported to ns-2 and OMNeT++, and recently
-was added to ns-3. This section describes the ns-3 port of NSC and
-how to use it.
-
-@subsection Prerequisites
-
-Presently, NSC has been tested and shown to work on these platforms:
-Linux i386 and Linux x86-64. NSC does not support powerpc.
-
-Building NSC requires the packages flex and bison.
-
-@subsection Configuring and Downloading
-
-Using the @code{build.py} script in ns-3-allinone directory, NSC will be
-enabled by default unless the platform does not support it. To disable
-it when building ns-3, type:
-@verbatim
-./waf configure --disable-nsc
-@end verbatim
-
-@subsection Building and validating
-
-Building ns-3 with nsc support is the same as building it without; no
-additional arguments are needed for waf. Building nsc may take some time
-compared to ns-3; it is interleaved in the ns-3 building process.
-
-Try running the following ns-3 test suite: @code{./test.py -s ns3-tcp-interoperability}. If NSC has
-been successfully built, the following should show up in the results:
-@verbatim
-PASS: TestSuite ns3-tcp-interoperability
-@end verbatim
-
-This confirms that NSC is ready to use.
-
-@subsection Usage
-There are a few example files. Try
-@verbatim
-./waf --run tcp-nsc-zoo
-./waf --run tcp-nsc-lfn
-@end verbatim
-These examples will deposit some @code{.pcap} files in your directory,
-which can be examined by tcpdump or wireshark.
-
-Let's look at the @code{examples/tcp-nsc-zoo.cc} file for some typical
-usage. How does it differ from using native ns-3 TCP? There is one
-main configuration line, when using NSC and the ns-3 helper API, that needs
-to be set:
-@verbatim
- InternetStackHelper internetStack;
-
- internetStack.SetNscStack ("liblinux2.6.26.so");
- // this switches nodes 0 and 1 to NSCs Linux 2.6.26 stack.
- internetStack.Install (n.Get(0));
- internetStack.Install (n.Get(1));
-@end verbatim
-
-The key line is the @code{SetNscStack}. This tells the InternetStack
-helper to aggregate instances of NSC TCP instead of native ns-3 TCP
-to the remaining nodes. It is important that this function be called
-@strong{before} calling the @code{Install()} function, as shown above.
-
-Which stacks are available to use? Presently, the focus has been on
-Linux 2.6.18 and Linux 2.6.26 stacks for ns-3. To see which stacks
-were built, one can execute the following find command at the ns-3 top level
-directory:
-@verbatim
-~/ns-3.2> find nsc -name "*.so" -type f
-nsc/linux-2.6.18/liblinux2.6.18.so
-nsc/linux-2.6.26/liblinux2.6.26.so
-@end verbatim
-This tells us that we may either pass the library name liblinux2.6.18.so or
-liblinux2.6.26.so to the above configuration step.
-
-@subsection Stack configuration
-NSC TCP shares the same configuration attributes that are common
-across TCP sockets, as described above and documented in
-@uref{http://www.nsnam.org/doxygen/classns3_1_1_tcp_socket.html,,Doxygen}
-
-Additionally, NSC TCP exports a lot of configuration variables into the
-ns-3 @ref{Attributes} system, via a @uref{http://en.wikipedia.org/wiki/Sysctl,,
-sysctl}-like interface. In the @code{examples/tcp-nsc-zoo} example, you
-can see the following configuration:
-@smallformat
-@example
- // this disables TCP SACK, wscale and timestamps on node 1 (the attributes
-represent sysctl-values).
- Config::Set ("/NodeList/1/$ns3::Ns3NscStack<linux2.6.26>/net.ipv4.tcp_sack",
-StringValue ("0"));
- Config::Set ("/NodeList/1/$ns3::Ns3NscStack<linux2.6.26>/net.ipv4.tcp_timestamps",
-StringValue ("0"));
- Config::Set ("/NodeList/1/$ns3::Ns3NscStack<linux2.6.26>/net.ipv4.tcp_window_scaling",
-StringValue ("0"));
-@end example
-@end smallformat
-These additional configuration variables are not available to native ns-3
-TCP.
-
-@subsection NSC API
-
-This subsection describes the API that NSC presents to ns-3 or any other
-simulator. NSC provides its API in the form of a number of classes that
-are defined in @code{sim/sim_interface.h} in the nsc directory.
-
-@itemize @bullet
-@item @strong{INetStack}
-INetStack contains the 'low level' operations for the operating system
-network stack, e.g. in and output functions from and to the network stack
-(think of this as the 'network driver interface'. There are also functions
-to create new TCP or UDP sockets.
-@item @strong{ISendCallback}
-This is called by NSC when a packet should be sent out to the network.
-This simulator should use this callback to re-inject the packet into the
-simulator so the actual data can be delivered/routed to its destination,
-where it will eventually be handed into Receive() (and eventually back to the
-receivers NSC instance via INetStack->if_receive() ).
-@item @strong{INetStreamSocket}
-This is the structure defining a particular connection endpoint (file
-descriptor). It contains methods to operate on this endpoint, e.g. connect,
-disconnect, accept, listen, send_data/read_data, ...
-@item @strong{IInterruptCallback}
-This contains the wakeup callback, which is called by NSC whenever
-something of interest happens. Think of wakeup() as a replacement of the
-operating systems wakeup function: Whenever the operating system would
-wake up a process that has been waiting for an operation to complete (for
-example the TCP handshake during connect()), NSC invokes the wakeup() callback
-to allow the simulator to check for state changes in its connection endpoints.
-@end itemize
-
-@subsection ns-3 implementation
-
-The ns-3 implementation makes use of the above NSC API, and is implemented
-as follows.
-
-The three main parts are:
-@itemize @bullet
-@item @code{ns3::NscTcpL4Protocol}: a subclass of Ipv4L4Protocol (and two nsc classes: ISendCallback and IInterruptCallback)
-@item @code{ns3::NscTcpSocketImpl}: a subclass of TcpSocket
-@item @code{ns3::NscTcpSocketFactoryImpl}: a factory to create new NSC
-sockets
-@end itemize
-
-@code{src/internet-stack/nsc-tcp-l4-protocol} is the main class. Upon
-Initialization, it loads an nsc network stack to use (via dlopen()). Each
-instance of this class may use a different stack. The stack
-(=shared library) to use is set using the SetNscLibrary() method (at
-this time its called indirectly via the internet stack helper). The nsc
-stack is then set up accordingly (timers etc). The
-NscTcpL4Protocol::Receive() function hands the packet it receives (must be
-a complete tcp/ip packet) to the nsc stack for further processing.
-To be able to send packets, this class implements the nsc send_callback
-method. This method is called by nsc whenever the nsc stack wishes to
-send a packet out to the network. Its arguments are a raw buffer,
-containing a complete TCP/IP packet, and a length value. This method
-therefore has to convert the raw data to a Ptr<Packet> usable by ns-3.
-In order to avoid various ipv4 header issues, the nsc ip header is not
-included. Instead, the tcp header and the actual payload are put into the
-Ptr<Packet>, after this the Packet is passed down to layer 3 for sending
-the packet out (no further special treatment is needed in the send code
-path).
-
-This class calls @code{ns3::NscTcpSocketImpl} both from the nsc wakeup()
-callback and from the Receive path (to ensure that possibly queued data
-is scheduled for sending).
-
-
-@code{src/internet-stack/nsc-tcp-socket-impl} implements the nsc socket
-interface. Each instance has its own nscTcpSocket. Data that is Send()
-will be handed to the nsc stack via m_nscTcpSocket->send_data(). (and not
-to nsc-tcp-l4, this is the major difference compared to ns-3 TCP). The
-class also queues up data that is Send() before the underlying
-descriptor has entered an ESTABLISHED state. This class is called from
-the nsc-tcp-l4 class, when the nsc-tcp-l4 wakeup() callback is invoked by
-nsc. nsc-tcp-socket-impl then checks the current connection state
-(SYN_SENT, ESTABLISHED, LISTEN...) and schedules appropriate callbacks as
-needed, e.g. a LISTEN socket will schedule Accept to see if a new
-connection must be accepted, an ESTABLISHED socket schedules any pending
-data for writing, schedule a read callback, etc.
-
-Note that @code{ns3::NscTcpSocketImpl} does not interact with nsc-tcp
-directly: instead, data is redirected to nsc. nsc-tcp calls the
-nsc-tcp-sockets of a node when its wakeup callback is invoked by nsc.
-
-@subsection Limitations
-@itemize @bullet
-@item NSC only works on single-interface nodes; attempting to run it on
-a multi-interface node will cause a program error. This limitation should
-be fixed by ns-3.7.
-@item Cygwin and OS X PPC are not supported
-@item The non-Linux stacks of NSC are not supported in ns-3
-@item Not all socket API callbacks are supported
-@end itemize
-
-For more information, see
-@uref{http://www.nsnam.org/wiki/index.php/Network_Simulation_Cradle_Integration,, this wiki page}.
--- a/doc/manual/tracing.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,1194 +0,0 @@
-@node Tracing
-@chapter Tracing
-
-The tracing subsystem is one of the most important mechanisms to understand in
-@command{ns-3}. In most cases, @command{ns-3} users will have a brilliant idea
-for some new and improved networking feature. In order to verify that this
-idea works, the researcher will make changes to an existing system and then run
-experiments to see how the new feature behaves by gathering statistics
-that capture the behavior of the feature.
-
-In other words, the whole point of running a simulation is to generate output for
-further study. In @command{ns-3}, the subsystem that enables a researcher to do
-this is the tracing subsystem.
-
-@menu
-* Tracing Motivation::
-* Overview::
-* Using the Tracing API::
-* Using Trace Helpers::
-* Tracing implementation details::
-@end menu
-
-@node Tracing Motivation
-@section Motivation
-
-There are many ways to get information out of a program. The most straightforward
-way is to just directly print the information to the standard output, as in,
-
-@verbatim
- #include <iostream>
- ...
- int main ()
- {
- ...
- std::cout << ``The value of x is `` << x << std::endl;
- ...
- }
-@end verbatim
-
-This is workable in small environments, but as your simulations get more and more
-complicated, you end up with more and more prints and the task of parsing and
-performing computations on the output begins to get harder and harder.
-
-Another thing to consider is that every time a new tidbit is needed, the software
-core must be edited and another print introduced. There is no standardized way
-to control all of this output, so the amount of output tends to grow without
-bounds. Eventually, the bandwidth required for simply outputting this information
-begins to limit the running time of the simulation. The output files grow to
-enormous sizes and parsing them becomes a problem.
-
-@command{ns-3} provides a simple mechanism for logging and providing some control
-over output via @emph{Log Components}, but the level of control is not very fine
-grained at all. The logging module is a relatively blunt instrument.
-
-It is desirable to have a facility that allows one to reach into the core system
-and only get the information required without having to change and recompile the
-core system. Even better would be a system that notified the user when an item
-of interest changed or an interesting event happened.
-
-The @command{ns-3} tracing system is designed to work along those lines and is
-well-integrated with the Attribute and Config substems allowing for relatively
-simple use scenarios.
-
-@node Overview
-@section Overview
-
-The tracing subsystem relies heavily on the @code{ns-3} Callback and Attribute
-mechanisms. You should read and understand the corresponding sections of the
-manual before attempting to understand the tracing system.
-
-The ns-3 tracing system is built on the concepts of independent tracing sources
-and tracing sinks; along with a uniform mechanism for connecting sources to sinks.
-
-Trace sources are entities that can signal events that happen in a simulation and
-provide access to interesting underlying data. For example, a trace source could
-indicate when a packet is received by a net device and provide access to the
-packet contents for interested trace sinks. A trace source might also indicate
-when an interesting state change happens in a model. For example, the congestion
-window of a TCP model is a prime candidate for a trace source.
-
-Trace sources are not useful by themselves; they must be connected to other pieces
-of code that actually do something useful with the information provided by the source.
-The entities that consume trace information are called trace sinks. Trace sources
-are generators of events and trace sinks are consumers.
-
-This explicit division allows for large numbers of trace sources to be scattered
-around the system in places which model authors believe might be useful. Unless
-a user connects a trace sink to one of these sources, nothing is output. This
-arrangement allows relatively unsophisticated users to attach new types of sinks
-to existing tracing sources, without requiring editing and recompiling the core
-or models of the simulator.
-
-There can be zero or more consumers of trace events generated by a trace source.
-One can think of a trace source as a kind of point-to-multipoint information link.
-
-The ``transport protocol'' for this conceptual point-to-multipoint link is an
-@code{ns-3} @code{Callback}.
-
-Recall from the Callback Section that callback facility is a way to allow two
-modules in the system to communicate via function calls while at the same time
-decoupling the calling function from the called class completely. This is the
-same requirement as outlined above for the tracing system.
-
-Basically, a trace source @emph{is} a callback to which multiple
-functions may be registered. When a trace sink expresses
-interest in receiving trace events, it adds a callback to a list of callbacks
-held by the trace source. When an interesting event happens, the trace source
-invokes its @code{operator()} providing zero or more parameters. This tells
-the source to go through its list of callbacks invoking each one in turn. In
-this way, the parameter(s) are communicated to the trace sinks, which are just
-functions.
-
-@subsection The Simplest Example
-
-It will be useful to go walk a quick example just to reinforce what we've said.
-
-@smallformat
-@example
- #include ``ns3/object.h''
- #include ``ns3/uinteger.h''
- #include ``ns3/traced-value.h''
- #include ``ns3/trace-source-accessor.h''
-
- #include <iostream>
-
- using namespace ns3;
-@end example
-@end smallformat
-
-The first thing to do is include the required files. As mentioned above, the
-trace system makes heavy use of the Object and Attribute systems. The first
-two includes bring in the declarations for those systems. The file,
-@code{traced-value.h} brings in the required declarations for tracing data
-that obeys value semantics.
-
-In general, value semantics just means that you can pass the object around,
-not an address. In order to use value semantics at all you have to have an
-object with an associated copy constructor and assignment operator
-available. We extend the requirements to talk about the set of operators
-that are pre-defined for plain-old-data (POD) types. Operator=, operator++,
-operator--, operator+, operator==, etc.
-
-What this all means is that you will be able to trace changes to an object
-made using those operators.
-
-@smallformat
-@example
- class MyObject : public Object
- @{
- public:
- static TypeId GetTypeId (void)
- @{
- static TypeId tid = TypeId ("MyObject")
- .SetParent (Object::GetTypeId ())
- .AddConstructor<MyObject> ()
- .AddTraceSource ("MyInteger",
- "An integer value to trace.",
- MakeTraceSourceAccessor (&MyObject::m_myInt))
- ;
- return tid;
- @}
-
- MyObject () @{@}
- TracedValue<uint32_t> m_myInt;
- @};
-@end example
-@end smallformat
-
-Since the tracing system is integrated with Attributes, and Attributes work
-with Objects, there must be an @command{ns-3} @code{Object} for the trace source
-to live in. The two important lines of code are the @code{.AddTraceSource} and
-the @code{TracedValue} declaration.
-
-The @code{.AddTraceSource} provides the ``hooks'' used for connecting the trace
-source to the outside world. The @code{TracedValue} declaration provides the
-infrastructure that overloads the operators mentioned above and drives the callback
-process.
-
-@smallformat
-@example
- void
- IntTrace (Int oldValue, Int newValue)
- @{
- std::cout << ``Traced `` << oldValue << `` to `` << newValue << std::endl;
- @}
-@end example
-@end smallformat
-
-This is the definition of the trace sink. It corresponds directly to a callback
-function. This function will be called whenever one of the operators of the
-@code{TracedValue} is executed.
-
-@smallformat
-@example
- int
- main (int argc, char *argv[])
- @{
- Ptr<MyObject> myObject = CreateObject<MyObject> ();
-
- myObject->TraceConnectWithoutContext ("MyInteger", MakeCallback(&IntTrace));
-
- myObject->m_myInt = 1234;
- @}
-@end example
-@end smallformat
-
-In this snippet, the first thing that needs to be done is to create the object
-in which the trace source lives.
-
-The next step, the @code{TraceConnectWithoutContext}, forms the connection
-between the trace source and the trace sink. Notice the @code{MakeCallback}
-template function. Recall from the Callback section that this creates the
-specialized functor responsible for providing the overloaded @code{operator()}
-used to ``fire'' the callback. The overloaded operators (++, --, etc.) will
-use this @code{operator()} to actually invoke the callback. The
-@code{TraceConnectWithoutContext}, takes a string parameter that provides
-the name of the Attribute assigned to the trace source. Let's ignore the bit
-about context for now since it is not important yet.
-
-Finally, the line,
-
-@verbatim
- myObject->m_myInt = 1234;
-@end verbatim
-
-should be interpreted as an invocation of @code{operator=} on the member
-variable @code{m_myInt} with the integer @code{1234} passed as a parameter.
-It turns out that this operator is defined (by @code{TracedValue}) to execute
-a callback that returns void and takes two integer values as parameters --
-an old value and a new value for the integer in question. That is exactly
-the function signature for the callback function we provided -- @code{IntTrace}.
-
-To summarize, a trace source is, in essence, a variable that holds a list of
-callbacks. A trace sink is a function used as the target of a callback. The
-Attribute and object type information systems are used to provide a way to
-connect trace sources to trace sinks. The act of ``hitting'' a trace source
-is executing an operator on the trace source which fires callbacks. This
-results in the trace sink callbacks registering interest in the source being
-called with the parameters provided by the source.
-
-@subsection Using the Config Subsystem to Connect to Trace Sources
-
-The @code{TraceConnectWithoutContext} call shown above in the simple example is
-actually very rarely used in the system. More typically, the @code{Config}
-subsystem is used to allow selecting a trace source in the system using what is
-called a @emph{config path}.
-
-For example, one might find something that looks like the following in the system
-(taken from @code{examples/tcp-large-transfer.cc})
-
-@smallformat
-@example
- void CwndTracer (uint32_t oldval, uint32_t newval) @{@}
-
- ...
-
- Config::ConnectWithoutContext (
- "/NodeList/0/$ns3::TcpL4Protocol/SocketList/0/CongestionWindow",
- MakeCallback (&CwndTracer));
-@end example
-@end smallformat
-
-This should look very familiar. It is the same thing as the previous example,
-except that a static member function of class @code{Config} is being called instead
-of a method on @code{Object}; and instead of an @code{Attribute} name, a path is
-being provided.
-
-The first thing to do is to read the path backward. The last segment of the path
-must be an @code{Attribute} of an @code{Object}. In fact, if you had a pointer to
-the @code{Object} that has the ``CongestionWindow'' @code{Attribute} handy (call it
-@code{theObject}), you could write this just like the previous example:
-
-@smallformat
-@example
- void CwndTracer (uint32_t oldval, uint32_t newval) @{@}
-
- ...
-
- theObject->TraceConnectWithoutContext ("CongestionWindow", MakeCallback (&CwndTracer));
-@end example
-@end smallformat
-
-It turns out that the code for @code{Config::ConnectWithoutContext} does exactly that.
-This function takes a path that represents a chain of @code{Object} pointers and follows
-them until it gets to the end of the path and interprets the last segment as an
-@code{Attribute} on the last object. Let's walk through what happens.
-
-The leading ``/'' character in the path refers to a so-called namespace. One of the
-predefined namespaces in the config system is ``NodeList'' which is a list of all of
-the nodes in the simulation. Items in the list are referred to by indices into the
-list, so ``/NodeList/0'' refers to the zeroth node in the list of nodes created by
-the simulation. This node is actually a @code{Ptr<Node>} and so is a subclass of
-an @code{ns3::Object}.
-
-As described in the Object Model section, @code{ns-3} supports an object aggregation
-model. The next path segment begins with the ``$'' character which indicates a
-@code{GetObject} call should be made looking for the type that follows. When a
-node is initialized by an @code{InternetStackHelper} a number of interfaces are
-aggregated to the node. One of these is the TCP level four protocol. The runtime
-type of this protocol object is ``ns3::TcpL4Protocol''. When the @code{GetObject}
-is executed, it returns a pointer to the object of this type.
-
-The @code{TcpL4Protocol} class defines an Attribute called ``SocketList'' which is
-a list of sockets. Each socket is actually an @code{ns3::Object} with its own
-@code{Attributes}. The items in the list of sockets are referred to by index just
-as in the NodeList, so ``SocketList/0'' refers to the zeroth socket in the list
-of sockets on the zeroth node in the NodeList -- the first node constructed in the
-simulation.
-
-This socket, the type of which turns out to be an @code{ns3::TcpSocketImpl} defines
-an attribute called ``CongestionWindow'' which is a @code{TracedValue<uint32_t>}.
-The @code{Config::ConnectWithoutContext} now does a,
-
-@smallformat
-@example
- object->TraceConnectWithoutContext ("CongestionWindow", MakeCallback (&CwndTracer));
-@end example
-@end smallformat
-
-using the object pointer from ``SocketList/0'' which makes the connection between
-the trace source defined in the socket to the callback -- @code{CwndTracer}.
-
-Now, whenever a change is made to the @code{TracedValue<uint32_t>} representing the
-congestion window in the TCP socket, the registered callback will be executed and
-the function @code{CwndTracer} will be called printing out the old and new values
-of the TCP congestion window.
-
-@node Using the Tracing API
-@section Using the Tracing API
-
- There
-are three levels of interaction with the tracing system:
-
-@itemize @bullet
-@item Beginning user can easily control which objects are participating in tracing;
-@item Intermediate users can extend the tracing system to modify the output format
-generated or use existing trace sources in different ways, without modifying the
-core of the simulator;
-@item Advanced users can modify the simulator core to add new tracing sources and
-sinks.
-@end itemize
-
-@node Using Trace Helpers
-@section Using Trace Helpers
-
-The @code{ns-3} trace helpers provide a rich environment for configuring and
-selecting different trace events and writing them to files. In previous
-sections, primarily ``Building Topologies,'' we have seen several varieties
-of the trace helper methods designed for use inside other (device) helpers.
-
-Perhaps you will recall seeing some of these variations:
-
-@verbatim
- pointToPoint.EnablePcapAll ("second");
- pointToPoint.EnablePcap ("second", p2pNodes.Get (0)->GetId (), 0);
- csma.EnablePcap ("third", csmaDevices.Get (0), true);
- pointToPoint.EnableAsciiAll (ascii.CreateFileStream ("myfirst.tr"));
-@end verbatim
-
-What may not be obvious, though, is that there is a consistent model for all of
-the trace-related methods found in the system. We will now take a little time
-and take a look at the ``big picture''.
-
-There are currently two primary use cases of the tracing helpers in @code{ns-3}:
-Device helpers and protocol helpers. Device helpers look at the problem
-of specifying which traces should be enabled through a node, device pair. For
-example, you may want to specify that pcap tracing should be enabled on a
-particular device on a specific node. This follows from the @code{ns-3} device
-conceptual model, and also the conceptual models of the various device helpers.
-Following naturally from this, the files created follow a
-<prefix>-<node>-<device> naming convention.
-
-Protocol helpers look at the problem of specifying which traces should be
-enabled through a protocol and interface pair. This follows from the @code{ns-3}
-protocol stack conceptual model, and also the conceptual models of internet
-stack helpers. Naturally, the trace files should follow a
-<prefix>-<protocol>-<interface> naming convention.
-
-The trace helpers therefore fall naturally into a two-dimensional taxonomy.
-There are subtleties that prevent all four classes from behaving identically,
-but we do strive to make them all work as similarly as possible; and whenever
-possible there are analogs for all methods in all classes.
-
-@verbatim
- | pcap | ascii |
- -----------------+------+-------|
- Device Helper | | |
- -----------------+------+-------|
- Protocol Helper | | |
- -----------------+------+-------|
-@end verbatim
-
-We use an approach called a @code{mixin} to add tracing functionality to our
-helper classes. A @code{mixin} is a class that provides functionality to that
-is inherited by a subclass. Inheriting from a mixin is not considered a form
-of specialization but is really a way to collect functionality.
-
-Let's take a quick look at all four of these cases and their respective
-@code{mixins}.
-
-@subsection Pcap Tracing Device Helpers
-
-The goal of these helpers is to make it easy to add a consistent pcap trace
-facility to an @code{ns-3} device. We want all of the various flavors of
-pcap tracing to work the same across all devices, so the methods of these
-helpers are inherited by device helpers. Take a look at
-@code{src/helper/trace-helper.h} if you want to follow the discussion while
-looking at real code.
-
-The class @code{PcapHelperForDevice} is a @code{mixin} provides the high level
-functionality for using pcap tracing in an @code{ns-3} device. Every device
-must implement a single virtual method inherited from this class.
-
-@verbatim
- virtual void EnablePcapInternal (std::string prefix, Ptr<NetDevice> nd, bool promiscuous) = 0;
-@end verbatim
-
-The signature of this method reflects the device-centric view of the situation
-at this level. All of the public methods inherited from class
-2@code{PcapUserHelperForDevice} reduce to calling this single device-dependent
-implementation method. For example, the lowest level pcap method,
-
-@verbatim
- void EnablePcap (std::string prefix, Ptr<NetDevice> nd, bool promiscuous = false, bool explicitFilename = false);
-@end verbatim
-
-will call the device implementation of @code{EnablePcapInternal} directly. All
-other public pcap tracing methods build on this implementation to provide
-additional user-level functionality. What this means to the user is that all
-device helpers in the system will have all of the pcap trace methods available;
-and these methods will all work in the same way across devices if the device
-implements @code{EnablePcapInternal} correctly.
-
-@subsubsection Pcap Tracing Device Helper Methods
-
-@verbatim
- void EnablePcap (std::string prefix, Ptr<NetDevice> nd, bool promiscuous = false, bool explicitFilename = false);
- void EnablePcap (std::string prefix, std::string ndName, bool promiscuous = false, bool explicitFilename = false);
- void EnablePcap (std::string prefix, NetDeviceContainer d, bool promiscuous = false);
- void EnablePcap (std::string prefix, NodeContainer n, bool promiscuous = false);
- void EnablePcap (std::string prefix, uint32_t nodeid, uint32_t deviceid, bool promiscuous = false);
- void EnablePcapAll (std::string prefix, bool promiscuous = false);
-@end verbatim
-
-In each of the methods shown above, there is a default parameter called
-@code{promiscuous} that defaults to false. This parameter indicates that the
-trace should not be gathered in promiscuous mode. If you do want your traces
-to include all traffic seen by the device (and if the device supports a
-promiscuous mode) simply add a true parameter to any of the calls above. For example,
-
-@verbatim
- Ptr<NetDevice> nd;
- ...
- helper.EnablePcap ("prefix", nd, true);
-@end verbatim
-
-will enable promiscuous mode captures on the @code{NetDevice} specified by @code{nd}.
-
-The first two methods also include a default parameter called @code{explicitFilename}
-that will be discussed below.
-
-You are encouraged to peruse the Doxygen for class @code{PcapHelperForDevice}
-to find the details of these methods; but to summarize ...
-
-You can enable pcap tracing on a particular node/net-device pair by providing a
-@code{Ptr<NetDevice>} to an @code{EnablePcap} method. The @code{Ptr<Node>} is
-implicit since the net device must belong to exactly one @code{Node}.
-For example,
-
-@verbatim
- Ptr<NetDevice> nd;
- ...
- helper.EnablePcap ("prefix", nd);
-@end verbatim
-
-You can enable pcap tracing on a particular node/net-device pair by providing a
-@code{std::string} representing an object name service string to an
-@code{EnablePcap} method. The @code{Ptr<NetDevice>} is looked up from the name
-string. Again, the @code{Node} is implicit since the named net device must
-belong to exactly one @code{Node}. For example,
-
-@verbatim
- Names::Add ("server" ...);
- Names::Add ("server/eth0" ...);
- ...
- helper.EnablePcap ("prefix", "server/ath0");
-@end verbatim
-
-You can enable pcap tracing on a collection of node/net-device pairs by
-providing a @code{NetDeviceContainer}. For each @code{NetDevice} in the container
-the type is checked. For each device of the proper type (the same type as is
-managed by the device helper), tracing is enabled. Again, the @code{Node} is
-implicit since the found net device must belong to exactly one @code{Node}.
-For example,
-
-@verbatim
- NetDeviceContainer d = ...;
- ...
- helper.EnablePcap ("prefix", d);
-@end verbatim
-
-You can enable pcap tracing on a collection of node/net-device pairs by
-providing a @code{NodeContainer}. For each @code{Node} in the @code{NodeContainer}
-its attached @code{NetDevices} are iterated. For each @code{NetDevice} attached
-to each node in the container, the type of that device is checked. For each
-device of the proper type (the same type as is managed by the device helper),
-tracing is enabled.
-
-@verbatim
- NodeContainer n;
- ...
- helper.EnablePcap ("prefix", n);
-@end verbatim
-
-You can enable pcap tracing on the basis of node ID and device ID as well as
-with explicit @code{Ptr}. Each @code{Node} in the system has an integer node ID
-and each device connected to a node has an integer device ID.
-
-@verbatim
- helper.EnablePcap ("prefix", 21, 1);
-@end verbatim
-
-Finally, you can enable pcap tracing for all devices in the system, with the
-same type as that managed by the device helper.
-
-@verbatim
- helper.EnablePcapAll ("prefix");
-@end verbatim
-
-@subsubsection Pcap Tracing Device Helper Filename Selection
-
-Implicit in the method descriptions above is the construction of a complete
-filename by the implementation method. By convention, pcap traces in the
-@code{ns-3} system are of the form ``<prefix>-<node id>-<device id>.pcap''
-
-As previously mentioned, every node in the system will have a system-assigned
-node id; and every device will have an interface index (also called a device id)
-relative to its node. By default, then, a pcap trace file created as a result
-of enabling tracing on the first device of node 21 using the prefix ``prefix''
-would be ``prefix-21-1.pcap''.
-
-You can always use the @code{ns-3} object name service to make this more clear.
-For example, if you use the object name service to assign the name ``server''
-to node 21, the resulting pcap trace file name will automatically become,
-``prefix-server-1.pcap'' and if you also assign the name ``eth0'' to the
-device, your pcap file name will automatically pick this up and be called
-``prefix-server-eth0.pcap''.
-
-Finally, two of the methods shown above,
-
-@verbatim
- void EnablePcap (std::string prefix, Ptr<NetDevice> nd, bool promiscuous = false, bool explicitFilename = false);
- void EnablePcap (std::string prefix, std::string ndName, bool promiscuous = false, bool explicitFilename = false);
-@end verbatim
-
-have a default parameter called @code{explicitFilename}. When set to true,
-this parameter disables the automatic filename completion mechanism and allows
-you to create an explicit filename. This option is only available in the
-methods which enable pcap tracing on a single device.
-
-For example, in order to arrange for a device helper to create a single
-promiscuous pcap capture file of a specific name (``my-pcap-file.pcap'') on a
-given device, one could:
-
-@verbatim
- Ptr<NetDevice> nd;
- ...
- helper.EnablePcap ("my-pcap-file.pcap", nd, true, true);
-@end verbatim
-
-The first @code{true} parameter enables promiscuous mode traces and the second
-tells the helper to interpret the @code{prefix} parameter as a complete filename.
-
-@subsection Ascii Tracing Device Helpers
-
-The behavior of the ascii trace helper @code{mixin} is substantially similar to
-the pcap version. Take a look at @code{src/helper/trace-helper.h} if you want to
-follow the discussion while looking at real code.
-
-The class @code{AsciiTraceHelperForDevice} adds the high level functionality for
-using ascii tracing to a device helper class. As in the pcap case, every device
-must implement a single virtual method inherited from the ascii trace @code{mixin}.
-
-@verbatim
- virtual void EnableAsciiInternal (Ptr<OutputStreamWrapper> stream, std::string prefix, Ptr<NetDevice> nd) = 0;
-@end verbatim
-
-The signature of this method reflects the device-centric view of the situation
-at this level; and also the fact that the helper may be writing to a shared
-output stream. All of the public ascii-trace-related methods inherited from
-class @code{AsciiTraceHelperForDevice} reduce to calling this single device-
-dependent implementation method. For example, the lowest level ascii trace
-methods,
-
-@verbatim
- void EnableAscii (std::string prefix, Ptr<NetDevice> nd);
- void EnableAscii (Ptr<OutputStreamWrapper> stream, Ptr<NetDevice> nd);
-@verbatim
-
-will call the device implementation of @code{EnableAsciiInternal} directly,
-providing either a valid prefix or stream. All other public ascii tracing
-methods will build on these low-level functions to provide additional user-level
-functionality. What this means to the user is that all device helpers in the
-system will have all of the ascii trace methods available; and these methods
-will all work in the same way across devices if the devices implement
-@code{EnablAsciiInternal} correctly.
-
-@subsubsection Ascii Tracing Device Helper Methods
-
-@verbatim
- void EnableAscii (std::string prefix, Ptr<NetDevice> nd);
- void EnableAscii (Ptr<OutputStreamWrapper> stream, Ptr<NetDevice> nd);
-
- void EnableAscii (std::string prefix, std::string ndName);
- void EnableAscii (Ptr<OutputStreamWrapper> stream, std::string ndName);
-
- void EnableAscii (std::string prefix, NetDeviceContainer d);
- void EnableAscii (Ptr<OutputStreamWrapper> stream, NetDeviceContainer d);
-
- void EnableAscii (std::string prefix, NodeContainer n);
- void EnableAscii (Ptr<OutputStreamWrapper> stream, NodeContainer n);
-
- void EnableAscii (std::string prefix, uint32_t nodeid, uint32_t deviceid);
- void EnableAscii (Ptr<OutputStreamWrapper> stream, uint32_t nodeid, uint32_t deviceid);
-
- void EnableAsciiAll (std::string prefix);
- void EnableAsciiAll (Ptr<OutputStreamWrapper> stream);
-@end verbatim
-
-You are encouraged to peruse the Doxygen for class @code{TraceHelperForDevice}
-to find the details of these methods; but to summarize ...
-
-There are twice as many methods available for ascii tracing as there were for
-pcap tracing. This is because, in addition to the pcap-style model where traces
-from each unique node/device pair are written to a unique file, we support a model
-in which trace information for many node/device pairs is written to a common file.
-This means that the <prefix>-<node>-<device> file name generation mechanism is
-replaced by a mechanism to refer to a common file; and the number of API methods
-is doubled to allow all combinations.
-
-Just as in pcap tracing, you can enable ascii tracing on a particular
-node/net-device pair by providing a @code{Ptr<NetDevice>} to an @code{EnableAscii}
-method. The @code{Ptr<Node>} is implicit since the net device must belong to
-exactly one @code{Node}. For example,
-
-@verbatim
- Ptr<NetDevice> nd;
- ...
- helper.EnableAscii ("prefix", nd);
-@end verbatim
-
-In this case, no trace contexts are written to the ascii trace file since they
-would be redundant. The system will pick the file name to be created using
-the same rules as described in the pcap section, except that the file will
-have the suffix ``.tr'' instead of ``.pcap''.
-
-If you want to enable ascii tracing on more than one net device and have all
-traces sent to a single file, you can do that as well by using an object to
-refer to a single file:
-
-@verbatim
- Ptr<NetDevice> nd1;
- Ptr<NetDevice> nd2;
- ...
- Ptr<OutputStreamWrapper> stream = asciiTraceHelper.CreateFileStream ("trace-file-name.tr");
- ...
- helper.EnableAscii (stream, nd1);
- helper.EnableAscii (stream, nd2);
-@verbatim
-
-In this case, trace contexts are written to the ascii trace file since they
-are required to disambiguate traces from the two devices. Note that since the
-user is completely specifying the file name, the string should include the ``,tr''
-for consistency.
-
-You can enable ascii tracing on a particular node/net-device pair by providing a
-@code{std::string} representing an object name service string to an
-@code{EnablePcap} method. The @code{Ptr<NetDevice>} is looked up from the name
-string. Again, the @code{Node} is implicit since the named net device must
-belong to exactly one @code{Node}. For example,
-
-@verbatim
- Names::Add ("client" ...);
- Names::Add ("client/eth0" ...);
- Names::Add ("server" ...);
- Names::Add ("server/eth0" ...);
- ...
- helper.EnableAscii ("prefix", "client/eth0");
- helper.EnableAscii ("prefix", "server/eth0");
-@end verbatim
-
-This would result in two files named ``prefix-client-eth0.tr'' and
-``prefix-server-eth0.tr'' with traces for each device in the respective trace
-file. Since all of the EnableAscii functions are overloaded to take a stream wrapper,
-you can use that form as well:
-
-@verbatim
- Names::Add ("client" ...);
- Names::Add ("client/eth0" ...);
- Names::Add ("server" ...);
- Names::Add ("server/eth0" ...);
- ...
- Ptr<OutputStreamWrapper> stream = asciiTraceHelper.CreateFileStream ("trace-file-name.tr");
- ...
- helper.EnableAscii (stream, "client/eth0");
- helper.EnableAscii (stream, "server/eth0");
-@end verbatim
-
-This would result in a single trace file called ``trace-file-name.tr'' that
-contains all of the trace events for both devices. The events would be
-disambiguated by trace context strings.
-
-You can enable ascii tracing on a collection of node/net-device pairs by
-providing a @code{NetDeviceContainer}. For each @code{NetDevice} in the container
-the type is checked. For each device of the proper type (the same type as is
-managed by the device helper), tracing is enabled. Again, the @code{Node} is
-implicit since the found net device must belong to exactly one @code{Node}.
-For example,
-
-@verbatim
- NetDeviceContainer d = ...;
- ...
- helper.EnableAscii ("prefix", d);
-@end verbatim
-
-This would result in a number of ascii trace files being created, each of which
-follows the <prefix>-<node id>-<device id>.tr convention. Combining all of the
-traces into a single file is accomplished similarly to the examples above:
-
-@verbatim
- NetDeviceContainer d = ...;
- ...
- Ptr<OutputStreamWrapper> stream = asciiTraceHelper.CreateFileStream ("trace-file-name.tr");
- ...
- helper.EnableAscii (stream, d);
-@end verbatim
-
-You can enable ascii tracing on a collection of node/net-device pairs by
-providing a @code{NodeContainer}. For each @code{Node} in the @code{NodeContainer}
-its attached @code{NetDevices} are iterated. For each @code{NetDevice} attached
-to each node in the container, the type of that device is checked. For each
-device of the proper type (the same type as is managed by the device helper),
-tracing is enabled.
-
-@verbatim
- NodeContainer n;
- ...
- helper.EnableAscii ("prefix", n);
-@end verbatim
-
-This would result in a number of ascii trace files being created, each of which
-follows the <prefix>-<node id>-<device id>.tr convention. Combining all of the
-traces into a single file is accomplished similarly to the examples above:
-
-You can enable pcap tracing on the basis of node ID and device ID as well as
-with explicit @code{Ptr}. Each @code{Node} in the system has an integer node ID
-and each device connected to a node has an integer device ID.
-
-@verbatim
- helper.EnableAscii ("prefix", 21, 1);
-@end verbatim
-
-Of course, the traces can be combined into a single file as shown above.
-
-Finally, you can enable pcap tracing for all devices in the system, with the
-same type as that managed by the device helper.
-
-@verbatim
- helper.EnableAsciiAll ("prefix");
-@end verbatim
-
-This would result in a number of ascii trace files being created, one for
-every device in the system of the type managed by the helper. All of these
-files will follow the <prefix>-<node id>-<device id>.tr convention. Combining
-all of the traces into a single file is accomplished similarly to the examples
-above.
-
-@subsubsection Ascii Tracing Device Helper Filename Selection
-
-Implicit in the prefix-style method descriptions above is the construction of the
-complete filenames by the implementation method. By convention, ascii traces
-in the @code{ns-3} system are of the form ``<prefix>-<node id>-<device id>.tr''
-
-As previously mentioned, every node in the system will have a system-assigned
-node id; and every device will have an interface index (also called a device id)
-relative to its node. By default, then, an ascii trace file created as a result
-of enabling tracing on the first device of node 21, using the prefix ``prefix'',
-would be ``prefix-21-1.tr''.
-
-You can always use the @code{ns-3} object name service to make this more clear.
-For example, if you use the object name service to assign the name ``server''
-to node 21, the resulting ascii trace file name will automatically become,
-``prefix-server-1.tr'' and if you also assign the name ``eth0'' to the
-device, your ascii trace file name will automatically pick this up and be called
-``prefix-server-eth0.tr''.
-
-@subsection Pcap Tracing Protocol Helpers
-
-The goal of these @code{mixins} is to make it easy to add a consistent pcap trace
-facility to protocols. We want all of the various flavors of pcap tracing to
-work the same across all protocols, so the methods of these helpers are
-inherited by stack helpers. Take a look at @code{src/helper/trace-helper.h}
-if you want to follow the discussion while looking at real code.
-
-In this section we will be illustrating the methods as applied to the protocol
-@code{Ipv4}. To specify traces in similar protocols, just substitute the
-appropriate type. For example, use a @code{Ptr<Ipv6>} instead of a
-@code{Ptr<Ipv4>} and call @code{EnablePcapIpv6} instead of @code{EnablePcapIpv4}.
-
-The class @code{PcapHelperForIpv4} provides the high level functionality for
-using pcap tracing in the @code{Ipv4} protocol. Each protocol helper enabling these
-methods must implement a single virtual method inherited from this class. There
-will be a separate implementation for @code{Ipv6}, for example, but the only
-difference will be in the method names and signatures. Different method names
-are required to disambiguate class @code{Ipv4} from @code{Ipv6} which are both
-derived from class @code{Object}, and methods that share the same signature.
-
-@verbatim
- virtual void EnablePcapIpv4Internal (std::string prefix, Ptr<Ipv4> ipv4, uint32_t interface) = 0;
-@end verbatim
-
-The signature of this method reflects the protocol and interface-centric view
-of the situation at this level. All of the public methods inherited from class
-@code{PcapHelperForIpv4} reduce to calling this single device-dependent
-implementation method. For example, the lowest level pcap method,
-
-@verbatim
- void EnablePcapIpv4 (std::string prefix, Ptr<Ipv4> ipv4, uint32_t interface);
-@verbatim
-
-will call the device implementation of @code{EnablePcapIpv4Internal} directly.
-All other public pcap tracing methods build on this implementation to provide
-additional user-level functionality. What this means to the user is that all
-protocol helpers in the system will have all of the pcap trace methods
-available; and these methods will all work in the same way across
-protocols if the helper implements @code{EnablePcapIpv4Internal} correctly.
-
-@subsubsection Pcap Tracing Protocol Helper Methods
-
-These methods are designed to be in one-to-one correspondence with the @code{Node}-
-and @code{NetDevice}- centric versions of the device versions. Instead of
-@code{Node} and @code{NetDevice} pair constraints, we use protocol and interface
-constraints.
-
-Note that just like in the device version, there are six methods:
-
-@verbatim
- void EnablePcapIpv4 (std::string prefix, Ptr<Ipv4> ipv4, uint32_t interface);
- void EnablePcapIpv4 (std::string prefix, std::string ipv4Name, uint32_t interface);
- void EnablePcapIpv4 (std::string prefix, Ipv4InterfaceContainer c);
- void EnablePcapIpv4 (std::string prefix, NodeContainer n);
- void EnablePcapIpv4 (std::string prefix, uint32_t nodeid, uint32_t interface);
- void EnablePcapIpv4All (std::string prefix);
-@end verbatim
-
-You are encouraged to peruse the Doxygen for class @code{PcapHelperForIpv4}
-to find the details of these methods; but to summarize ...
-
-You can enable pcap tracing on a particular protocol/interface pair by providing a
-@code{Ptr<Ipv4>} and @code{interface} to an @code{EnablePcap} method. For example,
-
-@verbatim
- Ptr<Ipv4> ipv4 = node->GetObject<Ipv4> ();
- ...
- helper.EnablePcapIpv4 ("prefix", ipv4, 0);
-@end verbatim
-
-You can enable pcap tracing on a particular node/net-device pair by providing a
-@code{std::string} representing an object name service string to an
-@code{EnablePcap} method. The @code{Ptr<Ipv4>} is looked up from the name
-string. For example,
-
-@verbatim
- Names::Add ("serverIPv4" ...);
- ...
- helper.EnablePcapIpv4 ("prefix", "serverIpv4", 1);
-@end verbatim
-
-You can enable pcap tracing on a collection of protocol/interface pairs by
-providing an @code{Ipv4InterfaceContainer}. For each @code{Ipv4} / interface
-pair in the container the protocol type is checked. For each protocol of the
-proper type (the same type as is managed by the device helper), tracing is
-enabled for the corresponding interface. For example,
-
-@verbatim
- NodeContainer nodes;
- ...
- NetDeviceContainer devices = deviceHelper.Install (nodes);
- ...
- Ipv4AddressHelper ipv4;
- ipv4.SetBase ("10.1.1.0", "255.255.255.0");
- Ipv4InterfaceContainer interfaces = ipv4.Assign (devices);
- ...
- helper.EnablePcapIpv4 ("prefix", interfaces);
-@end verbatim
-
-You can enable pcap tracing on a collection of protocol/interface pairs by
-providing a @code{NodeContainer}. For each @code{Node} in the @code{NodeContainer}
-the appropriate protocol is found. For each protocol, its interfaces are
-enumerated and tracing is enabled on the resulting pairs. For example,
-
-@verbatim
- NodeContainer n;
- ...
- helper.EnablePcapIpv4 ("prefix", n);
-@end verbatim
-
-You can enable pcap tracing on the basis of node ID and interface as well. In
-this case, the node-id is translated to a @code{Ptr<Node>} and the appropriate
-protocol is looked up in the node. The resulting protocol and interface are
-used to specify the resulting trace source.
-
-@verbatim
- helper.EnablePcapIpv4 ("prefix", 21, 1);
-@end verbatim
-
-Finally, you can enable pcap tracing for all interfaces in the system, with
-associated protocol being the same type as that managed by the device helper.
-
-@verbatim
- helper.EnablePcapIpv4All ("prefix");
-@end verbatim
-
-@subsubsection Pcap Tracing Protocol Helper Filename Selection
-
-Implicit in all of the method descriptions above is the construction of the
-complete filenames by the implementation method. By convention, pcap traces
-taken for devices in the @code{ns-3} system are of the form
-``<prefix>-<node id>-<device id>.pcap''. In the case of protocol traces,
-there is a one-to-one correspondence between protocols and @code{Nodes}.
-This is because protocol @code{Objects} are aggregated to @code{Node Objects}.
-Since there is no global protocol id in the system, we use the corresponding
-node id in file naming. Therefore there is a possibility for file name
-collisions in automatically chosen trace file names. For this reason, the
-file name convention is changed for protocol traces.
-
-As previously mentioned, every node in the system will have a system-assigned
-node id. Since there is a one-to-one correspondence between protocol instances
-and node instances we use the node id. Each interface has an interface id
-relative to its protocol. We use the convention
-"<prefix>-n<node id>-i<interface id>.pcap" for trace file naming in protocol
-helpers.
-
-Therefore, by default, a pcap trace file created as a result of enabling tracing
-on interface 1 of the Ipv4 protocol of node 21 using the prefix ``prefix''
-would be ``prefix-n21-i1.pcap''.
-
-You can always use the @code{ns-3} object name service to make this more clear.
-For example, if you use the object name service to assign the name ``serverIpv4''
-to the Ptr<Ipv4> on node 21, the resulting pcap trace file name will
-automatically become, ``prefix-nserverIpv4-i1.pcap''.
-
-@subsection Ascii Tracing Protocol Helpers
-
-The behavior of the ascii trace helpers is substantially similar to the pcap
-case. Take a look at @code{src/helper/trace-helper.h} if you want to
-follow the discussion while looking at real code.
-
-In this section we will be illustrating the methods as applied to the protocol
-@code{Ipv4}. To specify traces in similar protocols, just substitute the
-appropriate type. For example, use a @code{Ptr<Ipv6>} instead of a
-@code{Ptr<Ipv4>} and call @code{EnableAsciiIpv6} instead of @code{EnableAsciiIpv4}.
-
-The class @code{AsciiTraceHelperForIpv4} adds the high level functionality
-for using ascii tracing to a protocol helper. Each protocol that enables these
-methods must implement a single virtual method inherited from this class.
-
-@verbatim
- virtual void EnableAsciiIpv4Internal (Ptr<OutputStreamWrapper> stream, std::string prefix,
- Ptr<Ipv4> ipv4, uint32_t interface) = 0;
-@end verbatim
-
-The signature of this method reflects the protocol- and interface-centric view
-of the situation at this level; and also the fact that the helper may be writing
-to a shared output stream. All of the public methods inherited from class
-@code{PcapAndAsciiTraceHelperForIpv4} reduce to calling this single device-
-dependent implementation method. For example, the lowest level ascii trace
-methods,
-
-@verbatim
- void EnableAsciiIpv4 (std::string prefix, Ptr<Ipv4> ipv4, uint32_t interface);
- void EnableAsciiIpv4 (Ptr<OutputStreamWrapper> stream, Ptr<Ipv4> ipv4, uint32_t interface);
-@verbatim
-
-will call the device implementation of @code{EnableAsciiIpv4Internal} directly,
-providing either the prefix or the stream. All other public ascii tracing
-methods will build on these low-level functions to provide additional user-level
-functionality. What this means to the user is that all device helpers in the
-system will have all of the ascii trace methods available; and these methods
-will all work in the same way across protocols if the protocols implement
-@code{EnablAsciiIpv4Internal} correctly.
-
-@subsubsection Ascii Tracing Device Helper Methods
-
-@verbatim
- void EnableAsciiIpv4 (std::string prefix, Ptr<Ipv4> ipv4, uint32_t interface);
- void EnableAsciiIpv4 (Ptr<OutputStreamWrapper> stream, Ptr<Ipv4> ipv4, uint32_t interface);
-
- void EnableAsciiIpv4 (std::string prefix, std::string ipv4Name, uint32_t interface);
- void EnableAsciiIpv4 (Ptr<OutputStreamWrapper> stream, std::string ipv4Name, uint32_t interface);
-
- void EnableAsciiIpv4 (std::string prefix, Ipv4InterfaceContainer c);
- void EnableAsciiIpv4 (Ptr<OutputStreamWrapper> stream, Ipv4InterfaceContainer c);
-
- void EnableAsciiIpv4 (std::string prefix, NodeContainer n);
- void EnableAsciiIpv4 (Ptr<OutputStreamWrapper> stream, NodeContainer n);
-
- void EnableAsciiIpv4 (std::string prefix, uint32_t nodeid, uint32_t deviceid);
- void EnableAsciiIpv4 (Ptr<OutputStreamWrapper> stream, uint32_t nodeid, uint32_t interface);
-
- void EnableAsciiIpv4All (std::string prefix);
- void EnableAsciiIpv4All (Ptr<OutputStreamWrapper> stream);
-@end verbatim
-
-You are encouraged to peruse the Doxygen for class @code{PcapAndAsciiHelperForIpv4}
-to find the details of these methods; but to summarize ...
-
-There are twice as many methods available for ascii tracing as there were for
-pcap tracing. This is because, in addition to the pcap-style model where traces
-from each unique protocol/interface pair are written to a unique file, we
-support a model in which trace information for many protocol/interface pairs is
-written to a common file. This means that the <prefix>-n<node id>-<interface>
-file name generation mechanism is replaced by a mechanism to refer to a common
-file; and the number of API methods is doubled to allow all combinations.
-
-Just as in pcap tracing, you can enable ascii tracing on a particular
-protocol/interface pair by providing a @code{Ptr<Ipv4>} and an @code{interface}
-to an @code{EnableAscii} method.
-For example,
-
-@verbatim
- Ptr<Ipv4> ipv4;
- ...
- helper.EnableAsciiIpv4 ("prefix", ipv4, 1);
-@end verbatim
-
-In this case, no trace contexts are written to the ascii trace file since they
-would be redundant. The system will pick the file name to be created using
-the same rules as described in the pcap section, except that the file will
-have the suffix ``.tr'' instead of ``.pcap''.
-
-If you want to enable ascii tracing on more than one interface and have all
-traces sent to a single file, you can do that as well by using an object to
-refer to a single file. We have already something similar to this in the
-``cwnd'' example above:
-
-@verbatim
- Ptr<Ipv4> protocol1 = node1->GetObject<Ipv4> ();
- Ptr<Ipv4> protocol2 = node2->GetObject<Ipv4> ();
- ...
- Ptr<OutputStreamWrapper> stream = asciiTraceHelper.CreateFileStream ("trace-file-name.tr");
- ...
- helper.EnableAsciiIpv4 (stream, protocol1, 1);
- helper.EnableAsciiIpv4 (stream, protocol2, 1);
-@verbatim
-
-In this case, trace contexts are written to the ascii trace file since they
-are required to disambiguate traces from the two interfaces. Note that since
-the user is completely specifying the file name, the string should include the
-``,tr'' for consistency.
-
-You can enable ascii tracing on a particular protocol by providing a
-@code{std::string} representing an object name service string to an
-@code{EnablePcap} method. The @code{Ptr<Ipv4>} is looked up from the name
-string. The @code{Node} in the resulting filenames is implicit since there
-is a one-to-one correspondence between protocol instances and nodes,
-For example,
-
-@verbatim
- Names::Add ("node1Ipv4" ...);
- Names::Add ("node2Ipv4" ...);
- ...
- helper.EnableAsciiIpv4 ("prefix", "node1Ipv4", 1);
- helper.EnableAsciiIpv4 ("prefix", "node2Ipv4", 1);
-@end verbatim
-
-This would result in two files named ``prefix-nnode1Ipv4-i1.tr'' and
-``prefix-nnode2Ipv4-i1.tr'' with traces for each interface in the respective
-trace file. Since all of the EnableAscii functions are overloaded to take a
-stream wrapper, you can use that form as well:
-
-@verbatim
- Names::Add ("node1Ipv4" ...);
- Names::Add ("node2Ipv4" ...);
- ...
- Ptr<OutputStreamWrapper> stream = asciiTraceHelper.CreateFileStream ("trace-file-name.tr");
- ...
- helper.EnableAsciiIpv4 (stream, "node1Ipv4", 1);
- helper.EnableAsciiIpv4 (stream, "node2Ipv4", 1);
-@end verbatim
-
-This would result in a single trace file called ``trace-file-name.tr'' that
-contains all of the trace events for both interfaces. The events would be
-disambiguated by trace context strings.
-
-You can enable ascii tracing on a collection of protocol/interface pairs by
-providing an @code{Ipv4InterfaceContainer}. For each protocol of the proper
-type (the same type as is managed by the device helper), tracing is enabled
-for the corresponding interface. Again, the @code{Node} is implicit since
-there is a one-to-one correspondence between each protocol and its node.
-For example,
-
-@verbatim
- NodeContainer nodes;
- ...
- NetDeviceContainer devices = deviceHelper.Install (nodes);
- ...
- Ipv4AddressHelper ipv4;
- ipv4.SetBase ("10.1.1.0", "255.255.255.0");
- Ipv4InterfaceContainer interfaces = ipv4.Assign (devices);
- ...
- ...
- helper.EnableAsciiIpv4 ("prefix", interfaces);
-@end verbatim
-
-This would result in a number of ascii trace files being created, each of which
-follows the <prefix>-n<node id>-i<interface>.tr convention. Combining all of the
-traces into a single file is accomplished similarly to the examples above:
-
-@verbatim
- NodeContainer nodes;
- ...
- NetDeviceContainer devices = deviceHelper.Install (nodes);
- ...
- Ipv4AddressHelper ipv4;
- ipv4.SetBase ("10.1.1.0", "255.255.255.0");
- Ipv4InterfaceContainer interfaces = ipv4.Assign (devices);
- ...
- Ptr<OutputStreamWrapper> stream = asciiTraceHelper.CreateFileStream ("trace-file-name.tr");
- ...
- helper.EnableAsciiIpv4 (stream, interfaces);
-@end verbatim
-
-You can enable ascii tracing on a collection of protocol/interface pairs by
-providing a @code{NodeContainer}. For each @code{Node} in the @code{NodeContainer}
-the appropriate protocol is found. For each protocol, its interfaces are
-enumerated and tracing is enabled on the resulting pairs. For example,
-
-@verbatim
- NodeContainer n;
- ...
- helper.EnableAsciiIpv4 ("prefix", n);
-@end verbatim
-
-This would result in a number of ascii trace files being created, each of which
-follows the <prefix>-<node id>-<device id>.tr convention. Combining all of the
-traces into a single file is accomplished similarly to the examples above:
-
-You can enable pcap tracing on the basis of node ID and device ID as well. In
-this case, the node-id is translated to a @code{Ptr<Node>} and the appropriate
-protocol is looked up in the node. The resulting protocol and interface are
-used to specify the resulting trace source.
-
-@verbatim
- helper.EnableAsciiIpv4 ("prefix", 21, 1);
-@end verbatim
-
-Of course, the traces can be combined into a single file as shown above.
-
-Finally, you can enable ascii tracing for all interfaces in the system, with
-associated protocol being the same type as that managed by the device helper.
-
-@verbatim
- helper.EnableAsciiIpv4All ("prefix");
-@end verbatim
-
-This would result in a number of ascii trace files being created, one for
-every interface in the system related to a protocol of the type managed by the
-helper. All of these files will follow the <prefix>-n<node id>-i<interface.tr
-convention. Combining all of the traces into a single file is accomplished
-similarly to the examples above.
-
-@subsubsection Ascii Tracing Device Helper Filename Selection
-
-Implicit in the prefix-style method descriptions above is the construction of the
-complete filenames by the implementation method. By convention, ascii traces
-in the @code{ns-3} system are of the form ``<prefix>-<node id>-<device id>.tr''
-
-As previously mentioned, every node in the system will have a system-assigned
-node id. Since there is a one-to-one correspondence between protocols and nodes
-we use to node-id to identify the protocol identity. Every interface on a
-given protocol will have an interface index (also called simply an interface)
-relative to its protocol. By default, then, an ascii trace file created as a result
-of enabling tracing on the first device of node 21, using the prefix ``prefix'',
-would be ``prefix-n21-i1.tr''. Use the prefix to disambiguate multiple protocols
-per node.
-
-You can always use the @code{ns-3} object name service to make this more clear.
-For example, if you use the object name service to assign the name ``serverIpv4''
-to the protocol on node 21, and also specify interface one, the resulting ascii
-trace file name will automatically become, ``prefix-nserverIpv4-1.tr''.
-
-@node Tracing implementation details
-@section Implementation details
--- a/doc/manual/troubleshoot.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,98 +0,0 @@
-@node Troubleshooting
-@chapter Troubleshooting
-
-This chapter posts some information about possibly common errors in building
-or running ns-3 programs.
-
-@menu
-* Build errors::
-* Run-time errors::
-@end menu
-
-Please note that the wiki @*
-(@uref{http://www.nsnam.org/wiki/index.php/Troubleshooting})
-may have contributed items.
-
-@node Build errors
-@section Build errors
-
-@node Run-time errors
-@section Run-time errors
-
-Sometimes, errors can occur with a program after a successful build. These
-are run-time errors, and can commonly occur when memory is corrupted or
-pointer values are unexpectedly null.
-
-Here is an example of what might occur:
-
-@smallformat
-@example
-ns-old:~/ns-3-nsc$ ./waf --run tcp-point-to-point
-Entering directory `/home/tomh/ns-3-nsc/build'
-Compilation finished successfully
-Command ['/home/tomh/ns-3-nsc/build/debug/examples/tcp-point-to-point'] exited with code -11
-@end example
-@end smallformat
-
-The error message says that the program terminated unsuccessfully, but it is
-not clear from this information what might be wrong. To examine more
-closely, try running it under the @uref{http://sources.redhat.com/gdb/,,gdb debugger}:
-
-@smallformat
-@example
-ns-old:~/ns-3-nsc$ ./waf --run tcp-point-to-point --command-template="gdb %s"
-Entering directory `/home/tomh/ns-3-nsc/build'
-Compilation finished successfully
-GNU gdb Red Hat Linux (6.3.0.0-1.134.fc5rh)
-Copyright 2004 Free Software Foundation, Inc.
-GDB is free software, covered by the GNU General Public License, and you are
-welcome to change it and/or distribute copies of it under certain conditions.
-Type "show copying" to see the conditions.
-There is absolutely no warranty for GDB. Type "show warranty" for details.
-This GDB was configured as "i386-redhat-linux-gnu"...Using host libthread_db
-library "/lib/libthread_db.so.1".
-
-(gdb) run
-Starting program: /home/tomh/ns-3-nsc/build/debug/examples/tcp-point-to-point
-Reading symbols from shared object read from target memory...done.
-Loaded system supplied DSO at 0xf5c000
-
-Program received signal SIGSEGV, Segmentation fault.
-0x0804aa12 in main (argc=1, argv=0xbfdfefa4)
- at ../examples/tcp-point-to-point.cc:136
-136 Ptr<Socket> localSocket = socketFactory->CreateSocket ();
-(gdb) p localSocket
-$1 = @{m_ptr = 0x3c5d65@}
-(gdb) p socketFactory
-$2 = @{m_ptr = 0x0@}
-(gdb) quit
-The program is running. Exit anyway? (y or n) y
-@end example
-@end smallformat
-
-Note first the way the program was invoked-- pass the command to run as
-an argument to the command template "gdb %s".
-
-This tells us that there was an attempt to dereference a null pointer
-socketFactory.
-
-Let's look around line 136 of tcp-point-to-point, as gdb suggests:
-@smallformat
-@example
- Ptr<SocketFactory> socketFactory = n2->GetObject<SocketFactory> (Tcp::iid);
- Ptr<Socket> localSocket = socketFactory->CreateSocket ();
- localSocket->Bind ();
-@end example
-@end smallformat
-
-The culprit here is that the return value of GetObject is not being
-checked and may be null.
-
-Sometimes you may need to use the @uref{http://valgrind.org,,valgrind memory
-checker} for more subtle errors. Again, you invoke the use of valgrind
-similarly:
-@smallformat
-@example
-ns-old:~/ns-3-nsc$ ./waf --run tcp-point-to-point --command-template="valgrind %s"
-@end example
-@end smallformat
--- a/doc/manual/wifi.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,458 +0,0 @@
-@node Wifi NetDevice
-@chapter Wifi NetDevice
-@anchor{chap:wifi}
-
-ns-3 nodes can contain a collection of NetDevice objects, much like an actual
-computer contains separate interface cards for Ethernet, Wifi, Bluetooth, etc. This chapter describes the ns-3 WifiNetDevice and related models. By
-adding WifiNetDevice objects to ns-3 nodes, one can create models of
-802.11-based infrastructure and ad hoc networks.
-
-@menu
-* Overview of the model::
-* Using the WifiNetDevice::
-* The WifiChannel and WifiPhy models::
-* The MAC model::
-* Wifi Attributes::
-* Wifi Tracing::
-@end menu
-
-@node Overview of the model
-@section Overview of the model
-
-The WifiNetDevice models a wireless network interface controller based
-on the IEEE 802.11 standard. We will go into more detail below but in brief,
-ns-3 provides models for these aspects of 802.11:
-@itemize @bullet
-@item basic 802.11 DCF with @strong{infrastructure} and @strong{adhoc} modes
-@item @strong{802.11a} and @strong{802.11b} physical layers
-@item QoS-based EDCA and queueing extensions of @strong{802.11e}
-@item various propagation loss models including @strong{Nakagami, Rayleigh, Friis, LogDistance, FixedRss, Random}
-@item two propagation delay models, a distance-based and random model
-@item various rate control algorithms including @strong{Aarf, Arf, Cara, Onoe, Rraa, ConstantRate, and Minstrel}
-@item 802.11s (mesh), described in another chapter
-@end itemize
-
-The set of 802.11 models provided in ns-3 attempts to provide
-an accurate MAC-level implementation of the 802.11 specification
-and to provide a not-so-slow PHY-level model of the 802.11a
-specification.
-
-The implementation is modular and provides roughly four levels of models:
-@itemize @bullet
-@item the @strong{PHY layer models}
-@item the so-called @strong{MAC low models}: they implement DCF and EDCAF
-@item the so-called @strong{MAC high models}: they implement the MAC-level
-beacon generation, probing, and association state machines, and
-@item a set of @strong{Rate control algorithms} used by the MAC low models
-@end itemize
-
-There are presently three @strong{MAC high models} that provide for
-the three (non-mesh; the mesh equivalent, which is a sibling of these
-with common parent @code{ns3::RegularWifiMac}, is not discussed here)
-Wi-Fi topological elements - Access Point (AP) (implemented in class
-@code{ns3::ApWifiMac}), non-AP Station (STA) (@code{ns3::StaWifiMac}),
-and STA in an Independent Basic Service Set (IBSS - also commonly
-referred to as an ad hoc network) (@code{ns3::AdhocWifiMac}).
-
-The simplest of these is @code{ns3::AdhocWifiMac}, which implements a
-Wi-Fi MAC that does not perform any kind of beacon generation,
-probing, or association. The @code{ns3::StaWifiMac} class implements
-an active probing and association state machine that handles automatic
-re-association whenever too many beacons are missed. Finally,
-@code{ns3::ApWifiMac} implements an AP that generates periodic
-beacons, and that accepts every attempt to associate.
-
-These three MAC high models share a common parent in
-@code{ns3::RegularWifiMac}, which exposes, among other MAC
-configuration, an attribute (@code{QosSupported}) that allows
-configuration of 802.11e/WMM-style QoS support. With QoS-enabled MAC
-models it is possible to work with traffic belonging to four different
-Access Categories (ACs): @strong{AC_VO} for voice traffic,
-@strong{AC_VI} for video traffic, @strong{AC_BE} for best-effort
-traffic and @strong{AC_BK} for background traffic. In order for the
-MAC to determine the appropriate AC for an MSDU, packets forwarded
-down to these MAC layers should be marked using @code{ns3::QosTag} in
-order to set a TID (traffic id) for that packet otherwise it will be
-considered belonging to @strong{AC_BE}.
-
-The @strong{MAC low layer} is split into three components:
-@enumerate
-@item @code{ns3::MacLow} which takes care of RTS/CTS/DATA/ACK transactions.
-@item @code{ns3::DcfManager} and @code{ns3::DcfState} which implements the DCF and EDCAF functions.
-@item @code{ns3::DcaTxop} and @code{ns3::EdcaTxopN} which handle the packet queue,
-packet fragmentation, and packet retransmissions if they are needed.
-The @code{ns3::DcaTxop} object is used by high MACs that are not
-QoS-enabled, and for transmission of frames (e.g., of type Management)
-that the standard says should access the medium using the
-DCF. @code{ns3::EdcaTxopN} is used by QoS-enabled high MACs and also
-performs QoS operations like 802.11n-style MSDU aggregation.
-@end enumerate
-
-There are also several @strong{rate control algorithms} that can be used by the Mac low layer:
-@itemize @bullet
-@item @code{ns3::ArfMacStations}
-@item @code{ns3::AArfMacStations}
-@item @code{ns3::IdealMacStations}
-@item @code{ns3::CrMacStations}
-@item @code{ns3::OnoeMacStations}
-@item @code{ns3::AmrrMacStations}
-@end itemize
-
-The PHY layer implements a single model in the
-@code{ns3::WifiPhy class}: the
-physical layer model implemented there is described fully in a paper
-entitled @uref{http://cutebugs.net/files/wns2-yans.pdf,,"Yet Another Network Simulator"}. Validation results for 802.11b are available in this
-@uref{http://www.nsnam.org/~pei/80211b.pdf,,technical report}.
-
-In ns-3, nodes can have multiple WifiNetDevices on separate channels,
-and the WifiNetDevice can coexist with other device types; this removes
-an architectural limitation found in ns-2. Presently, however, there
-is no model for cross-channel interference or coupling.
-
-The source code for the Wifi NetDevice lives in the directory
-@code{src/devices/wifi}.
-
-@float Figure,fig:WifiArchitecture
-@caption{Wifi NetDevice architecture.}
-@image{../WifiArchitecture,5in}
-@end float
-
-@node Using the WifiNetDevice
-@section Using the WifiNetDevice
-
-The modularity provided by the implementation makes low-level
-configuration of the WifiNetDevice powerful but complex. For this reason,
-we provide some helper classes to perform common operations in a simple
-matter, and leverage the ns-3 attribute system to allow users to control
-the parametrization of the underlying models.
-
-Users who use the low-level ns-3 API and who wish to add a WifiNetDevice
-to their node must create an instance of a WifiNetDevice, plus
-a number of constituent objects, and bind them together appropriately
-(the WifiNetDevice is very modular in this regard, for future
-extensibility). At the low-level API, this can be done
-with about 20 lines of code (see @code{ns3::WifiHelper::Install}, and
-@code{ns3::YansWifiPhyHelper::Create}). They also must create,
-at some point, a WifiChannel, which also contains a number of
-constituent objects (see @code{ns3::YansWifiChannelHelper::Create}).
-
-However, a few helpers are available for users to add these devices
-and channels with only a few lines of code, if they are willing to
-use defaults, and the helpers provide additional API to allow the
-passing of attribute values to change default values. The scripts
-in @code{src/examples} can be browsed to see how this is done.
-
-@subsection YansWifiChannelHelper
-
-The YansWifiChannelHelper has an unusual name. Readers may wonder why
-it is named this way. The reference is to the
-@uref{http://cutebugs.net/files/wns2-yans.pdf,,yans simulator},
-from which this model is taken. The helper can be used to create
-a WifiChannel with a default PropagationLoss and PropagationDelay model.
-Specifically, the default is a channel model
-with a propagation delay equal to a constant, the speed of light,
-and a propagation loss based on a log distance model with a reference
-loss of 46.6777 dB at reference distance of 1m.
-
-Users will typically type code such as:
-@smallformat
-@example
- YansWifiChannelHelper wifiChannelHelper = YansWifiChannelHelper::Default ();
- Ptr<WifiChannel> wifiChannel = wifiChannelHelper.Create ();
-@end example
-@end smallformat
-to get the defaults. Note the distinction above in creating a helper
-object vs. an actual simulation object.
-In ns-3, helper objects (used at the helper API only) are created on the
-stack (they could also be created with operator new and later deleted).
-However, the actual ns-3 objects typically inherit from
-@code{class ns3::Object} and are assigned to a smart pointer. See the
-chapter on
-@uref{Object model} for a discussion of the ns-3 object model, if you
-are not familiar with it.
-
-@emph{Todo: Add notes about how to configure attributes with this helper API}
-
-@subsection YansWifiPhyHelper
-
-Physical devices (base class @code{ns3::Phy}) connect to
-@code{ns3::Channel} models in ns-3. We need to create Phy objects appropriate
-for the YansWifiChannel; here the @code{YansWifiPhyHelper} will
-do the work.
-
-The YansWifiPhyHelper class configures an object factory to create instances
-of a @code{YansWifiPhy} and
-adds some other objects to it, including possibly a supplemental
-ErrorRateModel and a pointer to a MobilityModel. The user code is
-typically:
-@verbatim
- YansWifiPhyHelper wifiPhyHelper = YansWifiPhyHelper::Default ();
- wifiPhyHelper.SetChannel (wifiChannel);
-@end verbatim
-Note that we haven't actually created any WifiPhy objects yet; we've
-just prepared the YansWifiPhyHelper by telling it which channel it is
-connected to. The phy objects are created in the next step.
-
-@subsection NqosWifiMacHelper and QosWifiMacHelper
-
-The @code{ns3::NqosWifiMacHelper} and @code{ns3::QosWifiMacHelper}
-configure an object factory to create instances of a
-@code{ns3::WifiMac}. They are used to configure MAC parameters like
-type of MAC.
-
-The former, @code{ns3::NqosWifiMacHelper}, supports creation of MAC
-instances that do not have 802.11e/WMM-style QoS support enabled.
-
-For example, the following user code configures a non-QoS MAC that
-will be a non-AP STA in an infrastructure network where the AP has
-SSID ``ns-3-ssid''.
-
-@smallformat
-@example
- NqosWifiMacHelper wifiMacHelper = NqosWifiMacHelper::Default ();
- Ssid ssid = Ssid ("ns-3-ssid");
- wifiMacHelper.SetType ("ns3::StaWifiMac",
- "Ssid", SsidValue (ssid),
- "ActiveProbing", BooleanValue (false));
-@end example
-@end smallformat
-
-To create MAC instances with QoS support enabled,
-@code{ns3::QosWifiMacHelper} is used in place of
-@code{ns3::NqosWifiMacHelper}. This object can be also used to set:
-
-@itemize @bullet
-@item a MSDU aggregator for a particular Access Category (AC) in order to use 802.11n MSDU aggregation feature;
-@item block ack parameters like threshold (number of packets for which block ack mechanism should be used) and inactivity timeout.
-@end itemize
-
-The following code shows an example use of
-@code{ns3::QosWifiMacHelper} to create an AP with QoS enabled,
-aggregation on AC_VO, and Block Ack on AC_BE:
-
-@smallformat
-@example
- QosWifiMacHelper wifiMacHelper = QosWifiMacHelper::Default ();
- wifiMacHelper.SetType ("ns3::ApWifiMac",
- "Ssid", SsidValue (ssid),
- "BeaconGeneration", BooleanValue (true),
- "BeaconInterval", TimeValue (Seconds (2.5)));
- wifiMacHelper.SetMsduAggregatorForAc (AC_VO, "ns3::MsduStandardAggregator",
- "MaxAmsduSize", UintegerValue (3839));
- wifiMacHelper.SetBlockAckThresholdForAc (AC_BE, 10);
- wifiMacHelper.SetBlockAckInactivityTimeoutForAc (AC_BE, 5);
-@end example
-@end smallformat
-
-@subsection WifiHelper
-
-We're now ready to create WifiNetDevices. First, let's create
-a WifiHelper with default settings:
-@verbatim
- WifiHelper wifiHelper = WifiHelper::Default ();
-@end verbatim
-What does this do? It sets the RemoteStationManager to
-@code{ns3::ArfWifiManager}.
-Now, let's use the wifiPhyHelper and wifiMacHelper created above to install WifiNetDevices
-on a set of nodes in a NodeContainer "c":
-@smallformat
-@example
- NetDeviceContainer wifiContainer = WifiHelper::Install (wifiPhyHelper, wifiMacHelper, c);
-@end example
-@end smallformat
-This creates the WifiNetDevice which includes also a WifiRemoteStationManager,
-a WifiMac, and a WifiPhy (connected to the matching WifiChannel).
-
-There are many ns-3 @uref{Attributes} that can be set on the above
-helpers to deviate from the default behavior; the example scripts
-show how to do some of this reconfiguration.
-
-@subsection AdHoc WifiNetDevice configuration
-This is a typical example of how a user might configure an adhoc network.
-
-@cartouche
-To be completed
-@end cartouche
-
-@subsection Infrastructure (Access Point and clients) WifiNetDevice configuration
-This is a typical example of how a user might configure an access point and a set of clients.
-
-@cartouche
-To be completed
-@end cartouche
-
-@node The WifiChannel and WifiPhy models
-@section The WifiChannel and WifiPhy models
-
-The WifiChannel subclass can be used to connect together a set of
-@code{ns3::WifiNetDevice} network interfaces. The class @code{ns3::WifiPhy}
-is the
-object within the WifiNetDevice that receives bits from the channel.
-A WifiChannel contains
-a @code{ns3::PropagationLossModel} and a @code{ns3::PropagationDelayModel}
-which can
-be overridden by the WifiChannel::SetPropagationLossModel
-and the WifiChannel::SetPropagationDelayModel methods. By default,
-no propagation models are set.
-
-The WifiPhy models an 802.11a channel, in terms of frequency, modulation,
-and bit rates, and interacts with the PropagationLossModel and
-PropagationDelayModel found in the channel.
-
-This section summarizes
-the description of the BER calculations found in the yans paper
-taking into account the
-Forward Error Correction present in 802.11a and describes
-the algorithm we implemented to decide whether or not a
-packet can be successfully received. See @uref{http://cutebugs.net/files/wns2-yans.pdf,,"Yet Another Network Simulator"} for more details.
-
-The PHY layer can be in one of three states:
-@enumerate
-@item TX: the PHY is currently transmitting a signal
-on behalf of its associated MAC
-@item RX: the PHY is synchronized on a signal and
-is waiting until it has received its last bit to forward
-it to the MAC.
-@item IDLE: the PHY is not in the TX or RX states.
-@end enumerate
-
-When the first bit of a new packet is received while
-the PHY is not IDLE (that is, it is already synchronized
-on the reception of another earlier packet or it is
-sending data itself), the received packet is dropped.
-Otherwise, if the PHY is IDLE, we calculate the received
-energy of the first bit of this new signal and compare it
-against our Energy Detection threshold (as defined
-by the Clear Channel Assessment function mode 1).
-If the energy of the packet k is higher, then the PHY moves
-to RX state and schedules an event when the last bit of
-the packet is expected to be received. Otherwise, the
-PHY stays in IDLE state and drops the packet.
-
-The energy of the received signal is assumed
-to be zero outside of the reception interval of packet k and
-is calculated from the transmission power with a path-loss
-propagation model in the reception interval.
-where the path loss exponent, @math{n}, is chosen equal to 3,
-the reference distance, @math{d_0} is choosen equal to
-@math{1.0m} and
-the reference energy is based based on a Friis
-propagation model.
-
-When the last bit of the packet upon which the PHY is
-synchronized is received, we need to calculate the
-probability that the packet is received with any error
-to decide whether or not
-the packet on which we were synchronized could
-be successfully received or not: a random number
-is drawn from a uniform distribution and is compared against
-the probability of error.
-
-To evaluate the probability of error, we start from the piecewise linear
-functions shown in Figure @ref{fig:snir} and calculate the
-SNIR function.
-
-@float Figure,fig:snir
-@caption{SNIR function over time}
-@image{figures/snir,,3in}
-@end float
-
-From the SNIR function we can derive bit error rates for BPSK and QAM
-modulations. Then, for each interval l where BER is
-constant, we define the upper bound of a probability that an error is
-present in the chunk of bits located in the interval l for packet k.
-If we assume an AWGN channel,
-binary convolutional coding (which is the case in 802.11a)
-and hard-decision Viterbi decoding, the error rate is thus derived,
-and the packet error probability for packet k can be computed..
-
-@subsection WifiChannel configuration
-
-WifiChannel models include both a PropagationDelayModel and a
-PropagationLossModel. The following PropagationDelayModels are available:
-@itemize @bullet
-@item ConstantSpeedPropagationDelayModel
-@item RandomPropagationDelayModel
-@end itemize
-
-The following PropagationLossModels are available:
-@itemize @bullet
-@item RandomPropagationLossModel
-@item FriisPropagationLossModel
-@item LogDistancePropagationLossModel
-@item JakesPropagationLossModel
-@item CompositePropagationLossModel
-@end itemize
-
-@node The MAC model
-@section The MAC model
-
-The 802.11 Distributed Coordination Function is used to
-calculate when to grant access to the transmission medium. While
-implementing the DCF would have been particularly easy if we
-had used a recurring timer that expired every slot, we
-chose to use the method described in @emph{(missing reference here from
-Yans paper)}
-where the backoff timer duration is lazily calculated whenever
-needed since it is claimed to have much better performance than
-the simpler recurring timer solution.
-
-The higher-level MAC functions are implemented in a set of other
-C++ classes and deal with:
-@itemize @bullet
-@item packet fragmentation and defragmentation,
-@item use of the rts/cts protocol,
-@item rate control algorithm,
-@item connection and disconnection to and from an Access Point,
-@item the MAC transmission queue,
-@item beacon generation,
-@item msdu aggregation,
-@item etc.
-@end itemize
-
-@node Wifi Attributes
-@section Wifi Attributes
-
-The WifiNetDevice makes heavy use of the ns-3 @ref{Attributes} subsystem for
-configuration and default value management. Presently, approximately
-100 values are stored in this system.
-
-For instance, class @code{ns-3::WifiMac} exports these attributes:
-@itemize @bullet
-@item CtsTimeout: When this timeout expires, the RTS/CTS handshake has failed.
-@item AckTimeout: When this timeout expires, the DATA/ACK handshake has failed.
-@item Sifs: The value of the SIFS constant.
-@item EifsNoDifs: The value of EIFS-DIFS
-@item Slot: The duration of a Slot.
-@item Pifs: The value of the PIFS constant.
-@item MaxPropagationDelay: The maximum propagation delay. Unused for now.
-@item MaxMsduSize: The maximum size of an MSDU accepted by the MAC layer.This value conforms to the specification.
-@item Ssid: The ssid we want to belong to.
-@end itemize
-
-@node Wifi Tracing
-@section Wifi Tracing
-
-@emph{This needs revised/updating based on the latest Doxygen}
-
-ns-3 has a sophisticated tracing infrastructure that allows users to hook
-into existing trace sources, or to define and export new ones.
-
-Wifi-related trace sources that are available by default include:
-@itemize @bullet
-@item @code{ns3::WifiNetDevice}
-@itemize @bullet
-@item Rx: Received payload from the MAC layer.
-@item Tx: Send payload to the MAC layer.
-@end itemize
-@item @code{ns3::WifiPhy}
-@itemize @bullet
-@item State: The WifiPhy state
-@item RxOk: A packet has been received successfully.
-@item RxError: A packet has been received unsuccessfully.
-@item Tx: Packet transmission is starting.
-@end itemize
-@end itemize
-Briefly, this means, for example, that a user can hook a processing
-function to the "State" tracing hook above and be notified whenever the
-WifiPhy model changes state.
--- a/doc/manual/wimax.texi Thu Dec 30 22:39:53 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,538 +0,0 @@
-@node Wimax NetDevice
-@chapter Wimax NetDevice
-@anchor{chap:wimax}
-
-This chapter describes the ns-3 WimaxNetDevice and related models. By
-adding WimaxNetDevice objects to ns-3 nodes, one can create models of
-802.16-based networks. Below, we list some more details about what
-the ns-3 WiMAX models cover but, in summary, the most important features
-of the ns-3 model are:
-@itemize @bullet
-@item a scalable and realistic physical layer and channel model
-@item a packet classifier for the IP convergence sublayer
-@item efficient uplink and downlink schedulers
-@item support for Multicast and Broadcast Service (MBS), and
-@item packet tracing functionality
-@end itemize
-
-The source code for the WiMAX models lives in the directory
-@code{src/devices/wimax}.
-
-There have been two academic papers published on this model:
-@itemize @bullet
-@item M.A. Ismail, G. Piro, L.A. Grieco, and T. Turletti, "An Improved
-IEEE 802.16 WiMAX Module for the NS-3 Simulator", SIMUTools 2010 Conference,
-March 2010.
-@item J. Farooq and T. Turletti, "An IEEE 802.16 WiMAX module for the NS-3
-Simulator," SIMUTools 2009 Conference, March 2009.
-@end itemize
-
-@menu
-* Scope of the model::
-* Using the Wimax models::
-* Wimax Attributes::
-* Wimax Tracing::
-* Wimax MAC model::
-* WimaxChannel and WimaxPhy models::
-* Channel model::
-* Physical model::
-@end menu
-
-@node Scope of the model
-@section Scope of the model
-
-From a MAC perspective, there are two basic modes of operation, that
-of a Subscriber Station (SS) or a Base Station (BS). These are implemented
-as two subclasses of the base class @code{ns3::NetDevice},
-@code{class SubscriberStationNetDevice} and @code{class BaseStationNetDevice}.
-As is typical in ns-3, there is also a physical layer class
-@code{class WimaxPhy} and a channel class @code{class WimaxChannel} which
-serves to hold the references to all of the attached Phy devices. The main
-physical layer class is the @code{SimpleOfdmWimaxChannel} class.
-
-Another important aspect of WiMAX is the uplink and downlink scheduler,
-and there are three primary scheduler types implemented:
-@itemize @bullet
-@item SIMPLE: a simple priority based FCFS scheduler
-@item RTPS: a real-time polling service (rtPS) scheduler
-@item MBQOS: a migration-based uplink scheduler
-@end itemize
-
-The following additional aspects of the 802.16 specifications, as
-well as physical layer and channel models, are modelled:
-@itemize @bullet
-@item leverages existing ns-3 wireless propagation loss and delay models,
-as well as ns-3 mobility models
-@item Point-to-Multipoint (PMP) mode and the WirelessMAN-OFDM PHY layer
-@item Initial Ranging
-@item Service Flow Initialization
-@item Management Connection
-@item Transport Initialization
-@item UGS, rtPS, nrtPS, and BE connections
-@end itemize
-
-The following aspects are not presently modelled but would be good topics
-for future extensions:
-@itemize @bullet
-@item OFDMA PHY layer
-@item Link adaptation
-@item Mesh topologies
-@item ARQ
-@item ertPS connection
-@item packet header suppression
-@end itemize
-
-@node Using the Wimax models
-@section Using the Wimax models
-
-The main way that users who write simulation scripts will typically
-interact with the Wimax models is through the helper API and through
-the publicly visible attributes of the model.
-
-The helper API is defined in @code{src/helper/wimax-helper.@{cc,h@}}.
-
-The example @code{examples/wimax/wimax-simple.cc} contains some basic
-code that shows how to set up the model:
-
-@smallformat
-@example
- switch (schedType)
- @{
- case 0:
- scheduler = WimaxHelper::SCHED_TYPE_SIMPLE;
- break;
- case 1:
- scheduler = WimaxHelper::SCHED_TYPE_MBQOS;
- break;
- case 2:
- scheduler = WimaxHelper::SCHED_TYPE_RTPS;
- break;
- default:
- scheduler = WimaxHelper::SCHED_TYPE_SIMPLE;
- @}
-
- NodeContainer ssNodes;
- NodeContainer bsNodes;
-
- ssNodes.Create (2);
- bsNodes.Create (1);
-
- WimaxHelper wimax;
-
- NetDeviceContainer ssDevs, bsDevs;
-
- ssDevs = wimax.Install (ssNodes,
- WimaxHelper::DEVICE_TYPE_SUBSCRIBER_STATION,
- WimaxHelper::SIMPLE_PHY_TYPE_OFDM,
- scheduler);
- bsDevs = wimax.Install (bsNodes, WimaxHelper::DEVICE_TYPE_BASE_STATION, WimaxHelper::SIMPLE_PHY_TYPE_OFDM, scheduler);
-@end example
-@end smallformat
-
-This example shows that there are two subscriber stations and one base
-station created. The helper method @code{Install} allows the user to
-specify the scheduler type, the physical layer type, and the device type.
-
-Different variants of @code{Install} are available; for instance, the
-example @code{examples/wimax/wimax-multicast.cc} shows how to specify a
-non-default channel or propagation model:
-
-@smallformat
-@example
- channel = CreateObject<SimpleOfdmWimaxChannel> ();
- channel->SetPropagationModel (SimpleOfdmWimaxChannel::COST231_PROPAGATION);
- ssDevs = wimax.Install (ssNodes,
- WimaxHelper::DEVICE_TYPE_SUBSCRIBER_STATION,
- WimaxHelper::SIMPLE_PHY_TYPE_OFDM,
- channel,
- scheduler);
- Ptr<WimaxNetDevice> dev = wimax.Install (bsNodes.Get (0),
- WimaxHelper::DEVICE_TYPE_BASE_STATION,
- WimaxHelper::SIMPLE_PHY_TYPE_OFDM,
- channel,
- scheduler);
-@end example
-@end smallformat
-
-Mobility is also supported in the same way as in Wifi models; see the
-@code{examples/wimax/wimax-multicast.cc}.
-
-Another important concept in WiMAX is that of a service flow. This is a
-unidirectional flow of packets with a set of QoS parameters such as
-traffic priority, rate, scheduling type, etc. The base station is
-responsible for issuing service flow identifiers and mapping them to
-WiMAX connections. The following
-code from @code{examples/wimax/wimax-multicast.cc} shows how this
-is configured from a helper level:
-
-@smallformat
-@example
- ServiceFlow MulticastServiceFlow = wimax.CreateServiceFlow (ServiceFlow::SF_DIRECTION_DOWN,
- ServiceFlow::SF_TYPE_UGS,
- MulticastClassifier);
-
- bs->GetServiceFlowManager ()->AddMulticastServiceFlow (MulticastServiceFlow, WimaxPhy::MODULATION_TYPE_QPSK_12);
-@end example
-@end smallformat
-
-
-@node Wimax Attributes
-@section Wimax Attributes
-
-The WimaxNetDevice makes heavy use of the ns-3 @ref{Attributes} subsystem for
-configuration and default value management. Presently, approximately
-60 values are stored in this system.
-
-For instance, class @code{ns-3::SimpleOfdmWimaxPhy} exports these attributes:
-@itemize @bullet
-@item NoiseFigure: Loss (dB) in the Signal-to-Noise-Ratio due to non-idealities in the receiver.
-@item TxPower: Transmission power (dB)
-@item G: The ratio of CP time to useful time
-@item txGain: Transmission gain (dB)
-@item RxGain: Reception gain (dB)
-@item Nfft: FFT size
-@item TraceFilePath: Path to the directory containing SNR to block error rate files
-@end itemize
-
-For a full list of attributes in these models, consult the Doxygen page
-that lists all attributes for ns-3.
-
-@node Wimax Tracing
-@section Wimax Tracing
-
-ns-3 has a sophisticated tracing infrastructure that allows users to hook
-into existing trace sources, or to define and export new ones.
-
-Many ns-3 users use the built-in Pcap or Ascii tracing, and the
-WimaxHelper has similar APIs:
-@smallformat
-@example
-AsciiTraceHelper ascii;
-WimaxHelper wimax;
-wimax.EnablePcap ("wimax-program", false);
-wimax.EnableAsciiAll (ascii.CreateFileStream ("wimax-program.tr");
-@end example
-@end smallformat
-
-Unlike other helpers, there is also a special
-@code{EnableAsciiForConnection()} method that limits the ascii tracing
-to a specific device and connection.
-
-These helpers access the low level trace sources that exist in the
-WiMAX physical layer, net device, and queue models. Like other
-ns-3 trace sources, users may hook their own functions to these
-trace sources if they want to do customized things based on the
-packet events. See the Doxygen List of trace sources for a
-complete list of these sources.
-
-@node Wimax MAC model
-@section Wimax MAC model
-
-The 802.16 model provided in ns-3 attempts to provide an accurate MAC and
-PHY level implementation of the 802.16 specification with the
-Point-to-Multipoint (PMP) mode and the WirelessMAN-OFDM PHY layer.
-The model is mainly composed of three layers:
-@itemize @bullet
-@item The convergence sublayer (CS)
-@item The MAC CP Common Part Sublayer (MAC-CPS)
-@item Physical (PHY) layer
-@end itemize
-
-The following figure @ref{fig:WimaxArchitecture} shows the relationships
-of these models.
-@float Figure,fig:WimaxArchitecture
-@caption{ns-3 WiMAX architecture.}
-@image{../WimaxArchitecture,5in}
-@end float
-
-@subsection the Convergence Sublayer
-
-The Convergence sublayer (CS) provided with this module implements
-the Packet CS, designed to work with the packet-based protocols at higher
-layers. The CS is responsible of receiving packet from the higher layer and
-from peer stations, classifying packets to appropriate connections (or
-service flows) and processing packets. It keeps a mapping of transport
-connections to service flows. This enables the MAC CPS identifying the Quality
-of Service (QoS) parameters associated to a transport connection and ensuring
-the QoS requirements. The CS currently employs an IP classifier.
-
-@subsection IP Packet Classifier
-
-An IP packet classifier is used to map incoming packets to appropriate
-connections based on a set of criteria. The classifier maintains a list of
-mapping rules which associate an IP flow (src IP address and mask, dst IP address
-and mask, src port range, dst port range and protocol) to one of the service flows.
-By analyzing the IP and the TCP/UDP headers the classifier will append the incoming
-packet (from the upper layer) to the queue of the appropriate WiMAX connection.
-@code{class IpcsClassifier} and @code{class IpcsClassifierRecord} implement the classifier module for
-both SS and BS
-
-@subsection MAC Common Part Sublayer
-
-The MAC Common Part Sublayer (CPS) is the main sublayer of the IEEE 802.16
-MAC and performs the fundamental functions of the MAC. The module implements
-the Point-Multi-Point (PMP) mode. In PMP mode BS is responsible of managing
-communication among multiple SSs. The key functionalities of the MAC CPS
-include framing and addressing, generation of MAC management messages, SS
-initialization and registration, service flow management, bandwidth
-management and scheduling services.
-@code{Class WimaxNetDevice} represents the MAC layer of a WiMAX network device.
-This class extends the @code{class NetDevice} of the ns-3 API that provides
-abstraction of a network device. @code{class WimaxNetDevice} is further extended by
-@code{class BaseStationNetDevice} and @code{class SubscriberStationNetDevice}, defining MAC
-layers of BS and SS, respectively. Besides these main classes, the key
-functions of MAC are distributed to several other classes.
-
-@subsection Framing and Management Messages
-
-The module implements a frame as a fixed duration of time, i.e., frame
-boundaries are defined with respect to time. Each frame is further
-subdivided into downlink (DL) and uplink (UL) subframes. The module implements
-the Time Division Duplex (TDD) mode where DL and UL operate on same frequency
-but are separated in time. A number of DL and UL bursts are then allocated in DL and UL
-subframes, respectively. Since the standard allows sending and
-receiving bursts of packets in a given DL or UL burst, the unit of
-transmission at the MAC layer is a packet burst. The module
-implements a special PacketBurst data structure for this purpose. A packet
-burst is essentially a list of packets. The BS downlink and uplink schedulers, implemented
-by @code{class BSScheduler} and @code{class UplinkScheduler}, are responsible of
-generating DL and UL subframes, respectively. In the case of DL, the
-subframe is simulated by transmitting consecutive bursts (instances
-PacketBurst). In case of UL, the subframe is divided, with respect to time,
-into a number of slots. The bursts transmitted by the SSs in these slots are
-then aligned to slot boundaries. The frame is divided into integer number of
-symbols and Physical Slots (PS) which helps in managing bandwidth more
-effectively. The number of symbols per frame depends on the underlying
-implementation of the PHY layer. The size of a DL or UL burst is specified in
-units of symbols.
-
-@subsection Network Entry and Initialization
-
-The network entry and initialization phase is basically divided into
-two sub-phases, (1) scanning and synchronization and (2) initial
-ranging. The entire phase is performed by the LinkManager component of SS
-and BS.
-Once an SS wants to join the network, it first scans the downlink
-frequencies to search for a suitable channel. The search is complete as soon
-as it detects a PHY frame. The next step is to establish synchronization
-with the BS. Once SS receives a Downlink-MAP (DL-MAP) message the synchronization
-phase is complete and it remains synchronized as long as it keeps receiving
-DL-MAP and Downlink Channel Descriptor (DCD) messages. After the synchronization
-is established, SS waits for a Uplink Channel Descriptor (UCD) message to
-acquire uplink channel parameters. Once acquired, the first sub-phase of
-the network entry and initialization is complete.
-Once synchronization is achieved, the SS waits for a UL-MAP message to
-locate a special grant, called initial ranging interval, in the UL subframe.
-This grant is allocated by the BS Uplink Scheduler at regular
-intervals. Currently this interval is set to 0.5 ms, however the user
-is enabled to modify its value from the simulation script.
-
-@subsection Connections and Addressing
-
-All communication at the MAC layer is carried in terms of connections. The
-standard defines a connection as a unidirectional mapping between the SS and
-BS's MAC entities for the transmission of traffic. The standard defines two
-types of connections: management connections for transmitting
-control messages and transport connections for data transmission. A
-connection is identified by a 16-bit Connection Identifier (CID).
-@code{Class WimaxConnection} and @code{class Cid} implement the connection
-and CID, respectively. Note that each connection maintains its own
-transmission queue where packets to transmit on that connection are
-queued. The ConnectionManager component of BS is responsible
-of creating and managing connections for all SSs.
-
-The two key management connections defined by the standard, namely
-the Basic and Primary management connections, are created and
-allocated to the SS during the ranging process. Basic connection
-plays an important role throughout the operation of SS also because
-all (unicast) DL and UL grants are directed towards SS's Basic CID.
-In addition to management connections, an SS may have one or more
-transport connections to send data packets.
-The Connection Manager component of SS manages the connections associated to
-SS. As defined by the standard, a management connection is bidirectional,
-i.e., a pair of downlink and uplink connections is represented by the same
-CID. This feature is implemented in a way that one connection
-(in DL direction) is created by the BS and upon receiving the CID the SS
-then creates an identical connection (in UL direction) with the same CID.
-
-@subsection Scheduling Services
-
-The module supports the four scheduling services defined by the 802.16-2004
-standard:
-@itemize @bullet
-@item Unsolicited Grant Service (UGS)
-@item Real-Time Polling Services (rtPS)
-@item Non Real-Time Polling Services (nrtPS)
-@item Best Effort (BE)
-@end itemize
-
-These scheduling services behave differently with respect to how they request
-bandwidth as well as how the it is granted. Each service flow is associated to
-exactly one scheduling service, and the QoS parameter set associated
-to a service flow actually defines the scheduling service it belongs
-to. When a service flow is created the UplinkScheduler calculates necessary
-parameters such as grant size and grant interval based on QoS parameters
-associated to it.
-
-@subsection WiMAX Uplink Scheduler Model
-
-Uplink Scheduler at the BS decides which of the SSs will be assigned
-uplink allocations based on the QoS parameters associated to a service
-flow (or scheduling service) and bandwidth requests from the SSs. Uplink
-scheduler together with Bandwidth Manager implements the complete
-scheduling service functionality. The standard defines up to four
-scheduling services (BE, UGS, rtPS, nrtPS) for applications with
-different types of QoS requirements. The service flows of these
-scheduling services behave differently with respect to how they request
-for bandwidth as well as how the bandwidth is granted. The module
-supports all four scheduling services. Each service flow is associated
-to exactly one transport connection and one scheduling service. The QoS
-parameters associated to a service flow actually define the scheduling
-service it belongs to. Standard QoS parameters for UGS, rtPS, nrtPS and
-BE services, as specified in Tables 111a to 111d of the 802.16e
-amendment, are supported. When a service flow is created the uplink
-scheduler calculates necessary parameters such as grant size and
-allocation interval based on QoS parameters associated to it.
-The current WiMAX module provides three different versions of schedulers.
-
-@itemize @bullet
-@item The first one is a simple priority-based First Come First Serve (FCFS).
-For the real-time services (UGS and rtPS) the BS then allocates grants/polls on
-regular basis based on the calculated interval. For the non real-time
-services (nrtPS and BE) only minimum reserved bandwidth is guaranteed if
-available after servicing real-time flows. Note that not all of these
-parameters are utilized by the uplink scheduler. Also note that
-currently only service flow with fixed-size packet size are supported,
-as currently set up in simulation scenario with OnOff application of
-fixed packet size. This scheduler is implemented by @code{class BSSchedulerSimple}
-and @code{class UplinkSchedulerSimple}.
-
-@item The second one is similar to first scheduler except by rtPS service flow.
-All rtPS Connections are able to transmit all packet in the queue according
-to the available bandwidth. The bandwidth saturation control has been
-implemented to redistribute the effective available bandwidth to all rtPS
-that have at least one packet to transmit. The remaining bandwidth is allocated
-to nrtPS and BE Connections. This scheduler is implemented by
-@code{class BSSchedulerRtps} and @code{class UplinkSchedulerRtps}
-
-@item The third one is a Migration-based Quality of Service uplink scheduler
-This uplink scheduler uses three queues, the low priority
-queue, the intermediate queue and the high priority queue.
-The scheduler serves the requests in strict priority order
-from the high priority queue to the low priority queue. The
-low priority queue stores the bandwidth requests of the BE
-service flow. The intermediate queue holds bandwidth requests
-sent by rtPS and by nrtPS connections. rtPS and nrtPS requests
-can migrate to the high priority queue to guarantee that
-their QoS requirements are met. Besides the requests migrated
-from the intermediate queue, the high priority queue stores
-periodic grants and unicast request opportunities that must be
-scheduled in the following frame. To guarantee the maximum delay
-requirement, the BS assigns a deadline to each rtPS bandwidth
-request in the intermediate queue. The minimum bandwidth
-requirement of both rtPS and nrtPS connections is guaranteed
-over a window of duration T. This scheduler is implemented by
-@code{class UplinkSchedulerMBQoS}.
-@end itemize
-
-@subsection WiMAX Outbound Schedulers Model
-
-Besides the uplink scheduler these are the outbound schedulers at BS and
-SS side (BSScheduler and SSScheduler). The outbound schedulers decide
-which of the packets from the outbound queues will be transmitted in a
-given allocation. The outbound scheduler at the BS schedules the
-downlink traffic, i.e., packets to be transmitted to the SSs in the
-downlink subframe. Similarly the outbound scheduler at a SS schedules
-the packet to be transmitted in the uplink allocation assigned to that
-SS in the uplink subframe. All three schedulers have been implemented to
-work as FCFS scheduler, as they allocate grants starting from highest
-priority scheduling service to the lower priority one (UGS> rtPS>
-nrtPS> BE). The standard does not suggest any scheduling algorithm and
-instead leaves this decision up to the manufacturers. Of course more
-sophisticated algorithms can be added later if required.
-
-@node WimaxChannel and WimaxPhy models
-@section WimaxChannel and WimaxPhy models
-
-The module implements the Wireless MAN OFDM PHY specifications
-as the more relevant for implementation as it is the schema chosen by the
-WiMAX Forum. This specification is designed for non-light-of-sight (NLOS)
-including fixed and mobile broadband wireless access.
-The proposed model uses a 256 FFT processor, with 192 data subcarriers.
-It supports all the seven modulation and coding schemes specified by Wireless
-MAN-OFDM. It is composed of two parts: the channel model and the physical model.
-
-@node Channel model
-@section Channel model
-
-The channel model we propose is implemented by the @code{class SimpleOFDMWimaxChannel} which
-extends the @code{class wimaxchannel}. The channel entity has a private structure named m_phyList
-which handles all the physical devices connected to it. When a physical device sends a packet (FEC Block)
-to the channel, the channel handles the packet, and then for each physical device connected to it, it
-calculates the propagation delay, the path loss according to a given propagation model and eventually forwards the
-packet to the receiver device.
-The channel class uses the method @code{GetDistanceFrom()} to calculate the distance between two physical
-entities according to their 3D coordinates. The delay is computed as @code{delay = distance/C}, where C
-is the speed of the light.
-
-@node Physical model
-@section Physical model
-
-The physical layer performs two main operations: (i) It receives a burst from a channel and forwards it to the
-MAC layer, (ii) it receives a burst from the MAC layer and transmits it on the channel. In order to reduce the
-simulation complexity of the WiMAX physical layer, we have chosen to model offline part of the physical layer.
-More specifically we have developed an OFDM simulator to generate trace files used by the reception process to
-evaluate if a FEC block can be correctly decoded or not.
-
-Transmission Process: A burst is a set of WiMAX MAC PDUs. At the sending process, a burst is converted into
-bit-streams and then splitted into smaller FEC blocks which are then sent to the channel with a power equal
-P_tx.
-
-Reception Process: The reception process includes the following operations:
-
-@itemize @bullet
-1- Receive a FEC block from the channel.
-2- Calculate the noise level.
-3- Estimate the signal to noise ratio (SNR) with the following formula.
-4- Determine if a FEC block can be correctly decoded.
-5- Concatenate received FEC blocks to reconstruct the original burst.
-6- Forward the burst to the upper layer.
-@end itemize
-
-The developed process to evaluate if a FEC block can be correctly received or not uses pre-generated traces.
-The trace files are generated by an external OFDM simulator (described later). A class named
-SNRToBlockErrorRateManager handles a repository containing seven trace files (one for each modulation and coding
-scheme). A repository is specific for a particular channel model.
-
-A trace file is made of 6 columns. The first column provides the SNR value (1), whereas the other columns give
-respectively the bit error rate BER (2), the block error rate BlcER(3), the standard deviation on BlcER, and
-the confidence interval (4 and 5).
-These trace files are loaded into memory by the SNRToBlockErrorRateManager entity at the beginning of the simulation.
-
-Currently, The first process uses the first and third columns to determine if a FEC block is correctly received. When
-the physical layer receives a packet with an SNR equal to SNR_rx, it asks the SNRToBlockErrorRateManager to return
-the corresponding block error rate BlcER. A random number RAND between 0 and 1 is then generated. If RAND is
-greater than BlcER, then the block is correctly received, otherwise the block is considered erroneous and is ignored.
-
-The module provides defaults SNR to block error rate traces in default-traces.h. The traces have been generated by an
-External WiMAX OFDM simulator. The simulator is based on an external mathematics and signal processing library IT++
-and includes : a random block generator, a Reed Solomon (RS) coder, a convolutional coder, an interleaver, a 256
-FFT-based OFDM modulator, a multi-path channel simulator and an equalizer. The multipath channel is simulated using
-the TDL_channel class of the IT++ library.
-
-Users can configure the module to use their own traces generated by another OFDM simulator or ideally by performing
-experiments in real environment. for this purpose, a path to a repository containing trace files should be provided.
-If no repository is provided the traces form default-traces.h will be loaded. A valid repository should contain 7
-files, one for each modulation and coding scheme.
-
-The names of the files should respect the following format: modulation0.txt for modulation 0, modulation1.txt for
-modulation 1 and so on...
-The file format should be as follows
-@smallformat
-@example
-SNR_value1 BER Blc_ER STANDARD_DEVIATION CONFIDENCE_INTERVAL1 CONFIDENCE_INTERVAL2
-SNR_value2 BER Blc_ER STANDARD_DEVIATION CONFIDENCE_INTERVAL1 CONFIDENCE_INTERVAL2
- ... ... ... ... ... ...
- ... ... ... ... ... ...
-@end example
-@end smallformat