some fixes to the manual for IPv4 refactoring
authorTom Henderson <tomh@tomh.org>
Thu, 02 Jul 2009 21:57:00 -0700
changeset 4646c25ca2e38845
parent 4645 d53223aae797
child 4647 b69bef7e00ed
some fixes to the manual for IPv4 refactoring
doc/manual/node.texi
doc/manual/routing.texi
     1.1 --- a/doc/manual/node.texi	Thu Jul 02 16:38:53 2009 +0200
     1.2 +++ b/doc/manual/node.texi	Thu Jul 02 21:57:00 2009 -0700
     1.3 @@ -121,86 +121,74 @@
     1.4  Internet Nodes are not subclasses of class Node; they are simply Nodes 
     1.5  that have had a bunch of IPv4-related
     1.6  objects aggregated to them.  They can be put together by hand, or
     1.7 -via a helper function @code{AddInternetStack ()} which does the 
     1.8 -following:
     1.9 +via a helper function @code{InternetStackHelper::Install ()} which does the 
    1.10 +following to all nodes passed in as arguments:
    1.11  @verbatim
    1.12 -void AddInternetStack (Ptr<Node> node)
    1.13 +void
    1.14 +InternetStackHelper::Install (Ptr<Node> node) const
    1.15  {
    1.16 -  // Create layer-3 protocols 
    1.17 -  Ptr<Ipv4L3Protocol> ipv4 = CreateObject<Ipv4L3Protocol> ();
    1.18 -  Ptr<ArpL3Protocol> arp = CreateObject<ArpL3Protocol> ();
    1.19 -  ipv4->SetNode (node);
    1.20 -  arp->SetNode (node);
    1.21 +  if (node->GetObject<Ipv4> () != 0)
    1.22 +    {
    1.23 +      NS_FATAL_ERROR ("InternetStackHelper::Install(): Aggregating "
    1.24 +                      "an InternetStack to a node with an existing Ipv4 object");
    1.25 +      return;
    1.26 +    }
    1.27  
    1.28 -  // Create an L4 demux 
    1.29 -  Ptr<Ipv4L4Demux> ipv4L4Demux = CreateObject<Ipv4L4Demux> ();
    1.30 +  CreateAndAggregateObjectFromTypeId (node, "ns3::ArpL3Protocol");
    1.31 +  CreateAndAggregateObjectFromTypeId (node, "ns3::Ipv4L3Protocol");
    1.32 +  CreateAndAggregateObjectFromTypeId (node, "ns3::Icmpv4L4Protocol");
    1.33 +  CreateAndAggregateObjectFromTypeId (node, "ns3::UdpL4Protocol");
    1.34 +  node->AggregateObject (m_tcpFactory.Create<Object> ());
    1.35 +  Ptr<PacketSocketFactory> factory = CreateObject<PacketSocketFactory> ();
    1.36 +  node->AggregateObject (factory);
    1.37 +  // Set routing
    1.38 +  Ptr<Ipv4> ipv4 = node->GetObject<Ipv4> ();
    1.39 +  Ptr<Ipv4RoutingProtocol> ipv4Routing = m_routing->Create (node);
    1.40 +  ipv4->SetRoutingProtocol (ipv4Routing);
    1.41 +}
    1.42 +@end verbatim
    1.43  
    1.44 -  // Create transport protocols and insert them into the demux
    1.45 -  Ptr<UdpL4Protocol> udp = CreateObject<UdpL4Protocol> ();
    1.46 -  Ptr<TcpL4Protocol> tcp = CreateObject<TcpL4Protocol> ();
    1.47 -  
    1.48 -  ipv4L4Demux->SetNode (node);
    1.49 -  udp->SetNode (node);
    1.50 -  tcp->SetNode (node);
    1.51 -  
    1.52 -  ipv4L4Demux->Insert (udp);
    1.53 -  ipv4L4Demux->Insert (tcp);
    1.54 -  
    1.55 -  // Add factories for instantiating transport protocol sockets
    1.56 -  Ptr<UdpSocketFactoryImpl> udpFactory = CreateObject<UdpSocketFactoryImpl> ();
    1.57 -  Ptr<TcpSocketFactoryImpl> tcpFactory = CreateObject<TcpSocketFactoryImpl> ();
    1.58 -  Ptr<Ipv4Impl> ipv4Impl = CreateObject<Ipv4Impl> ();
    1.59 -  
    1.60 -  udpFactory->SetUdp (udp);
    1.61 -  tcpFactory->SetTcp (tcp);
    1.62 -  ipv4Impl->SetIpv4 (ipv4);
    1.63 -  
    1.64 -  // Aggregate all of these new objects to the node
    1.65 -  node->AggregateObject (ipv4);
    1.66 -  node->AggregateObject (arp);
    1.67 -  node->AggregateObject (ipv4Impl);
    1.68 -  node->AggregateObject (udpFactory);
    1.69 -  node->AggregateObject (tcpFactory);
    1.70 -  node->AggregateObject (ipv4L4Demux);
    1.71 +Note that the Ipv4 routing protocol is configured and set outside this
    1.72 +function.  By default, the following protocols are added to Ipv4:
    1.73 +@verbatim
    1.74 +InternetStackHelper::InternetStackHelper ()
    1.75 +{
    1.76 +  SetTcp ("ns3::TcpL4Protocol");
    1.77 +  static Ipv4StaticRoutingHelper staticRouting;
    1.78 +  static Ipv4GlobalRoutingHelper globalRouting;
    1.79 +  static Ipv4ListRoutingHelper listRouting;
    1.80 +  listRouting.Add (staticRouting, 0);
    1.81 +  listRouting.Add (globalRouting, -10);
    1.82 +  SetRoutingHelper (listRouting);
    1.83  }
    1.84  @end verbatim
    1.85  
    1.86  @subsection Internet Node structure
    1.87  
    1.88 -The Internet Node (an ns-3 Node augmented by aggregation to have one or more
    1.89 +An IPv4-capable Node (an ns-3 Node augmented by aggregation to have one or more
    1.90  IP stacks) has the following internal structure.
    1.91  
    1.92  @subsubsection Layer-3 protocols
    1.93  At the lowest layer, sitting above the NetDevices, are the "layer 3" 
    1.94 -protocols, including IPv4, IPv6, and ARP.  These protocols provide 
    1.95 -the following key methods and data members:
    1.96 +protocols, including IPv4, IPv6 (in the future), and ARP.  The 
    1.97 +@code{class Ipv4L3Protocol} is an 
    1.98 +implementation class whose public interface is 
    1.99 +typically @code{class Ipv4} (found in src/node directory), but the 
   1.100 +Ipv4L3Protocol public API is also used internally in the 
   1.101 +src/internet-stack directory at present.
   1.102  
   1.103 +In class Ipv4L3Protocol, one method described below is @code{Receive ()}:
   1.104  @verbatim
   1.105 -class Ipv4L3Protocol : public Object
   1.106 -{
   1.107 -public: 
   1.108 -  // Add an Ipv4 interface corresponding to the provided NetDevice
   1.109 -  uint32_t AddInterface (Ptr<NetDevice> device);
   1.110 -
   1.111 -  // Receive function that can be bound to a callback, for receiving
   1.112 -  // packets up the stack
   1.113 -  void Receive( Ptr<NetDevice> device, Ptr<Packet> p, uint16_t protocol, 
   1.114 -    const Address &from);
   1.115 -
   1.116 -  // Higher-level layers call this method to send a packet
   1.117 -  // down the stack to the MAC and PHY layers
   1.118 -  // 
   1.119 -  void Send (Ptr<Packet> packet, Ipv4Address source,
   1.120 -             Ipv4Address destination, uint8_t protocol);
   1.121 -
   1.122 -private:
   1.123 -  Ipv4InterfaceList m_interfaces;
   1.124 -
   1.125 -  // Protocol handlers
   1.126 -}
   1.127 + /**
   1.128 +   * Lower layer calls this method after calling L3Demux::Lookup
   1.129 +   * The ARP subclass needs to know from which NetDevice this
   1.130 +   * packet is coming to:
   1.131 +   *    - implement a per-NetDevice ARP cache
   1.132 +   *    - send back arp replies on the right device
   1.133 +   */
   1.134 +  void Receive( Ptr<NetDevice> device, Ptr<const Packet> p, uint16_t protocol, const Address &from,
   1.135 +                const Address &to, NetDevice::PacketType packetType);
   1.136  @end verbatim
   1.137 -There are many more functions (such as @code{Forward ()}) but we will
   1.138 -focus on the above four items from an architectural perspective.
   1.139  
   1.140  First, note that the @code{Receive ()} function has a matching signature
   1.141  to the ReceiveCallback in the @code{class Node}.  This function pointer
   1.142 @@ -228,24 +216,15 @@
   1.143  This class nicely demonstrates two techniques we exploit in
   1.144  ns-3 to bind objects together:  callbacks, and object aggregation.
   1.145  
   1.146 -Once IPv4 has determined that a packet is for the local node, it 
   1.147 +Once IPv4 routing has determined that a packet is for the local node, it 
   1.148  forwards it up the stack.  This is done with the following function:
   1.149  
   1.150  @verbatim
   1.151  void
   1.152 -Ipv4L3Protocol::ForwardUp (Ptr<Packet> p, Ipv4Header const&ip,
   1.153 -                           Ptr<Ipv4Interface> incomingInterface)
   1.154 -{
   1.155 -  NS_LOG_FUNCTION (this << p << &ip);
   1.156 -
   1.157 -  Ptr<Ipv4L4Demux> demux = m_node->GetObject<Ipv4L4Demux> ();
   1.158 -  Ptr<Ipv4L4Protocol> protocol = demux->GetProtocol (ip.GetProtocol ());
   1.159 -  protocol->Receive (p, ip.GetSource (), ip.GetDestination (), incomingInterface);
   1.160 -}
   1.161 +Ipv4L3Protocol::LocalDeliver (Ptr<const Packet> packet, Ipv4Header const&ip, uint32_t iif)
   1.162  @end verbatim
   1.163  
   1.164 -The first step is to find the aggregated Ipv4L4Demux object.  Then, this
   1.165 -object is consulted to look up the right Ipv4L4Protocol, based on IP protocol
   1.166 +The first step is to find the right Ipv4L4Protocol object , based on IP protocol
   1.167  number.  For instance, TCP is registered in the demux as protocol number 6.
   1.168  Finally, the @code{Receive()} function on the Ipv4L4Protocol (such as
   1.169  @code{TcpL4Protocol::Receive} is called.
   1.170 @@ -321,10 +300,10 @@
   1.171  address) associated with the socket, and a receive callback for the socket.
   1.172  @end itemize
   1.173  
   1.174 -@subsection Internet Node interfaces
   1.175 +@subsection Ipv4-capable node interfaces
   1.176  
   1.177  Many of the implementation details, or internal objects themselves, 
   1.178 -of Internet Node objects are not exposed at the simulator public
   1.179 +of Ipv4-capable Node objects are not exposed at the simulator public
   1.180  API.  This allows for different implementations; for instance, 
   1.181  replacing the native ns-3 models with ported TCP/IP stack code. 
   1.182   
     2.1 --- a/doc/manual/routing.texi	Thu Jul 02 16:38:53 2009 +0200
     2.2 +++ b/doc/manual/routing.texi	Thu Jul 02 21:57:00 2009 -0700
     2.3 @@ -106,18 +106,26 @@
     2.4  Presently, global centralized IPv4 unicast routing over both 
     2.5  point-to-point and shared (CSMA) links is supported.
     2.6  
     2.7 +By default, when using the ns-3 helper API and the default InternetStackHelper,
     2.8 +global routing capability will be added  to the node, and global routing
     2.9 +will be inserted as a routing protocol with lower priority than the
    2.10 +static routes (i.e., users can insert routes via Ipv4StaticRouting API
    2.11 +and they will take precedence over routes found by global routing).
    2.12 +
    2.13  @subsection Global Unicast Routing API
    2.14  
    2.15  The public API is very minimal.  User scripts include the following:
    2.16  @verbatim
    2.17 -#include "ns3/global-route-manager.h"
    2.18 +#include "ns3/helper-module.h"
    2.19  @end verbatim
    2.20  
    2.21 +If the default InternetStackHelper is used, then an instance of
    2.22 +global routing will be aggregated to each node.
    2.23  After IP addresses are configured, the following function call will
    2.24  cause all of the nodes that have an Ipv4 interface to receive
    2.25  forwarding tables entered automatically by the GlobalRouteManager:
    2.26  @verbatim
    2.27 -  GlobalRouteManager::PopulateRoutingTables ();
    2.28 +  Ipv4GlobalRoutingHelper::PopulateRoutingTables ();
    2.29  @end verbatim
    2.30  
    2.31  @emph{Note:} A reminder that the wifi NetDevice will work but does not
    2.32 @@ -127,7 +135,7 @@
    2.33  It is possible to call this function again in the midst of a simulation
    2.34  using the following additional public function:
    2.35  @verbatim
    2.36 -  GlobalRouteManager::RecomputeRoutingTables ();
    2.37 +  Ipv4GlobalRoutingHelper::RecomputeRoutingTables ();
    2.38  @end verbatim
    2.39  which flushes the old tables, queries the nodes for new interface information,
    2.40  and rebuilds the routes.
    2.41 @@ -135,7 +143,7 @@
    2.42  For instance, this scheduling call will cause the tables to be rebuilt
    2.43  at time 5 seconds:
    2.44  @verbatim
    2.45 -  Simulator::Schedule (Seconds (5),&GlobalRouteManager::RecomputeRoutingTables);
    2.46 +  Simulator::Schedule (Seconds (5),&Ipv4GlobalRoutingHelper::RecomputeRoutingTables);
    2.47  @end verbatim
    2.48  
    2.49  @subsection Global Routing Implementation