revise README

README.routing

@@ -1,31 +1,52 @@
-Routing overview, mid-July
-
-This is a proposal to add global static routing to ns-3
-
-The previously announced roadmap:
-* July 15: Support IPv4 static routing with PointToPoint numbered links
-* August 15: Extend IPv4 static routing to Ethernet (shared links), add static multicast forwarding over Ethernet and PointToPoint
-* Sept 15: Add static multicast forwarding over wireless interface 
-
-This would provide the first bullet above.
-
-Note:  This is orthogonal to Gustavo's OLSR code, but could also exist
-as a static routing protocol in the framework that he proposes; right now,
-this just writes directly into the existing Ipv4 routing API 
-
-1.  Code:
-
-- source code is in a routing module src/routing/
-- an example script is in examples/simple-static-routing.cc
-- StaticRouteManager is added in the run-tests unit tests
-
-2.  Approach
+Static routing overview
+---------------
 
+This is brief documentation of a proposal to add global static routing to ns-3
 Static routing is used to automatically populate the forwarding tables
 in a topology without running a dynamic routing protocol or asking
 the user to manually enter routes themselves.  
 
-A single object (StaticRouteManager) is responsible for populating
+The previously announced roadmap:
+* July 15: Support IPv4 static routing with PointToPoint numbered links
+* August 15: Extend IPv4 static routing to Ethernet (shared links), 
+add static multicast forwarding over Ethernet and PointToPoint
+* Sept 15: Add static multicast forwarding over wireless interface 
+
+This code would provide the first bullet above.
+
+Note:  This is orthogonal to Gustavo's OLSR code, but could also exist
+as a static routing protocol in the framework that he proposes; right now,
+this code just writes directly into the existing Ipv4 routing API 
+
+1.  Code:
+
+- source code is in a routing module src/routing/
+- an example script is in examples/simple-static-routing.cc.  It produces the 
+same output as simple-p2p.cc
+- StaticRouteManager is added in the run-tests unit tests
+
+2.  API:
+
+The public API is very minimal.
+
+- user scripts include the following:
+#include "ns3/routing-environment.h"
+#include "ns3/static-route-manager.h"
+
+- A single default value (default false) enables static routing
+  Bind ("DoStaticRouting", "true");
+
+- The call to build the static routes themselves is a single method,
+called after the topology has been addressed:
+
+  if (RoutingEnvironment::StaticRoutingEnabled ())
+    {
+      StaticRouteManager::PopulateRoutingTables ();
+    }
+
+3.  Approach:
+
+A singleton object (StaticRouteManager) is responsible for populating
 the static routes on each node, using the public Ipv4 API of that node.
 It queries each node in the topology for a "staticRouter" interface.
 If found, it uses the API of that interface to obtain a "link state
@@ -38,13 +59,6 @@ the StaticRouteManager executes the OSPF shortest path first (SPF)
 computation on the database, and populates the routing tables on each
 node.
 
-This computation is initiated during the pre-simulation phase (after
-topology and IP addressing has been done) with the following lines of code, 
-presently:
-      Ptr<StaticRouteManager> routeManager = Create<StaticRouteManager> ();
-      routeManager->BuildStaticRoutingDatabase ();
-      routeManager->InitializeRoutes ();
-
 The quagga (http://www.quagga.net) OSPF implementation was used as the
 basis for the routing computation logic.
 One benefit of following an existing OSPF SPF implementation is that
@@ -60,34 +74,53 @@ straightforward now that the underlying OSPF SPF framework is in place.
 Presently, we can handle IPv4 point-to-point, numbered links, and we do
 not do equal-cost multipath.
 
-3.  Bootstrapping
-
-Static routing can be enabled using a DoStaticRouting flag in the
-default value system:
-  Bind ("DoStaticRouting", "true");
-This bind tells the system to use global static routing.  It results in
-a StaticRouter interface being aggregated to the internet nodes and the
-creation of a Route Manager component to oversee the route generation.
-
-If this flag is true, when an InternetNode is created, it will aggregate
-a routing interface to it.
+The support for this relies on the node object supporting a StaticRouter
+interface.  This can be manually added to each node, or alternatively,
+we have modified InternetNode::Construct() as follows:
   if (RoutingEnvironment::StaticRoutingEnabled())
     {
       Ptr<StaticRouter> staticRouter = Create<StaticRouter> (this);
       Object::AddInterface (staticRouter);
     }
-this flag is also tested before creating a StaticRouteManager object.
 
 4.  Some open issues
 
+- trying to enable this with the default value framework raised some
+questions.  Access to an underlying default variable is required
+across compilation units.  The routing environment was designed
+to put everything in one compilation unit.  Whether this is good
+practice or just overly paranoid is for further discussion.  An 
+alternative may be to define some kind of test with the same default 
+value system such as
+if (IsBound("DoStaticRouting", "true")) ...
+
+- along the same lines, Bind() is kind of an oddball in the present
+system.  We do NodeList::Begin (), Simulator::Run (), 
+CommandLine::Parse (); but simply Bind ().  This isn't very consistent.
+
+(note:  the choice of "bind()" was due to ns-2's methods of the same name)
+
+Perhaps it would be better to do something like,
+
+Configurator::Set ("DoStaticRouting", "true");
+
+if (Configurator::IsEqual ("DoStaticRouting", "true"))
+  {
+  }
+
 - how transparent vs. explicit the enabling of static routing should be
 (e.g., if we have a higher layer Inversion-of-Control framework, do these
 static routing functions exist in some kind of Init() or Presimulate() 
-method?)
+method?).  Presently, it is explicitly enabled.
+
 - whether to add some kind of flag in an InternetNode that is equivalent
 to /proc/sys/net/ipv4/ip_forward , so that every InternetNode is not
 necessarily a router.
+
 - whether to continue to write to the existing IPv4 API or load a static
-router component into the node like Gustavo's OLSR
-- whether to make a single global forwarding table instead of distributing
-it among all the routers
+router component into the node such as Gustavo's OLSR code does
+
+- what to name this.  Gustavo had suggestions to pick another name for
+the StaticRouteManager.  One possibility I would be fine with is to call 
+it GlobalRouteManager (although I would still argue it adds static routes
+into the nodes in any case).