@c ========================================================================

@c Other Network Topologies

@c ========================================================================

@node Other-network-topologies

@chapter Other Network Topologies

@cindex topology

@cindex Channel

@cindex NetDevice

@cindex topology!bus

@cindex topology!point-to-point

@cindex PointToPointChannel

@cindex PointToPointNetDevice

@emph{Network topology} is the study of the arrangement of of the elements

(in @command{ns-3} represented by the classes @code{Channel} and @code{Node})

of a network.  Two fundamental types of physical topologies are the 

@emph{point-to-point} and @emph{bus} topologies.  We have already been exposed

to the @command{ns-3} channel specialization named @code{CsmaChannel}.  This is

a simulation of a bus network.  We also provide a simulation of a 

point-to-point channel with associated net devices.  As described previously,

the associated C++ classes specialize the @command{ns-3} base classes

@code{NetDevice} and @code{Channel} and are called @code{PointToPointNetDevice}

and @code{PointToPointChannel} respectively.

We will use combinations of these bus and point-to-point topology elements

to show how to create several commonly seen network topologies.

@section A Point-to-Point Network

We're going to take what might be seen as a step backward and look at a simple

point-to-point network.  We will be building the simplest network you can 

imagine.  A serial link (point to point) between two computers.  When you

see this point-to-point network, you can think of an RS-422 (or RS-232 for 

you old-timers) cable.  This topology is shown below.

@sp 1

@center @image{figures/pp,,,,png}

@cindex CreateObject

@cindex InternetNode

We have provided a file for you in the @code{tutorial}

directory called @code{tutorial-point-to-point.cc}.  You should now be

familiar enough with the system to pick out fairly easily what has been

changed.  Let's focus on the following lines:

@verbatim

  Ptr<Node> n0 = CreateObject<InternetNode> ();

  Ptr<Node> n1 = CreateObject<InternetNode> ();

  Ptr<PointToPointChannel> link = PointToPointTopology::AddPointToPointLink (

    n0, n1, DataRate (38400), MilliSeconds (20));

  PointToPointTopology::AddIpv4Addresses (link, n0, "10.1.1.1",

    n1, "10.1.1.2");

@end verbatim

You can see that we created two @code{InternetNode} objects in the usual way.

Then, instead of creating a @code{CsmaChannel} we create a 

@code{PointToPointChannel}.  This point-to-point channel, which we call

@code{link}, connects node zero (@code{n0}) and node one (@code{n1}) over a

simulated link that runs at 38400 bits per second and has a 20 millisecond

simulated speed-of-light delay.  This call also creates appropriate net devices

and attaches them to nodes zero and one.

We then add IP addresses to the net devices we just created using the topology

helper @code{AddIpv4Addresses}.  Node zero gets the IP address 10.1.1.1 and

node one gets the IP address 10.1.1.2 assigned.  

The alert tutorial user may wonder what the network number or prefix is of

those IP addresses.  The point-to-point topology assumes that you want a

@code{/30} subnet and assigns an appropriate net mask for you.  It then then

@emph{asserts} that the network numbers of the two net devices match.  So there

is an implicit network mask created down in the topology code that looks like,

@verbatim

  Ipv4Mask netmask("255.255.255.252");

@end verbatim

The rest of the code you should recognize and understand.  We are just going

to echo one packet across the point-to-point link.  You should be now be able

to build and run this example and to locate and interpret the ASCII trace 

file.  This is left as an exercise for you.

The file @code{tutorial-point-to-point.cc} is reproduced here for your 

convenience:

@verbatim

/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */

/*

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License version 2 as

 * published by the Free Software Foundation;

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

 */

#include "ns3/log.h"

#include "ns3/ptr.h"

#include "ns3/internet-stack.h"

#include "ns3/point-to-point-channel.h"

#include "ns3/mac48-address.h"

#include "ns3/point-to-point-net-device.h"

#include "ns3/point-to-point-topology.h"

#include "ns3/udp-echo-client.h"

#include "ns3/udp-echo-server.h"

#include "ns3/simulator.h"

#include "ns3/nstime.h"

#include "ns3/ascii-trace.h"

#include "ns3/pcap-trace.h"

#include "ns3/global-route-manager.h"

NS_LOG_COMPONENT_DEFINE ("PointToPointSimulation");

using namespace ns3;

// Network topology

//

//                       point to point

//                      +--------------+

//                      |              |

//                     n0             n1

//

int 

main (int argc, char *argv[])

{

  LogComponentEnable ("PointToPointSimulation", LOG_LEVEL_INFO);

  NS_LOG_INFO ("Point to Point Topology Simulation");

  Ptr<Node> n0 = CreateObject<InternetNode> ();

  Ptr<Node> n1 = CreateObject<InternetNode> ();

  Ptr<PointToPointChannel> link = PointToPointTopology::AddPointToPointLink (

    n0, n1, DataRate (38400), MilliSeconds (20));

  PointToPointTopology::AddIpv4Addresses (link, n0, "10.1.1.1", 

    n1, "10.1.1.2");

  uint16_t port = 7;

  Ptr<UdpEchoClient> client = CreateObject<UdpEchoClient> (n0, "10.1.1.2", 

    port, 1, Seconds(1.), 1024);

  Ptr<UdpEchoServer> server = CreateObject<UdpEchoServer> (n1, port);

  server->Start(Seconds(1.));

  client->Start(Seconds(2.));

  server->Stop (Seconds(10.));

  client->Stop (Seconds(10.));

  AsciiTrace asciitrace ("tutorial.tr");

  asciitrace.TraceAllQueues ();

  asciitrace.TraceAllNetDeviceRx ();

  Simulator::Run ();

  Simulator::Destroy ();

}

@end verbatim

@section A Star Network

A point-to-point network is considered a special case of a star network.  As

you might expect, the process of constructing a star network is an extension

of the very simple process used for a point-to-point link.  We have provided

a file for you in the @code{tutorial} directory called @code{tutorial-star.cc}

that implements a simple star network as seen below.

@sp 1

@center @image{figures/star,,,,png}

In order to create a star network, we need to be able to instantiate some

number (greater than one) of net devices on a node.  In the name of simplicity

of use, the @code{PointToPointTopology} topology helper does not allow one to

do this.  We provided a separate topology helper class, the 

@code{PointToPointIpv4Topology} helper class that provides the slightly finer

granularity we need to accomplish a star network.  In order to use this new

helper we have to load the definitions by including the appropriate file.

@verbatim

  #include "ns3/point-to-point-ipv4-topology.h"

@end verbatim

The star that we're going to create has a node in the center (@code{n0}) with

six nodes surrounding (@code{n1} - @code{n6}).  You should be able to easily

find and understand the code that creates these nodes.

@verbatim

  Ptr<Node> n0 = CreateObject<InternetNode> ();

  Ptr<Node> n1 = CreateObject<InternetNode> ();

  Ptr<Node> n2 = CreateObject<InternetNode> ();

  Ptr<Node> n3 = CreateObject<InternetNode> ();

  Ptr<Node> n4 = CreateObject<InternetNode> ();

  Ptr<Node> n5 = CreateObject<InternetNode> ();

  Ptr<Node> n6 = CreateObject<InternetNode> ();

@end verbatim

Next, we get into the differences between the @code{PointToPointTopology}

helper and the @code{PointToPointIpv4Topology} helper.  The

@code{PointToPointIpv4Topology} helper looks and feels a little like the 

@code{CsmaIpv4Topology} helper.  Just like you created a CSMA channel 

previously, you need to create a point-to-point channel.  The following

code creates a @code{PointToPointChannel} and calls it @code{link01}.  You can

interpret this name as being the channel (or @emph{link}) from node zero to 

node one.  

@verbatim

  Ptr<PointToPointChannel> link01 =

    PointToPointIpv4Topology::CreateChannel (DataRate (38400),

    MilliSeconds (20));

@end verbatim

You need to provide a data rate for the channel which we set at 38400 bits 

per second.  You must also provide a speed-of-light delay which we set at

20 milliseconds.

Just as you added a net device to the nodes in the CSMA tutorial section, you

do the same here but with a point-to-point net device.  The following code

illustrates how we do that:

@verbatim

  uint32_t nd01 = PointToPointIpv4Topology::AddNetDevice (n0,

    link01);

@end verbatim

We call the @code{PointToPointIpv4Topology} helper and ask it to add a net

device to node zero (@code{n0}) and connect it to the appropriate 

point-to-point link (@code{link01}) which you will recall is the serial link

from node zero to node one.

If you look at the following code, you will see the same calls are repeated

to create the remaining five point-to-point channels and connect them

to net devices on node zero.

The next new code is found after the ``spokes'' of the star have been created.

It looks like the following:

@verbatim

  uint32_t nd1 = PointToPointIpv4Topology::AddNetDevice (n1, link01);

  uint32_t nd2 = PointToPointIpv4Topology::AddNetDevice (n2, link02);

  uint32_t nd3 = PointToPointIpv4Topology::AddNetDevice (n3, link03);

  uint32_t nd4 = PointToPointIpv4Topology::AddNetDevice (n4, link04);

  uint32_t nd5 = PointToPointIpv4Topology::AddNetDevice (n5, link05);

  uint32_t nd6 = PointToPointIpv4Topology::AddNetDevice (n6, link06);

@end verbatim

Here we are creating the net devices on the nodes surrounding the center node.

In the first call, we are adding a net device on node one (@code{n1}) and

connecting that net device to the channel named @code{link01}.  Remember that

we created the channel @code{link01} as the channel connecting node zero and

node one.  We previously created a net device on node zero and attached that

device to @code{link01}.  Here we are connecting the other side of that link

to node one.  The return value from this call is the net device index of the

created net device.

The next section of code adds addresses to the net devices we just created.

The first call adds the IP address 10.1.1.1 to the net device going from 

node zero to node one.  Recall that we first created a node named @code{n0}

and a channel called @code{link01}.  We added a net device to @code{n0} and

remembered the net device index as the @code{uint32_t nd01}.  This meant

the net device @emph{nd} on node @emph{0} that we connected to node @emph{1}. 

We call @code{AddAddress} to add an IP address (10.1.1.1) to the net device

on node zero identified by the net device index @code{nd01}.  We provide a

net mask suitable for a point to point network.  This is typically a /30 

address but we don't force that in this API.

After setting up the address on node zero, we do the same for the node on

the other end of the ``spoke'' --- in this case node one, with its single

net device.  Note that the network number is the same on both sides of this

network.

@verbatim

  PointToPointIpv4Topology::AddAddress (n0, nd01, "10.1.1.1",

    ``255.255.255.252'');

  PointToPointIpv4Topology::AddAddress (n1, nd1, "10.1.1.2",

    ``255.255.255.252'');

@end verbatim

The following code repeats this pattern assining similar IP addresses to the

remaining net devices.  Note that there are no @code{Mac48Address} address

assignments --- they are not required.

The rest of the code you should recognize and understand.  We are just going

to echo one packet across the point-to-point link.  You should be now be able

to build and run this example and to locate and interpret the ASCII trace 

file.  This is left as an exercise for you.

The file @code{tutorial-star.cc} is reproduced here for your convenience:

@verbatim

/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */

/*

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License version 2 as

 * published by the Free Software Foundation;

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

 */

#include "ns3/log.h"

#include "ns3/ptr.h"

#include "ns3/internet-stack.h"

#include "ns3/point-to-point-channel.h"

#include "ns3/mac48-address.h"

#include "ns3/point-to-point-net-device.h"

#include "ns3/point-to-point-ipv4-topology.h"

#include "ns3/udp-echo-client.h"

#include "ns3/udp-echo-server.h"

#include "ns3/simulator.h"

#include "ns3/nstime.h"

#include "ns3/ascii-trace.h"

#include "ns3/pcap-trace.h"

#include "ns3/global-route-manager.h"

NS_LOG_COMPONENT_DEFINE ("StarSimulation");

using namespace ns3;

// Network topology

//

//                  n3    n2

//                   |   /

//                    | /

//              n4 --- n0 --- n1

//                    /  |

//                   /    |

//                  n5    n6

int 

main (int argc, char *argv[])

{

  LogComponentEnable ("StarSimulation", LOG_LEVEL_INFO);

  NS_LOG_INFO ("Star Topology Simulation");

  Ptr<Node> n0 = CreateObject<InternetNode> ();

  Ptr<Node> n1 = CreateObject<InternetNode> ();

  Ptr<Node> n2 = CreateObject<InternetNode> ();

  Ptr<Node> n3 = CreateObject<InternetNode> ();

  Ptr<Node> n4 = CreateObject<InternetNode> ();

  Ptr<Node> n5 = CreateObject<InternetNode> ();

  Ptr<Node> n6 = CreateObject<InternetNode> ();

  Ptr<PointToPointChannel> link01 = 

    PointToPointIpv4Topology::CreateChannel (DataRate (38400), 

    MilliSeconds (20));

  uint32_t nd01 = PointToPointIpv4Topology::AddNetDevice (n0,

    link01);

  Ptr<PointToPointChannel> link02 = 

    PointToPointIpv4Topology::CreateChannel (DataRate (38400), 

    MilliSeconds (20));

  uint32_t nd02 = PointToPointIpv4Topology::AddNetDevice (n0,

    link02);

  Ptr<PointToPointChannel> link03 = 

    PointToPointIpv4Topology::CreateChannel (DataRate (38400), 

    MilliSeconds (20));

  uint32_t nd03 = PointToPointIpv4Topology::AddNetDevice (n0,

    link03);

  Ptr<PointToPointChannel> link04 = 

    PointToPointIpv4Topology::CreateChannel (DataRate (38400), 

    MilliSeconds (20));

  uint32_t nd04 = PointToPointIpv4Topology::AddNetDevice (n0, 

    link04);

  Ptr<PointToPointChannel> link05 = 

    PointToPointIpv4Topology::CreateChannel (DataRate (38400), 

    MilliSeconds (20));

  uint32_t nd05 = PointToPointIpv4Topology::AddNetDevice (n0,

    link05);

  Ptr<PointToPointChannel> link06 = 

    PointToPointIpv4Topology::CreateChannel (DataRate (38400), 

    MilliSeconds (20));

  uint32_t nd06 = PointToPointIpv4Topology::AddNetDevice (n0, link06);

  uint32_t nd1 = PointToPointIpv4Topology::AddNetDevice (n1, link01);

  uint32_t nd2 = PointToPointIpv4Topology::AddNetDevice (n2, link02);

  uint32_t nd3 = PointToPointIpv4Topology::AddNetDevice (n3, link03);

  uint32_t nd4 = PointToPointIpv4Topology::AddNetDevice (n4, link04);

  uint32_t nd5 = PointToPointIpv4Topology::AddNetDevice (n5, link05);

  uint32_t nd6 = PointToPointIpv4Topology::AddNetDevice (n6, link06);

  PointToPointIpv4Topology::AddAddress (n0, nd01, "10.1.1.1", 

    "255.255.255.252");

  PointToPointIpv4Topology::AddAddress (n1, nd1, "10.1.1.2", 

    "255.255.255.252");

  PointToPointIpv4Topology::AddAddress (n0, nd02, "10.1.2.1", 

    "255.255.255.252");

  PointToPointIpv4Topology::AddAddress (n2, nd2, "10.1.2.2", 

    "255.255.255.252");

  PointToPointIpv4Topology::AddAddress (n0, nd03, "10.1.3.1", 

    "255.255.255.252");

  PointToPointIpv4Topology::AddAddress (n3, nd3, "10.1.2.2", 

    "255.255.255.252");

  PointToPointIpv4Topology::AddAddress (n0, nd04, "10.1.4.1", 

    "255.255.255.252");

  PointToPointIpv4Topology::AddAddress (n4, nd4, "10.1.4.2", 

    "255.255.255.252");

  PointToPointIpv4Topology::AddAddress (n0, nd05, "10.1.5.1", 

    "255.255.255.252");

  PointToPointIpv4Topology::AddAddress (n5, nd5, "10.1.5.2", 

    "255.255.255.252");

  PointToPointIpv4Topology::AddAddress (n0, nd06, "10.1.6.1", 

    "255.255.255.252");

  PointToPointIpv4Topology::AddAddress (n6, nd6, "10.1.6.2", 

    "255.255.255.252");

  uint16_t port = 7;

  Ptr<UdpEchoClient> client = CreateObject<UdpEchoClient> (n0, "10.1.1.2", 

    port, 1, Seconds(1.), 1024);

  Ptr<UdpEchoServer> server = CreateObject<UdpEchoServer> (n1, port);

  server->Start(Seconds(1.));

  client->Start(Seconds(2.));

  server->Stop (Seconds(10.));

  client->Stop (Seconds(10.));

  AsciiTrace asciitrace ("tutorial.tr");

  asciitrace.TraceAllQueues ();

  asciitrace.TraceAllNetDeviceRx ();

  Simulator::Run ();

  Simulator::Destroy ();

}

@end verbatim

@subsection Routing

If you are really excited about this simulator you may have already tried to

modify the scripts outside the tutorial.  I know that one of the first things

that would have occurred to me when I saw the star network would have been to

start trying to add applications to echo packets from nodes other than zero.

If you tried, for example, to start the echo client on node one instead of

node zero, you would have found an empty trace file.  The reason for this

is that you have now created an internetwork.  This means you will need to 

enable internetwork routing.

We have provided a file for you in the @code{tutorial} directory called 

@code{tutorial-star-routing.cc} to show you how this is done.  This extremely

tricky and difficult change is shown below:

@verbatim 

 GlobalRouteManager::PopulateRoutingTables ();

@end verbatim

This one-line addition, located just before the simulation runs, tells the 

@command{ns-3} @emph{global route manager} to walk the topology you created and 

build internetwork routing tables for all of the nodes in the simulation.

We changed the client application so that it runs on node four:

@verbatim

  Ptr<UdpEchoClient> client = CreateObject<UdpEchoClient> (n4, "10.1.1.2", 

    port, 1, Seconds(1.), 1024);

@end verbatim

Now if you build and run @code{tutorial-star-routing.cc} you can examine the

@code{tutorial.tr} file and see that your UDP echo packets are now correctly

routed through the topology.

@section A Dumbbell Network

One of the most interesting simple topologies (from a phenomenological point of

view) is commonly called a dumbbell network.  The name derives from a 

superficial similarity in form to a piece of exercise equipment.

The dumbbell model is typically composed of two bus or star network elements

connected via a point-to-point link.  The point-to-point link is usually 

configured with a lower bandwidth than the bus elements to provide a 

@emph{choke point}.

The following is a representation of the topology.

@sp 1

@center @image{figures/dumbbell,,,,png}

We have provided a file that constructs this dumbbell network and creates 

enough data flowing across the choke point that some packets will be dropped.

The file is called @code{tutorial-linear-dumbbell.cc} and is located in the 

@code{tutorial} directory.  We have already covered all of the code used to

create this network, so we will just quickly go over the main sections of the

script.

The first section creates a CSMA lan that will become the left side of the

dumbbell network.  This code should be very familiar since we used the same

process to create our first example.

@verbatim

//

// Create the lan on the left side of the dumbbell.

//

  Ptr<Node> n0 = CreateObject<InternetNode> ();

  Ptr<Node> n1 = CreateObject<InternetNode> ();

  Ptr<Node> n2 = CreateObject<InternetNode> ();

  Ptr<Node> n3 = CreateObject<InternetNode> ();