some fixes to the manual for IPv4 refactoring
authorTom Henderson <>
Thu, 02 Jul 2009 21:57:00 -0700
changeset 4646 c25ca2e38845
parent 4645 d53223aae797
child 4647 b69bef7e00ed
some fixes to the manual for IPv4 refactoring
--- a/doc/manual/node.texi	Thu Jul 02 16:38:53 2009 +0200
+++ b/doc/manual/node.texi	Thu Jul 02 21:57:00 2009 -0700
@@ -121,86 +121,74 @@
 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{AddInternetStack ()} which does the 
+via a helper function @code{InternetStackHelper::Install ()} which does the 
+following to all nodes passed in as arguments:
-void AddInternetStack (Ptr<Node> node)
+InternetStackHelper::Install (Ptr<Node> node) const
-  // Create layer-3 protocols 
-  Ptr<Ipv4L3Protocol> ipv4 = CreateObject<Ipv4L3Protocol> ();
-  Ptr<ArpL3Protocol> arp = CreateObject<ArpL3Protocol> ();
-  ipv4->SetNode (node);
-  arp->SetNode (node);
-  // Create an L4 demux 
-  Ptr<Ipv4L4Demux> ipv4L4Demux = CreateObject<Ipv4L4Demux> ();
+  if (node->GetObject<Ipv4> () != 0)
+    {
+      NS_FATAL_ERROR ("InternetStackHelper::Install(): Aggregating "
+                      "an InternetStack to a node with an existing Ipv4 object");
+      return;
+    }
-  // Create transport protocols and insert them into the demux
-  Ptr<UdpL4Protocol> udp = CreateObject<UdpL4Protocol> ();
-  Ptr<TcpL4Protocol> tcp = CreateObject<TcpL4Protocol> ();
-  ipv4L4Demux->SetNode (node);
-  udp->SetNode (node);
-  tcp->SetNode (node);
-  ipv4L4Demux->Insert (udp);
-  ipv4L4Demux->Insert (tcp);
-  // Add factories for instantiating transport protocol sockets
-  Ptr<UdpSocketFactoryImpl> udpFactory = CreateObject<UdpSocketFactoryImpl> ();
-  Ptr<TcpSocketFactoryImpl> tcpFactory = CreateObject<TcpSocketFactoryImpl> ();
-  Ptr<Ipv4Impl> ipv4Impl = CreateObject<Ipv4Impl> ();
-  udpFactory->SetUdp (udp);
-  tcpFactory->SetTcp (tcp);
-  ipv4Impl->SetIpv4 (ipv4);
-  // Aggregate all of these new objects to the node
-  node->AggregateObject (ipv4);
-  node->AggregateObject (arp);
-  node->AggregateObject (ipv4Impl);
-  node->AggregateObject (udpFactory);
-  node->AggregateObject (tcpFactory);
-  node->AggregateObject (ipv4L4Demux);
+  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:
+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
-The Internet Node (an ns-3 Node augmented by aggregation to have one or more
+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, and ARP.  These protocols provide 
-the following key methods and data members:
-class Ipv4L3Protocol : public Object
-  // Add an Ipv4 interface corresponding to the provided NetDevice
-  uint32_t AddInterface (Ptr<NetDevice> device);
-  // Receive function that can be bound to a callback, for receiving
-  // packets up the stack
-  void Receive( Ptr<NetDevice> device, Ptr<Packet> p, uint16_t protocol, 
-    const Address &from);
+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.
-  // Higher-level layers call this method to send a packet
-  // down the stack to the MAC and PHY layers
-  // 
-  void Send (Ptr<Packet> packet, Ipv4Address source,
-             Ipv4Address destination, uint8_t protocol);
-  Ipv4InterfaceList m_interfaces;
-  // Protocol handlers
+In class Ipv4L3Protocol, one method described below is @code{Receive ()}:
+ /**
+   * Lower layer calls this method after calling L3Demux::Lookup
+   * The ARP subclass needs to know from which NetDevice this
+   * packet is coming to:
+   *    - implement a per-NetDevice ARP cache
+   *    - send back arp replies on the right device
+   */
+  void Receive( Ptr<NetDevice> device, Ptr<const Packet> p, uint16_t protocol, const Address &from,
+                const Address &to, NetDevice::PacketType packetType);
 @end verbatim
-There are many more functions (such as @code{Forward ()}) but we will
-focus on the above four items from an architectural perspective.
 First, note that the @code{Receive ()} function has a matching signature
 to the ReceiveCallback in the @code{class Node}.  This function pointer
@@ -228,24 +216,15 @@
 This class nicely demonstrates two techniques we exploit in
 ns-3 to bind objects together:  callbacks, and object aggregation.
-Once IPv4 has determined that a packet is for the local node, it 
+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:
-Ipv4L3Protocol::ForwardUp (Ptr<Packet> p, Ipv4Header const&ip,
-                           Ptr<Ipv4Interface> incomingInterface)
-  NS_LOG_FUNCTION (this << p << &ip);
-  Ptr<Ipv4L4Demux> demux = m_node->GetObject<Ipv4L4Demux> ();
-  Ptr<Ipv4L4Protocol> protocol = demux->GetProtocol (ip.GetProtocol ());
-  protocol->Receive (p, ip.GetSource (), ip.GetDestination (), incomingInterface);
+Ipv4L3Protocol::LocalDeliver (Ptr<const Packet> packet, Ipv4Header const&ip, uint32_t iif)
 @end verbatim
-The first step is to find the aggregated Ipv4L4Demux object.  Then, this
-object is consulted to look up the right Ipv4L4Protocol, based on IP protocol
+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.
@@ -321,10 +300,10 @@
 address) associated with the socket, and a receive callback for the socket.
 @end itemize
-@subsection Internet Node interfaces
+@subsection Ipv4-capable node interfaces
 Many of the implementation details, or internal objects themselves, 
-of Internet Node objects are not exposed at the simulator public
+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. 
--- a/doc/manual/routing.texi	Thu Jul 02 16:38:53 2009 +0200
+++ b/doc/manual/routing.texi	Thu Jul 02 21:57:00 2009 -0700
@@ -106,18 +106,26 @@
 Presently, global centralized IPv4 unicast routing over both 
 point-to-point and shared (CSMA) links is supported.
+By default, when using the ns-3 helper API and the default InternetStackHelper,
+global routing capability will be added  to the node, and global routing
+will be inserted as a routing protocol with lower priority than the
+static routes (i.e., users can insert routes via Ipv4StaticRouting API
+and they will take precedence over routes found by global routing).
 @subsection Global Unicast Routing API
 The public API is very minimal.  User scripts include the following:
-#include "ns3/global-route-manager.h"
+#include "ns3/helper-module.h"
 @end verbatim
+If the default InternetStackHelper is used, then an instance of
+global routing will be aggregated to each node.
 After IP addresses are configured, the following function call will
 cause all of the nodes that have an Ipv4 interface to receive
 forwarding tables entered automatically by the GlobalRouteManager:
-  GlobalRouteManager::PopulateRoutingTables ();
+  Ipv4GlobalRoutingHelper::PopulateRoutingTables ();
 @end verbatim
 @emph{Note:} A reminder that the wifi NetDevice will work but does not
@@ -127,7 +135,7 @@
 It is possible to call this function again in the midst of a simulation
 using the following additional public function:
-  GlobalRouteManager::RecomputeRoutingTables ();
+  Ipv4GlobalRoutingHelper::RecomputeRoutingTables ();
 @end verbatim
 which flushes the old tables, queries the nodes for new interface information,
 and rebuilds the routes.
@@ -135,7 +143,7 @@
 For instance, this scheduling call will cause the tables to be rebuilt
 at time 5 seconds:
-  Simulator::Schedule (Seconds (5),&GlobalRouteManager::RecomputeRoutingTables);
+  Simulator::Schedule (Seconds (5),&Ipv4GlobalRoutingHelper::RecomputeRoutingTables);
 @end verbatim
 @subsection Global Routing Implementation