F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Manual organization

Browse Source
This commit is contained in:
Tom Henderson
2009-10-16 07:13:05 -07:00
parent 117fa7f3c2
commit c237cbe114
22 changed files with 729 additions and 731 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
doc/manual/animation.texi Normal file
View File

@@ -0,0 +1,6 @@
@node Animation
@chapter Animation
@cartouche
Placeholder chapter
@end cartouche

6
doc/manual/applications.texi Normal file
View File

@@ -0,0 +1,6 @@
@node Applications
@chapter Applications
@cartouche
Placeholder chapter
@end cartouche

6
doc/manual/bridge.texi Normal file
View File

@@ -0,0 +1,6 @@
@node Bridge NetDevice
@chapter Bridge NetDevice
@cartouche
Placeholder chapter
@end cartouche

8
doc/manual/callbacks.texi
View File

@@ -7,15 +7,15 @@ chapter provides some motivation on the callback, guidance on how to use
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 @@ to a transport protocol above, the user may be forced to hack the
system to get the desired interconnections, This is clearly not an
optimal way to design a generic simulator.
@node Background
@node Callbacks Background
@section Background
The basic mechanism that allows one to address the problem above is known as

384
doc/manual/emu.texi
View File

@@ -1,183 +1,293 @@
@node Emu NetDevice
@chapter Emu NetDevice
This is the introduction to Emu NetDevice chapter, to complement the
Emu model doxygen.
@section Behavior
@menu
* Overview of the model::
* Using the EmuNetDevice::
* Emu Tracing::
@end menu
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.
@node Overview of the model
@section Overview of the model
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.
The emulated net device allows a simulation node to send and receive packets
a real network.
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 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 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.
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.
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.
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:
@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
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
NetDeviceContainer emuDevices = emu.Install (nodes);
//
// 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
@node Emu Tracing
@section Emu Tracing
And then the IP address of the client or server is set in the usual way using
helpers.
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.
@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
@subsection Upper-Level (MAC) Hooks
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.
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
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
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:
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:
@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
EmuHelper::EnablePcapAll ("emu-udp-echo-client");
@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.
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/}.
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.
@section Implementation
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.
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.
@subsection Lower-Level (PHY) Hooks
We do a similar thing for both the @code{Emu} and the @code{Tap} devices.
The high-level view is that the @code{CreateSocket} method creates a local
interprocess (Unix) socket, forks, and executes the small creation program.
The small program, which runs as suid root, creates a raw socket and sends
back the raw socket file descriptor over the Unix socket that is passed to
it as a parameter. The raw socket is passed as a control message (sometimes
called ancillary data) of type SCM_RIGHTS.
The @code{Emu} net device uses the ns-3 threading and multithreaded real-time
scheduler extensions. The interesting work in the @code{Emu} device is done
when the net device is started (@code{EmuNetDevice::StartDevice ()}). An
attribute (``Start'') provides a simulation time at which to spin up the
net device. At this specified time (which defaults to t=0), the socket
creation function is called and executes as described above. You may also
specify a time at which to stop the device using the ``Stop'' attribute.
Once the (promiscuous mode) socket is created, we bind it to an interface name
also provided as an attribute (``DeviceName'') that is stored internally as
@code{m_deviceName}:
@verbatim
struct ifreq ifr;
bzero (&ifr, sizeof(ifr));
strncpy ((char *)ifr.ifr_name, m_deviceName.c_str (), IFNAMSIZ);
int32_t rc = ioctl (m_sock, SIOCGIFINDEX, &ifr);
struct sockaddr_ll ll;
bzero (&ll, sizeof(ll));
ll.sll_family = AF_PACKET;
ll.sll_ifindex = m_sll_ifindex;
ll.sll_protocol = htons(ETH_P_ALL);
rc = bind (m_sock, (struct sockaddr *)&ll, sizeof (ll));
@end verbatim
After the promiscuous raw socket is set up, a separate thread is spawned to do
reads from that socket and the link state is set to @code{Up}.
@verbatim
m_readThread = Create<SystemThread> (
MakeCallback (&EmuNetDevice::ReadThread, this));
m_readThread->Start ();
NotifyLinkUp ();
@end verbatim
The @code{EmuNetDevice::ReadThread} function basically just sits in an infinite
loop reading from the promiscuous mode raw socket and scheduling packet
receptions using the real-time simulator extensions.
@verbatim
for (;;)
{
...
len = recvfrom (m_sock, buf, bufferSize, 0, (struct sockaddr *)&addr,
&addrSize);
...
DynamicCast<RealtimeSimulatorImpl> (Simulator::GetImplementation ())->
ScheduleRealtimeNow (
MakeEvent (&EmuNetDevice::ForwardUp, this, buf, len));
...
}
@end verbatim
The line starting with our templated DynamicCast function probably deserves a
comment. It gains access to the simulator implementation object using
the @code{Simulator::GetImplementation} method and then casts to the real-time
simulator implementation to use the real-time schedule method
@code{ScheduleRealtimeNow}. This function will cause a handler for the newly
received packet to be scheduled for execution at the current real time clock
value. This will, in turn cause the simulation clock to be advanced to that
real time value when the scheduled event (@code{EmuNetDevice::ForwardUp}) is
fired.
The @code{ForwardUp} function operates as most other similar ns-3 net device
methods do. The packet is first filtered based on the destination address. In
the case of the @code{Emu} device, the MAC destination address will be the
address of the @code{Emu} device and not the hardware address of the real
device. Headers are then stripped off and the trace hooks are hit. Finally,
the packet is passed up the ns-3 protocol stack using the receive callback
function of the net device.
Sending a packet is equally straightforward as shown below. The first thing
we do is to add the ethernet header and trailer to the ns-3 @code{Packet} we
are sending. The source address corresponds to the address of the @code{Emu}
device and not the underlying native device MAC address. This is where the
MAC address spoofing is done. The trailer is added and we enqueue and dequeue
the packet from the net device queue to hit the trace hooks.
@verbatim
header.SetSource (source);
header.SetDestination (destination);
header.SetLengthType (packet->GetSize ());
packet->AddHeader (header);
EthernetTrailer trailer;
trailer.CalcFcs (packet);
packet->AddTrailer (trailer);
m_queue->Enqueue (packet);
packet = m_queue->Dequeue ();
struct sockaddr_ll ll;
bzero (&ll, sizeof (ll));
ll.sll_family = AF_PACKET;
ll.sll_ifindex = m_sll_ifindex;
ll.sll_protocol = htons(ETH_P_ALL);
rc = sendto (m_sock, packet->PeekData (), packet->GetSize (), 0,
reinterpret_cast<struct sockaddr *> (&ll), sizeof (ll));
@end verbatim
Finally, we simply send the packet to the raw socket which puts it out on the
real network.
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.

315
doc/manual/emulation.texi
View File

@@ -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 @@ We expect the typical use case for this environment will be to analyze the
behavior of native applications and protocol suites in the presence of large
simulated ns-3 networks.
@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.

6
doc/manual/flow-monitor.texi Normal file
View File

@@ -0,0 +1,6 @@
@node Flow Monitor
@chapter Flow Monitor
@cartouche
Placeholder chapter
@end cartouche

42
doc/manual/helpers.texi Normal file
View File

@@ -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.

229
doc/manual/internet.texi Normal file
View File

@@ -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

6
doc/manual/ipv4.texi Normal file
View File

@@ -0,0 +1,6 @@
@node IPv4
@chapter IPv4
@cartouche
Placeholder chapter
@end cartouche

6
doc/manual/ipv6.texi Normal file
View File

@@ -0,0 +1,6 @@
@node IPv6
@chapter IPv6
@cartouche
Placeholder chapter
@end cartouche

25
doc/manual/log.texi
View File

@@ -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

92
doc/manual/manual.texi
View File

@@ -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 @@ along with this program. If not, see @uref{http://www.gnu.org/licenses/}.
@include VERSION
@today{}
@c @page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@@ -86,42 +84,102 @@ Simulator version:
@end ifnottex
@menu
* Organization::
* Random variables::
* Callbacks::
* Object model::
* Attributes::
* Object names::
* Logging::
* Tracing::
* RealTime::
* Emulation::
* Packets::
* Sockets APIs::
* Node and Internet Stack::
* TCP::
* Routing overview::
* Wifi NetDevice::
* CSMA NetDevice::
* Helpers::
* Python::
* Node and NetDevices::
* Simple NetDevice::
* PointToPoint NetDevice::
* CSMA NetDevice::
* Wifi NetDevice::
* Mesh NetDevice::
* Bridge NetDevice::
* Emulation::
* Emu NetDevice::
* Tap NetDevice::
* Sockets APIs::
* Internet Stack::
* IPv4::
* IPv6::
* Routing overview::
* TCP::
* 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 emulation.texi
@include packets.texi
@include sockets.texi
@include helpers.texi
@include python.texi
@unnumbered Part 2: Nodes and NetDevices
@setchapternewpage off
@include node.texi
@c @include output.texi
@include tcp.texi
@include routing.texi
@include wifi.texi
@include csma.texi
@setchapternewpage odd
@include simple.texi
@include point-to-point.texi
@c @include other.texi
@include csma.texi
@include wifi.texi
@include mesh.texi
@include bridge.texi
@unnumbered Part 3: Emulation
@setchapternewpage off
@include emulation.texi
@include emu.texi
@include tap.texi
@setchapternewpage odd
@unnumbered Part 4: Internet Models
@setchapternewpage off
@include sockets.texi
@setchapternewpage odd
@include internet.texi
@include ipv4.texi
@include ipv6.texi
@include routing.texi
@include tcp.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

6
doc/manual/mesh.texi Normal file
View File

@@ -0,0 +1,6 @@
@node Mesh NetDevice
@chapter Mesh NetDevice
@cartouche
Placeholder chapter
@end cartouche

6
doc/manual/names.texi Normal file
View File

@@ -0,0 +1,6 @@
@node Object names
@chapter Object names
@cartouche
Placeholder chapter
@end cartouche

231
doc/manual/node.texi
View File

@@ -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 @@ The NodeList class provides an @code{Add()} method and C++ iterators
to allow one to walk the node list or fetch a Node pointer by
its integer identifier.
@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
The following chapters provide reference information on the available
NetDevices in ns-3.

50
doc/manual/organization.texi Normal file
View File

@@ -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

6
doc/manual/python.texi Normal file
View File

@@ -0,0 +1,6 @@
@node Python
@chapter Python
@cartouche
Placeholder chapter
@end cartouche

6
doc/manual/simple.texi Normal file
View File

@@ -0,0 +1,6 @@
@node Simple NetDevice
@chapter Simple NetDevice
@cartouche
Placeholder chapter
@end cartouche

9
doc/manual/statistics.texi
View File

@@ -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

7
doc/manual/tap.texi Normal file
View File

@@ -0,0 +1,7 @@
@node Tap NetDevice
@chapter Tap NetDevice
@cartouche
Placeholder chapter
@end cartouche

8
doc/manual/tracing.texi
View File

@@ -13,13 +13,13 @@ further study. In @command{ns-3}, the subsystem that enables a researcher to do
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 @@ core of the simulator;
sinks.
@end itemize
@node Implementation details
@node Tracing implementation details
@section Implementation details