# HG changeset patch # User Craig Dowell # Date 1256003250 25200 # Node ID 39a82d7a0d661febe42e75f26ada79424258e330 # Parent 5f1b13dda227b3e606cfd2a2f64efad39a3ac990# Parent 81a3858041a8ede8e28b9634a4f4b74e82cb0a14 branch merge diff -r 5f1b13dda227 -r 39a82d7a0d66 doc/manual/Makefile --- a/doc/manual/Makefile Mon Oct 19 18:47:01 2009 -0700 +++ b/doc/manual/Makefile Mon Oct 19 18:47:30 2009 -0700 @@ -72,6 +72,8 @@ version: echo -n "ns-" > VERSION-PREFIX; cat VERSION-PREFIX ../../VERSION > VERSION; rm -rf VERSION-PREFIX -clean: figures-clean +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 + +clean: figures-clean texi-clean diff -r 5f1b13dda227 -r 39a82d7a0d66 doc/manual/animation.texi --- a/doc/manual/animation.texi Mon Oct 19 18:47:01 2009 -0700 +++ b/doc/manual/animation.texi Mon Oct 19 18:47:30 2009 -0700 @@ -4,3 +4,10 @@ @cartouche Placeholder chapter @end cartouche + +This wiki page: @* +@uref{http://www.nsnam.org/wiki/index.php/NetAnim,,http://www.nsnam.org/wiki/index.php/NetAnim} +contains information about the animator support that has been added to ns-3.6. + +Another Python-based animator is available (ns-3-pyviz) but is not +documented. diff -r 5f1b13dda227 -r 39a82d7a0d66 doc/manual/bridge.texi --- a/doc/manual/bridge.texi Mon Oct 19 18:47:01 2009 -0700 +++ b/doc/manual/bridge.texi Mon Oct 19 18:47:30 2009 -0700 @@ -4,3 +4,6 @@ @cartouche Placeholder chapter @end cartouche + +Some examples of the use of Bridge NetDevice can be found in +@code{examples/csma/} directory. diff -r 5f1b13dda227 -r 39a82d7a0d66 doc/manual/emu.texi --- a/doc/manual/emu.texi Mon Oct 19 18:47:01 2009 -0700 +++ b/doc/manual/emu.texi Mon Oct 19 18:47:30 2009 -0700 @@ -9,14 +9,7 @@ We perform MAC spoofing to separate simulation network traffic from other network traffic that may be flowing to and from the host. -Normally, the use case for emulated net devices is in collections of small -simulations that connect to the outside world through specific interfaces. -For example, one could construct a number of virtual machines and connect them -via a host-only network. To use the emulated net device, you would need to -set all of the host-only interfaces in promiscuous mode and provide an -appropriate device name, "eth1" for example. - -One could also use the @code{Emu} net device in a testbed situation where the +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 @@ -48,7 +41,7 @@ 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 static global routing. The global router module +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 @@ -71,8 +64,10 @@ 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. -@uref{http://www.nsnam.org/wiki/index.php/HOWTO_use_VMware_to_set_up_virtual_networks_(Windows)} -@uref{http://www.nsnam.org/wiki/index.php/HOWTO_use_ns-3_scripts_to_drive_real_hardware_(experimental)} +@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 @@ -102,7 +97,7 @@ // 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 addresses to the devices in both halves + // 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. // diff -r 5f1b13dda227 -r 39a82d7a0d66 doc/manual/flow-monitor.texi --- a/doc/manual/flow-monitor.texi Mon Oct 19 18:47:01 2009 -0700 +++ b/doc/manual/flow-monitor.texi Mon Oct 19 18:47:30 2009 -0700 @@ -4,3 +4,7 @@ @cartouche Placeholder chapter @end cartouche + +This feature was added as contributed code (@code{src/contrib}) in ns-3.6. +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} diff -r 5f1b13dda227 -r 39a82d7a0d66 doc/manual/internet.texi --- a/doc/manual/internet.texi Mon Oct 19 18:47:01 2009 -0700 +++ b/doc/manual/internet.texi Mon Oct 19 18:47:30 2009 -0700 @@ -3,19 +3,20 @@ @section Internet stack aggregation -The above @code{class Node} is not very useful as-is; other objects +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-related components. These include IPv4, -ARP, UDP, TCP, and other related protocols. +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: -@verbatim +@smallformat +@example void InternetStackHelper::Install (Ptr node) const { @@ -38,9 +39,14 @@ Ptr ipv4Routing = m_routing->Create (node); ipv4->SetRoutingProtocol (ipv4Routing); } -@end verbatim +@end example +@end smallformat -Note that the Ipv4 routing protocol is configured and set outside this +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 () @@ -55,6 +61,8 @@ } @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 @@ -70,7 +78,8 @@ src/internet-stack directory at present. In class Ipv4L3Protocol, one method described below is @code{Receive ()}: -@verbatim +@smallformat +@example /** * Lower layer calls this method after calling L3Demux::Lookup * The ARP subclass needs to know from which NetDevice this @@ -78,9 +87,10 @@ * - implement a per-NetDevice ARP cache * - send back arp replies on the right device */ - void Receive( Ptr device, Ptr p, uint16_t protocol, const Address &from, - const Address &to, NetDevice::PacketType packetType); -@end verbatim + void Receive( Ptr device, Ptr 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 @@ -111,10 +121,12 @@ 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: -@verbatim +@smallformat +@example void Ipv4L3Protocol::LocalDeliver (Ptr packet, Ipv4Header const&ip, uint32_t iif) -@end verbatim +@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. @@ -127,6 +139,8 @@ 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 diff -r 5f1b13dda227 -r 39a82d7a0d66 doc/manual/ipv6.texi --- a/doc/manual/ipv6.texi Mon Oct 19 18:47:01 2009 -0700 +++ b/doc/manual/ipv6.texi Mon Oct 19 18:47:30 2009 -0700 @@ -4,3 +4,7 @@ @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/} + diff -r 5f1b13dda227 -r 39a82d7a0d66 doc/manual/manual.texi --- a/doc/manual/manual.texi Mon Oct 19 18:47:01 2009 -0700 +++ b/doc/manual/manual.texi Mon Oct 19 18:47:30 2009 -0700 @@ -158,9 +158,9 @@ @unnumbered Part 3: Emulation @setchapternewpage off @include emulation.texi +@setchapternewpage odd @include emu.texi @include tap.texi -@setchapternewpage odd @unnumbered Part 4: Internet Models @setchapternewpage off diff -r 5f1b13dda227 -r 39a82d7a0d66 doc/manual/mesh.texi --- a/doc/manual/mesh.texi Mon Oct 19 18:47:01 2009 -0700 +++ b/doc/manual/mesh.texi Mon Oct 19 18:47:30 2009 -0700 @@ -4,3 +4,8 @@ @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} diff -r 5f1b13dda227 -r 39a82d7a0d66 doc/manual/new-models.texi --- a/doc/manual/new-models.texi Mon Oct 19 18:47:01 2009 -0700 +++ b/doc/manual/new-models.texi Mon Oct 19 18:47:30 2009 -0700 @@ -395,8 +395,10 @@ @subsection how to include files from elsewhere @subsection log component -Here, write a bit about adding ns-3 logging macros. Note that +@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 @@ -407,7 +409,8 @@ @subsection Object Framework -@verbatim +@smallformat +@example static const ClassId cid; @@ -416,8 +419,8 @@ const ClassId ErrorModel::cid = MakeClassId ("ErrorModel", ErrorModel::iid); -@end verbatim - +@end example +@end smallformat @node Adding-a-sample-script @section Adding a sample script @@ -431,7 +434,8 @@ @subsection Add basic support in the class -@verbatim +@smallformat +@example point-to-point-net-device.h class ErrorModel; @@ -440,12 +444,13 @@ */ Ptr m_receiveErrorModel; -@end verbatim +@end example +@end smallformat @subsection Add Accessor -@verbatim - +@smallformat +@example void PointToPointNetDevice::SetReceiveErrorModel (Ptr em) { @@ -458,11 +463,13 @@ PointerValue (), MakePointerAccessor (&PointToPointNetDevice::m_receiveErrorModel), MakePointerChecker ()) -@end verbatim +@end example +@end smallformat @subsection Plumb into the system -@verbatim +@smallformat +@example void PointToPointNetDevice::Receive (Ptr packet) { NS_LOG_FUNCTION (this << packet); @@ -486,15 +493,18 @@ ProcessHeader(packet, protocol); m_rxCallback (this, packet, protocol, GetRemote ()); if (!m_promiscCallback.IsNull ()) - { m_promiscCallback (this, packet, protocol, GetRemote (), GetAddress (), NetDevice::PACKET_HOST); + { m_promiscCallback (this, packet, protocol, GetRemote (), + GetAddress (), NetDevice::PACKET_HOST); } } } -@end verbatim +@end example +@end smallformat @subsection Create null functional script -@verbatim +@smallformat +@example simple-error-model.cc // Error model @@ -514,7 +524,8 @@ NS_LOG_UNCOND("Corrupt!"); return false; } -@end verbatim +@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 @@ -550,7 +561,8 @@ We declare BasicErrorModel to be a subclass of ErrorModel as follows, -@verbatim +@smallformat +@example class BasicErrorModel : public ErrorModel { public: @@ -562,7 +574,8 @@ virtual bool DoReset (void); ... } -@end verbatim +@end example +@end smallformat and configure the subclass GetTypeId function by setting a unique TypeId string and setting the Parent to ErrorModel: diff -r 5f1b13dda227 -r 39a82d7a0d66 doc/manual/node.texi --- a/doc/manual/node.texi Mon Oct 19 18:47:01 2009 -0700 +++ b/doc/manual/node.texi Mon Oct 19 18:47:30 2009 -0700 @@ -20,8 +20,8 @@ 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 unique integer ID, and a system ID (for -distributed simulation). +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: diff -r 5f1b13dda227 -r 39a82d7a0d66 doc/manual/python.texi --- a/doc/manual/python.texi Mon Oct 19 18:47:01 2009 -0700 +++ b/doc/manual/python.texi Mon Oct 19 18:47:30 2009 -0700 @@ -4,3 +4,6 @@ @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}. diff -r 5f1b13dda227 -r 39a82d7a0d66 doc/manual/routing.texi --- a/doc/manual/routing.texi Mon Oct 19 18:47:01 2009 -0700 +++ b/doc/manual/routing.texi Mon Oct 19 18:47:30 2009 -0700 @@ -25,7 +25,7 @@ @image{figures/routing, 6in} @end float -Figure 11-1 shows the overall routing architecture for Ipv4. The key objects +@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). @@ -143,7 +143,8 @@ For instance, this scheduling call will cause the tables to be rebuilt at time 5 seconds: @verbatim - Simulator::Schedule (Seconds (5),&Ipv4GlobalRoutingHelper::RecomputeRoutingTables); + Simulator::Schedule (Seconds (5), + &Ipv4GlobalRoutingHelper::RecomputeRoutingTables); @end verbatim @subsection Global Routing Implementation @@ -199,15 +200,21 @@ @node Unicast routing @section Unicast routing -There are presently four routing protocols defined: +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 Optimized Link State Routing (a MANET protocol defined in +@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 diff -r 5f1b13dda227 -r 39a82d7a0d66 doc/manual/sockets.texi --- a/doc/manual/sockets.texi Mon Oct 19 18:47:01 2009 -0700 +++ b/doc/manual/sockets.texi Mon Oct 19 18:47:30 2009 -0700 @@ -42,8 +42,8 @@ @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 a little funny to -people to pass ``Packets'' across a stream socket API, but think +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 @@ -58,7 +58,7 @@ @subsubsection Creating sockets An application that wants to use sockets must first create one. -On real systems, this is accomplished by calling socket(): +On real systems using a C-based API, this is accomplished by calling socket(): @verbatim int socket(int domain, int type, int protocol); @@ -79,11 +79,13 @@ This method returns a smart pointer to a Socket object. Here is an example: -@verbatim +@smallformat +@example Ptr n0; // Do some stuff to build up the Node's internet stack Ptr localSocket = Socket::CreateSocket (n0, TcpSocketFactory::GetTypeId ()); -@end verbatim +@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 @@ -149,7 +151,7 @@ int Recv (uint8_t* buf, uint32_t size); @end verbatim -The non-Packet variants are left for legacy API reasons. When calling +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 p)} is invoked. @@ -160,7 +162,7 @@ @itemize @bullet @item Users can use the Tags facility of packets to, for example, encode -a flow ID or other helper data. +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). @@ -193,51 +195,6 @@ @section POSIX-like sockets API -@emph{this capability is under development and is scheduled for -inclusion in the ns-3.5 releasetimeframe; see the repository -http://code.nsnam.org/mathieu/ns-3-simu for details} - -The below is excerpted from Mathieu's post to ns-developers list -on April 4, 2008. - -"To summarize, the goal is that the full posix/socket API is defined in -src/process/simu.h: each posix type and function is re-defined there -with a simu_ or SIMU_ prefix to avoid ugly name clashes and collisions -(feel free to come up with a better prefix). - -Each process is created with a call to ProcessManager::Create and is -attached to that ProcessManager instance. So, if the ProcessManager -(which is aggregated to a Node in src/helper/process-helper.cc) is -killed when the simulation ends, the system will automatically reclaim -all the resources of each process associated to each manager. The same -happens when an application "exits" from its main function. - -The example application defines two posix "processes": the function -ClientProgram creates a udp socket on the localhost port 2000 and the -function ServerProgram creates a udp socket on the localhost port 2000. -The code does not work right now because I did not get the details of -simu_read right yet but, I do plan to make this work at some point. - -I really think that this approach is worthwhile for many reasons, a few -of which are outlined below: -@itemize @bullet -@item makes porting real world application code _much_ easier - -@item makes write applications for new users much easier because they can -read the bsd socket api reference and documentation and write code -directly. - -@item can be used to write applications which work in both simulation and -in the real world at the same time. To do this, all you have to do is -write your application to use the simu_ API, and, then, you can chose at -compile-time which implementation of that API you want to use: you can -pick one implementation which forwards all calls to the system BSD -socket API or another one which forwards all calls to the attached -ProcessManager. Arguably, I did not implement the version which forwards -to system BSD sockets but, that should be pretty trivial. -@end itemize - -So, anyway, comments about the overall API would be welcome. Students -interested in the gsoc project for real-world code integration should -consider looking at this also." - +@cartouche +Under development in the http://code.nsnam.org/mathieu/ns-3-simu repository. +@end cartouche diff -r 5f1b13dda227 -r 39a82d7a0d66 doc/manual/statistics.texi --- a/doc/manual/statistics.texi Mon Oct 19 18:47:01 2009 -0700 +++ b/doc/manual/statistics.texi Mon Oct 19 18:47:30 2009 -0700 @@ -4,3 +4,7 @@ @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. diff -r 5f1b13dda227 -r 39a82d7a0d66 doc/manual/tap.texi --- a/doc/manual/tap.texi Mon Oct 19 18:47:01 2009 -0700 +++ b/doc/manual/tap.texi Mon Oct 19 18:47:30 2009 -0700 @@ -5,3 +5,7 @@ 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. + diff -r 5f1b13dda227 -r 39a82d7a0d66 doc/manual/tcp.texi --- a/doc/manual/tcp.texi Mon Oct 19 18:47:01 2009 -0700 +++ b/doc/manual/tcp.texi Mon Oct 19 18:47:30 2009 -0700 @@ -105,10 +105,7 @@ @subsection Current limitations @itemize @bullet @item Only Tahoe congestion control is presently supported. -@item Only IPv4 is supported (IPv6 support will start to be added in ns-3.3). -@item @uref{http://www.nsnam.org/bugzilla/show_bug.cgi?id=198,,Bug 198}: TcpSocketImpl doesn't send acks with data packets in two-way transfers -@item @uref{http://www.nsnam.org/bugzilla/show_bug.cgi?id=250,,Bug 250}: Tcp breaks if you set the DelAckCount parameter to be greater than 2 -@item @uref{http://www.nsnam.org/bugzilla/show_bug.cgi?id=311,,Bug 311}: Tcp socket close returns -1 but does not set errno. +@item Only IPv4 is supported (IPv6 support will start to be added after ns-3.6). @end itemize @section Network Simulation Cradle @@ -132,43 +129,17 @@ @subsection Prerequisites Presently, NSC has been tested and shown to work on these platforms: -Linux i386 and Linux x86-64. NSC does not support powerpc at the moment. +Linux i386 and Linux x86-64. NSC does not support powerpc. -NSC requires the packages mercurial, flex, and bison. +Building NSC requires the packages flex and bison. @subsection Configuring and Downloading -NSC is disabled by default and must be explicitly configured in. To try -this, type -@verbatim -./waf configure --enable-nsc -@end verbatim -the output of the configuration will show something like: +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 -Checking for NSC supported architecture x86_64 : ok -Pulling nsc updates from https://secure.wand.net.nz/mercurial/nsc -pulling from https://secure.wand.net.nz/mercurial/nsc -searching for changes -no changes found ----- Summary of optional NS-3 features: -... -Network Simulation Cradle : enabled -... -@end verbatim -if successful. Note that the configure script pulls a recent copy of -NSC from a mercurial repository. This download will not work if you are not -online. - -If everything went OK, you will see a directory called "nsc" in the top-level -directory, with contents like this: -@verbatim -audit.sh linux-2.6/ openbsd3/ scons-time.py* -ChangeLog linux-2.6.18/ README SConstruct -config.log linux-2.6.26/ sconsign.py* sim/ -freebsd5/ lwip-1.3.0/ scons-LICENSE test/ -globaliser/ lwip-HEAD/ scons-local-1.0.1/ -INSTALL ns/ scons.py* -LICENSE omnetpp/ scons-README +./waf configure --disable-nsc @end verbatim @subsection Building and validating @@ -233,12 +204,18 @@ ns-3 @ref{Attributes} system, via a @uref{http://en.wikipedia.org/wiki/Sysctl,, sysctl}-like interface. In the @code{examples/tcp-nsc-zoo} example, you can see the following configuration: -@verbatim - // this disables TCP SACK, wscale and timestamps on node 1 (the attributes represent sysctl-values). - Config::Set ("/NodeList/1/$ns3::Ns3NscStack/net.ipv4.tcp_sack", StringValue ("0")); - Config::Set ("/NodeList/1/$ns3::Ns3NscStack/net.ipv4.tcp_timestamps", StringValue ("0")); - Config::Set ("/NodeList/1/$ns3::Ns3NscStack/net.ipv4.tcp_window_scaling", StringValue ("0")); -@end verbatim +@smallformat +@example + // this disables TCP SACK, wscale and timestamps on node 1 (the attributes +represent sysctl-values). + Config::Set ("/NodeList/1/$ns3::Ns3NscStack/net.ipv4.tcp_sack", +StringValue ("0")); + Config::Set ("/NodeList/1/$ns3::Ns3NscStack/net.ipv4.tcp_timestamps", +StringValue ("0")); + Config::Set ("/NodeList/1/$ns3::Ns3NscStack/net.ipv4.tcp_window_scaling", +StringValue ("0")); +@end example +@end smallformat These additional configuration variables are not available to native ns-3 TCP. @@ -331,11 +308,10 @@ @itemize @bullet @item NSC only works on single-interface nodes; attempting to run it on a multi-interface node will cause a program error. This limitation should -be fixed by ns-3.3. -@item Cygwin and OS X PPC are not presently supported -@item The non-Linux stacks of NSC are not supported -@item NSC's integration into the build system presently requires on-line -access and mercurial, and is a slow download. +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 diff -r 5f1b13dda227 -r 39a82d7a0d66 doc/manual/troubleshoot.texi --- a/doc/manual/troubleshoot.texi Mon Oct 19 18:47:01 2009 -0700 +++ b/doc/manual/troubleshoot.texi Mon Oct 19 18:47:30 2009 -0700 @@ -9,7 +9,9 @@ * Run-time errors:: @end menu -Please note that the wiki (@uref{http://www.nsnam.org/wiki/index.php/Troubleshooting}) may have contributed items. +Please note that the wiki @* +(@uref{http://www.nsnam.org/wiki/index.php/Troubleshooting}) +may have contributed items. @node Build errors @section Build errors @@ -23,18 +25,21 @@ Here is an example of what might occur: -@verbatim +@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 verbatim +@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}: -@verbatim +@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 @@ -44,7 +49,8 @@ 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". +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 @@ -61,7 +67,8 @@ $2 = {m_ptr = 0x0} (gdb) quit The program is running. Exit anyway? (y or n) y -@end verbatim +@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". @@ -70,11 +77,13 @@ socketFactory. Let's look around line 136 of tcp-point-to-point, as gdb suggests: -@verbatim +@smallformat +@example Ptr socketFactory = n2->GetObject (Tcp::iid); Ptr localSocket = socketFactory->CreateSocket (); localSocket->Bind (); -@end verbatim +@end example +@end smallformat The culprit here is that the return value of GetObject is not being checked and may be null. @@ -82,6 +91,8 @@ 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: -@verbatim +@smallformat +@example ns-old:~/ns-3-nsc$ ./waf --run tcp-point-to-point --command-template="valgrind %s" -@end verbatim +@end example +@end smallformat diff -r 5f1b13dda227 -r 39a82d7a0d66 doc/manual/wifi.texi --- a/doc/manual/wifi.texi Mon Oct 19 18:47:01 2009 -0700 +++ b/doc/manual/wifi.texi Mon Oct 19 18:47:30 2009 -0700 @@ -28,9 +28,8 @@ @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, and ConstantRate} -@item @emph{(under development)} 802.11s (mesh) -@item @emph{(under development)} Minstrel rate control +@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 @@ -159,10 +158,12 @@ loss of 46.6777 dB at reference distance of 1m. Users will typically type code such as: -@verbatim +@smallformat +@example YansWifiChannelHelper wifiChannelHelper = YansWifiChannelHelper::Default (); Ptr wifiChannel = wifiChannelHelper.Create (); -@end verbatim +@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 @@ -203,35 +204,45 @@ Setting up a non-QoS MAC layers the object we use is @code{ns3::NqosWifiMacHelper}. For example the following user code configures a non-QoS MAC sta and changes its default values for contention window and Aifsn: -@verbatim +@smallformat +@example NqosWifiMacHelper wifiMacHelper = NqosWifiMacHelper::Default (); Ssid ssid = Ssid ("ns-3-ssid"); - wifiMacHelper.SetType ("ns3::NqstaWifiMac", "Ssid", SsidValue (ssid), "ActiveProbing", BooleanValue (false)); - wifiMacHelper.SetDcaParameters ("MinCw", UintegerValue (20), "Aifsn", UintegerValue (3)); -@end verbatim + wifiMacHelper.SetType ("ns3::NqstaWifiMac", "Ssid", SsidValue (ssid), +"ActiveProbing", BooleanValue (false)); + wifiMacHelper.SetDcaParameters ("MinCw", UintegerValue (20), "Aifsn", +UintegerValue (3)); +@end example +@end smallformat Setting up a QoS MACs we use a @code{ns3::QosWifiMacHelper} instead. This object could be also used to change default EDCA parameters, and to set a possible MSDU aggregator for a particular access class in order to use 802.11n MSDU aggregation feature. A possible user code: -@verbatim +@smallformat +@example QosWifiMacHelper wifiMacHelper = QosWifiMacHelper::Default (); - wifiMacHelper.SetType ("ns3::QapWifiMac", "Ssid", SsidValue (ssid), "BeaconGeneration", BooleanValue (true), + wifiMacHelper.SetType ("ns3::QapWifiMac", "Ssid", SsidValue (ssid), +"BeaconGeneration", BooleanValue (true), "BeaconInterval", TimeValue (Seconds (2.5))); wifiMacHelper.SetEdcaParametersForAc (AC_VO, "MinCw", UintegerValue (2)); - wifiMacHelper.SetMsduAggregatorForAc (AC_VO, "ns3::MsduStandardAggregator", "MaxAmsduSize", UintegerValue (3839)); -@end verbatim + wifiMacHelper.SetMsduAggregatorForAc (AC_VO, "ns3::MsduStandardAggregator", +"MaxAmsduSize", UintegerValue (3839)); +@end example +@end smallformat Call to QosWifiMacHelper::Default () is needed in order to set default EDCA parameters properly for all access classes. Otherwise we should set them one by one: -@verbatim +@smallformat +@example QosWifiMacHelper wifiMacHelper; - wifiMacHelper.SetEdcaParametersForAc (AC_VO, "MinCw", UintegerValue (2), "MaxCw", UintegerValue (7), - "Aifsn", UintegerValue (2)); - wifiMacHelper.SetEdcaParametersForAc (AC_VI, "MinCw", UintegerValue (7), "MaxCw", UintegerValue (15), - "Aifsn", UintegerValue (2)); + wifiMacHelper.SetEdcaParametersForAc (AC_VO, "MinCw", UintegerValue (2), +"MaxCw", UintegerValue (7), "Aifsn", UintegerValue (2)); + wifiMacHelper.SetEdcaParametersForAc (AC_VI, "MinCw", UintegerValue (7), +"MaxCw", UintegerValue (15), "Aifsn", UintegerValue (2)); ... -@end verbatim +@end example +@end smallformat @subsection WifiHelper @@ -244,9 +255,11 @@ @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": -@verbatim +@smallformat +@example NetDeviceContainer wifiContainer = WifiHelper::Install (wifiPhyHelper, wifiMacHelper, c); -@end verbatim +@end example +@end smallformat This creates the WifiNetDevice which includes also a WifiRemoteStationManager, a WifiMac, and a WifiPhy (connected to the matching WifiChannel). @@ -257,12 +270,16 @@ @subsection AdHoc WifiNetDevice configuration This is a typical example of how a user might configure an adhoc network. -@emph{Write me} +@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. -@emph{Write me} +@cartouche +To be completed +@end cartouche @node The WifiChannel and WifiPhy models @section The WifiChannel and WifiPhy models