--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/animation.texi Fri Oct 16 07:13:05 2009 -0700
@@ -0,0 +1,6 @@
+@node Animation
+@chapter Animation
+
+@cartouche
+Placeholder chapter
+@end cartouche
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/applications.texi Fri Oct 16 07:13:05 2009 -0700
@@ -0,0 +1,6 @@
+@node Applications
+@chapter Applications
+
+@cartouche
+Placeholder chapter
+@end cartouche
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/bridge.texi Fri Oct 16 07:13:05 2009 -0700
@@ -0,0 +1,6 @@
+@node Bridge NetDevice
+@chapter Bridge NetDevice
+
+@cartouche
+Placeholder chapter
+@end cartouche
--- a/doc/manual/callbacks.texi Thu Oct 15 23:55:06 2009 -0700
+++ b/doc/manual/callbacks.texi Fri Oct 16 07:13:05 2009 -0700
@@ -7,15 +7,15 @@
it, and details on its implementation.
@menu
-* Motivation::
-* Background::
+* Callbacks Motivation::
+* Callbacks Background::
* Using the Callback API::
* Bound Callbacks::
* Callback locations in ns-3::
* Implementation details::
@end menu
-@node Motivation
+@node Callbacks Motivation
@section Motivation
Consider that you have two simulation models A and B, and you wish
@@ -91,7 +91,7 @@
system to get the desired interconnections, This is clearly not an
optimal way to design a generic simulator.
-@node Background
+@node Callbacks Background
@section Background
The basic mechanism that allows one to address the problem above is known as
--- a/doc/manual/emu.texi Thu Oct 15 23:55:06 2009 -0700
+++ b/doc/manual/emu.texi Fri Oct 16 07:13:05 2009 -0700
@@ -1,183 +1,293 @@
@node Emu NetDevice
@chapter Emu NetDevice
-This is the introduction to Emu NetDevice chapter, to complement the
-Emu model doxygen.
-
-@menu
-* Overview of the model::
-* Using the EmuNetDevice::
-* Emu Tracing::
-@end menu
+@section Behavior
-@node Overview of the model
-@section Overview of the model
-
-The emulated net device allows a simulation node to send and receive packets
-a real network.
-
-The Emu net device is not a complete net device and channel combination as is
-typical in ns-3. The Emu device can be thought of as a proxy for a real
-device that resides in an ns-3 simulation. The Emu net device talks to that
-real device using raw sockets and binds to the device via the Linux interface.
-There is no related Emu channel since other devices will most likely reside on
-different computers running entirely separate simulations.
+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.
-The Emu net device relies on a specified interface (``eth1, for example) 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.
-
-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.
+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 emulated 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.
+One could also 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 emulated net device only works if the underlying interface is up in
-promiscuous mode. We could just turn it on, but the situation is that we
-expect the other considerations listed above to have been dealt with.
-To verify that these issues are dealt with, we just make sure that the end
-result of that process has taken place and that the specified interface is
-in promiscuous mode.
-
-@subsection Address Concerns
-
-Packets will be sent out over the device, but as mentioned, we use MAC spoofing.
-By default in the simulation, the MAC addresses will be generated using the
+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 you to determine that using these MAC addresses is
+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
+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 SetAddress method so you can do this manually. For larger simulations,
-you may want to set the OUI in the MAC address allocation function.
+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.
-
-@subsection Attributes
-
-The Emu network device appears to the ns-3 system just as any other device and
-can be controlled through the attribute system, and traced through conventional
-trace hooks. The EmuNetDevice provides following Attributes:
-
-@itemize @bullet
-@item Address: The Mac48Address of the device;
-@item DeviceName: The name of the underlying real device (e.g., ``eth1'');
-@item Start: The simulation time at which to enable the underlying socket;
-@item Stop: The simulation time at which to stop receiving from the underlying socket;
-@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;
-@end itemize
-
-Packets sent over the EmuNetDevice 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.
-
-@node Using the EmuNetDevice
-@section Using the EmuNetDevice
+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 medium is, and so have not made an
-effort to model it abstractly. The primary thing to be aware of is the
+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
attempts to walk the channels looking for adjacent networks. Since there
-is no channel, the global router will be unable to do this.
+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.
-The Emu net devices are typically created and configured using the associated
-@code{EmuHelper} object. The various ns3 device helpers generally work in a
-similar way, and their use is seen in many of our example programs.
+@section Usage
-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:
-
+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
- NodeContainer nodes;
- nodes.Create (nEmuNodes);
+GlobalValue::Bind ("ChecksumEnabled", BooleanValue (true));
@end verbatim
-Once you have your nodes, you need to instantiate a @code{EmuHelper} and set
-any attributes you may want to change.
+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.
+
+@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)}
+
+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;
- csma.SetAttribute ("DeviceName", StringValue ("eth1"));
+ emu.SetAttribute ("DeviceName", StringValue ("eth1"));
+ NetDeviceContainer d = emu.Install (n);
@end verbatim
-
-Once the attributes are set, all that remains is to create the devices
-and install them on the required nodes. 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.
+
+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 addresses 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
- NetDeviceContainer emuDevices = emu.Install (nodes);
+ //
+ // 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
-@node Emu Tracing
-@section Emu Tracing
+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.
-Like all ns-3 devices, the Emu 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.
+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.
-@subsection Upper-Level (MAC) Hooks
+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}:
-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.
+@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);
-When a packet is sent to the Emu net device for transmission it always
-passes through the transmit queue. The transmit queue in the
-EmuNetDevice inherits from Queue, and therefore inherits three
-trace sources:
+ 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.
-@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
+@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 upper-level (MAC) trace hooks for the EmuNetDevice are, in fact,
-exactly these three trace sources on the single transmit queue of the device.
+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.
-The m_traceEnqueue event is triggered when a packet is placed on the transmit
-queue. This happens at the time that EmuNetDevice::Send or
-EmuNetDevice::SendFrom is called by a higher layer to queue a packet for
-transmission.
+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);
-The m_traceDequeue event is triggered when a packet is removed from the
-transmit queue. Dequeues from the transmit queue happen immediately after
-the Enqueue event and just prior to the packet being sent to the underlying
-socket. This means that the transmit queue really only exists to fire on
-enqueue and dequeue operations so the Emu device behaves like other ns-3
-devices in this respect.
+ m_queue->Enqueue (packet);
+ packet = m_queue->Dequeue ();
+
+ struct sockaddr_ll ll;
+ bzero (&ll, sizeof (ll));
-@subsection Lower-Level (PHY) Hooks
+ ll.sll_family = AF_PACKET;
+ ll.sll_ifindex = m_sll_ifindex;
+ ll.sll_protocol = htons(ETH_P_ALL);
-There are no lower level trace hooks implemented in the Emu net device since
-we rely on the underlying OS implementation of the raw socket to perform
-the low level operations required to send and receive packets.
+ 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 Oct 15 23:55:06 2009 -0700
+++ b/doc/manual/emulation.texi Fri Oct 16 07:13:05 2009 -0700
@@ -1,6 +1,5 @@
@node Emulation
@chapter Emulation
-@anchor{chap:Emulation}
ns-3 has been designed for integration into testbed and virtual machine
environments. We have addressed this need by providing two kinds of
@@ -68,317 +67,3 @@
behavior of native applications and protocol suites in the presence of large
simulated ns-3 networks.
-@section Behavior
-
-@subsection Emu Net Device
-
-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.
-
-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
-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 static 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.
-
-@subsection Tap Net Device
-
-The @code{Tap} Net Device is scheduled for inclusion in ns-3.4 at the writing
-of this section. We will include details as soon as the @code{Tap} device is
-merged.
-
-@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
-
-@subsection Emu Net Device
-
-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.
-
-@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)}
-
-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 addresses 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/}.
-
-@subsection Tap Net Device
-
-The @code{Tap} Net Device is scheduled for inclusion in ns-3.4 at the writing
-of this section. We will include details as soon as the @code{Tap} device is
-merged.
-
-@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.
-
-@subsection Emu Net Device
-
-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.
-
-@subsection Tap Net Device
-
-The @code{Tap} Net Device is scheduled for inclusion in ns-3.4 at the writing
-of this section. We will include details as soon as the @code{Tap} device is
-merged.
-
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/flow-monitor.texi Fri Oct 16 07:13:05 2009 -0700
@@ -0,0 +1,6 @@
+@node Flow Monitor
+@chapter Flow Monitor
+
+@cartouche
+Placeholder chapter
+@end cartouche
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/helpers.texi Fri Oct 16 07:13:05 2009 -0700
@@ -0,0 +1,42 @@
+@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.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/internet.texi Fri Oct 16 07:13:05 2009 -0700
@@ -0,0 +1,229 @@
+@node Internet Stack
+@chapter Internet Stack
+
+@section Internet stack aggregation
+
+The above @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.
+
+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
+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 verbatim
+
+Note that the Ipv4 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
+
+@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 ()}:
+@verbatim
+ /**
+ * 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 verbatim
+
+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:
+
+@verbatim
+void
+Ipv4L3Protocol::LocalDeliver (Ptr<const Packet> packet, Ipv4Header const&ip, uint32_t iif)
+@end verbatim
+
+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.
+
+@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
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/ipv4.texi Fri Oct 16 07:13:05 2009 -0700
@@ -0,0 +1,6 @@
+@node IPv4
+@chapter IPv4
+
+@cartouche
+Placeholder chapter
+@end cartouche
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/ipv6.texi Fri Oct 16 07:13:05 2009 -0700
@@ -0,0 +1,6 @@
+@node IPv6
+@chapter IPv6
+
+@cartouche
+Placeholder chapter
+@end cartouche
--- a/doc/manual/log.texi Thu Oct 15 23:55:06 2009 -0700
+++ b/doc/manual/log.texi Fri Oct 16 07:13:05 2009 -0700
@@ -1,24 +1,7 @@
@node Logging
@chapter Logging
-@anchor{chap:Logging}
-This chapter is the first in a series of chapters discussing things that
-one can do to modify the input or output of existing ns-3 scripts.
-
-Examples:
-@itemize @bullet
-@item Enable or disable the generation of log messages, with fine granularity
-@item Set default values for configuration values in the system
-@item Generate a report of all configuration values used during a simulation
-run (not yet implemented)
-@item Set or get values of member variables on objects already instantiated
-@item Customizing the tracing output of the script
-@item Generate statistics on (not yet implemented)
-@item Perform a large number of independent runs of the same simulation
-@end itemize
-
-@node Logging Basics
-@section Logging Basics
-
-@node Enabling Log Output
-@section Enabling Log Output
+@cartouche
+This chapter not yet written. For now, the ns-3 tutorial contains logging
+information.
+@end cartouche
--- a/doc/manual/manual.texi Thu Oct 15 23:55:06 2009 -0700
+++ b/doc/manual/manual.texi Fri Oct 16 07:13:05 2009 -0700
@@ -2,7 +2,6 @@
@c %**start of header
@setfilename ns-3.info
@settitle ns-3 manual
-@c @setchapternewpage odd
@c %**end of header
@ifinfo
@@ -61,7 +60,6 @@
@include VERSION
@today{}
-@c @page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@@ -86,42 +84,102 @@
@end ifnottex
@menu
+* Organization::
* Random variables::
* Callbacks::
* Object model::
* Attributes::
+* Object names::
+* Logging::
* Tracing::
* RealTime::
+* Packets::
+* Helpers::
+* Python::
+* Node and NetDevices::
+* Simple NetDevice::
+* PointToPoint NetDevice::
+* CSMA NetDevice::
+* Wifi NetDevice::
+* Mesh NetDevice::
+* Bridge NetDevice::
* Emulation::
-* Packets::
+* Emu NetDevice::
+* Tap NetDevice::
* Sockets APIs::
-* Node and Internet Stack::
+* Internet Stack::
+* IPv4::
+* IPv6::
+* Routing overview::
* TCP::
-* Routing overview::
-* Wifi NetDevice::
-* CSMA NetDevice::
-* PointToPoint NetDevice::
+* Applications::
+* Flow Monitor::
+* Animation::
+* Statistics::
* Creating a new ns-3 model::
* Troubleshooting::
@end menu
+@setchapternewpage odd
+@headings off
+@everyheading @thischapter @| @| ns-3 manual
+@everyfooting ns-3.6 @| @thispage @| @today
+@include organization.texi
+
+@unnumbered Part 1: ns-3 core
+@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 packets.texi
+@include helpers.texi
+@include python.texi
+
+@unnumbered Part 2: Nodes and NetDevices
+@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
+
+@unnumbered Part 3: Emulation
+@setchapternewpage off
@include emulation.texi
-@include packets.texi
+@include emu.texi
+@include tap.texi
+@setchapternewpage odd
+
+@unnumbered Part 4: Internet Models
+@setchapternewpage off
@include sockets.texi
-@include node.texi
-@c @include output.texi
+@setchapternewpage odd
+@include internet.texi
+@include ipv4.texi
+@include ipv6.texi
+@include routing.texi
@include tcp.texi
-@include routing.texi
-@include wifi.texi
-@include csma.texi
-@include point-to-point.texi
-@c @include other.texi
+
+@unnumbered Part 5: Applications
+@setchapternewpage off
+@include applications.texi
+@setchapternewpage odd
+
+@unnumbered Part 6: Support
+@setchapternewpage off
+@include flow-monitor.texi
+@setchapternewpage odd
+@include animation.texi
+@include statistics.texi
@include new-models.texi
@include troubleshoot.texi
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/mesh.texi Fri Oct 16 07:13:05 2009 -0700
@@ -0,0 +1,6 @@
+@node Mesh NetDevice
+@chapter Mesh NetDevice
+
+@cartouche
+Placeholder chapter
+@end cartouche
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/names.texi Fri Oct 16 07:13:05 2009 -0700
@@ -0,0 +1,6 @@
+@node Object names
+@chapter Object names
+
+@cartouche
+Placeholder chapter
+@end cartouche
--- a/doc/manual/node.texi Thu Oct 15 23:55:06 2009 -0700
+++ b/doc/manual/node.texi Fri Oct 16 07:13:05 2009 -0700
@@ -1,5 +1,5 @@
-@node Node and Internet Stack
-@chapter Node and Internet Stack
+@node Node and NetDevices
+@chapter Node and NetDevices
@anchor{chap:Node}
This chapter describes how ns-3 nodes are put together, and provides
@@ -109,229 +109,6 @@
to allow one to walk the node list or fetch a Node pointer by
its integer identifier.
-@section Internet stack aggregation
-
-The above @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.
-
-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
-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 verbatim
-
-Note that the Ipv4 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
-
-@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 ()}:
-@verbatim
- /**
- * 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 verbatim
-
-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:
+The following chapters provide reference information on the available
+NetDevices in ns-3.
-@verbatim
-void
-Ipv4L3Protocol::LocalDeliver (Ptr<const Packet> packet, Ipv4Header const&ip, uint32_t iif)
-@end verbatim
-
-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.
-
-@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
-
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/organization.texi Fri Oct 16 07:13:05 2009 -0700
@@ -0,0 +1,50 @@
+@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++.
+
+The source code for ns-3 is mostly organized in the @code{src/}
+directory and can be described by the following block diagram.
+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/docs,, ns-3 Testing and Validation manual})j
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/python.texi Fri Oct 16 07:13:05 2009 -0700
@@ -0,0 +1,6 @@
+@node Python
+@chapter Python
+
+@cartouche
+Placeholder chapter
+@end cartouche
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/simple.texi Fri Oct 16 07:13:05 2009 -0700
@@ -0,0 +1,6 @@
+@node Simple NetDevice
+@chapter Simple NetDevice
+
+@cartouche
+Placeholder chapter
+@end cartouche
--- a/doc/manual/statistics.texi Thu Oct 15 23:55:06 2009 -0700
+++ b/doc/manual/statistics.texi Fri Oct 16 07:13:05 2009 -0700
@@ -1,9 +1,6 @@
@node Statistics
@chapter Statistics
-@anchor{chap:Statistics}
-ns-3 does not presently have support for statistics (automatically generated
-statistical output). This is planned
-for development later in 2008. If you are interested in contributing,
-please see @uref{http://www.nsnam.org/wiki/index.php/Suggested_Projects,,our suggested projects page} or contact the ns-developers
-list.
+@cartouche
+Placeholder chapter
+@end cartouche
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/tap.texi Fri Oct 16 07:13:05 2009 -0700
@@ -0,0 +1,7 @@
+@node Tap NetDevice
+@chapter Tap NetDevice
+
+@cartouche
+Placeholder chapter
+@end cartouche
+
--- a/doc/manual/tracing.texi Thu Oct 15 23:55:06 2009 -0700
+++ b/doc/manual/tracing.texi Fri Oct 16 07:13:05 2009 -0700
@@ -13,13 +13,13 @@
this is the tracing subsystem.
@menu
-* Motivation::
+* Tracing Motivation::
* Overview::
* Using the Tracing API::
-* Implementation details::
+* Tracing implementation details::
@end menu
-@node Motivation
+@node Tracing Motivation
@section Motivation
There are many ways to get information out of a program. The most straightforward
@@ -324,5 +324,5 @@
sinks.
@end itemize
-@node Implementation details
+@node Tracing implementation details
@section Implementation details