--- a/src/dsr/doc/dsr.rst Tue Jun 05 12:12:49 2012 -0700
+++ b/src/dsr/doc/dsr.rst Tue Jun 05 16:28:00 2012 -0700
@@ -3,8 +3,8 @@
DSR Routing
-----------
-Dynamic Source Routing (DSR) protocol is a reactive routing protocol designed specifically for use in multi-hop
-wireless ad hoc networks of mobile nodes.
+Dynamic Source Routing (DSR) protocol is a reactive routing protocol designed
+specifically for use in multi-hop wireless ad hoc networks of mobile nodes.
This model was developed by
`the ResiliNets research group <http://www.ittc.ku.edu/resilinets>`_
@@ -13,83 +13,87 @@
DSR Routing Overview
********************
- This model implements the base specification of the Dynamic Source Routing (DSR)
- protocol. Implementation is based on RFC4728.
-
- Class dsr::DsrRouting implements all functionality of service packet exchange and inherits IpL4Protocol.
-
- Class dsr::DsrOptions implements functionality of packet processing and talk to DsrRouting to send/receive packets
-
- Class dsr::DsrFsHeader defines the fixed-size header and identify the up-layer protocol
-
- Class dsr::DsrOptionHeader takes care of different dsr options and process different header according to specification from rfc
+This model implements the base specification of the Dynamic Source Routing
+(DSR) protocol. Implementation is based on RFC4728.
- Class dsr::DsrSendBuffer is a buffer to save data packet as well as route error packet when there is no route to forward the packet
-
- Class dsr::DsrMaintainBuffer is a buffer to save data packet for next-hop notification when the data packet has already sent out of send buffer
-
- Class dsr::RouteCache is the essential part to save routes found for data packet, dsr responds to several routes for a single destination
+* ``Class dsr::DsrRouting`` implements all functionality of service packet exchange and inherits IpL4Protocol.
+* ``Class dsr::DsrOptions`` implements functionality of packet processing and talks to DsrRouting to send/receive packets
+* ``Class dsr::DsrFsHeader`` defines the fixed-size header and identifies the up-layer protocol
+* ``Class dsr::DsrOptionHeader`` takes care of different dsr options and processes different header according to the specification from the RFC
+* ``Class dsr::DsrSendBuffer`` is a buffer to save data packets and route error packets when there is no route to forward the packets
+* ``Class dsr::DsrMaintainBuffer`` is a buffer to save data packets for next-hop notification when the data packet has already been sent out of send buffer
+* ``Class dsr::RouteCache`` is the essential part to save routes found for data packets. DSR responds to several routes for a single destination
+* ``Class dsr::RreqTable`` implements the functions to avoid duplicate route requests and control route request rate for a single destination
+
+Protocol operation depends on many adjustable parameters. We support parameters, with their default values, from RFC and parameters that enable/disable
+protocol features or tune for specific simulation scenarios, such as the max
+size of the send buffer and its timeout value. The full parameter list is
+found in the dsr-routing.cc file.
- Class dsr::RreqTable implements the functionalities to avoid duplicate route requests and control route request rate for a single destination
-
- Protocol operation depends on the many adjustable parameters. We support parameters, with their default values, from
- RFC and parameters that enable/disable protocol features or tune for specific simulation scenarios, such as the max size
- of send buffer and its timeout value. The full parameter list is in DsrRouting.cc file.
+DSR discovers routes on-demand. Therefore, our DSR model buffers all packets,
+while a route request packet (RREQ) is disseminated. We implement a packet
+buffer in dsr-rsendbuff.cc. The packet queue implements garbage collection
+of old packets and a queue size limit. When the packet is sent out from the
+send buffer, it will be queued in maintenance buffer for next hop
+acknowledgment.
- DSR discovers routes totally on demand. Therefore, our DSR model buffers all packets, while a route request packet (RREQ)
- is disseminated. We implement a packet buffer in dsr-rsendbuff.cc. The packet queue implements garbage collection of old
- packets and a queue size limit. When the packet is sent out from the send buffer, it will be queued in maintenance buffer for
- next hop acknowledgment
+The Route Cache implementation support garbage collection of old entries
+and state machine, as defined in the standard. It implements as a STL
+map container. The key is the destination IP address.
- Route Cache implementation support garbage collection of old entries and state machine, defined in standard.
- It implements as a STL map container. The key is the destination IP address.
-
- Protocol operation strongly depends on broken link detection mechanism. We implement all the three heuristics.
- First, we use layer 2 feedback when possible. Link considered to be broken, if frame transmission results in a transmission
- failure for all retries. This mechanism meant for active links and work much more faster, than first method.
- Layer 2 feedback implementation relies on TxErrHeader trace source, currently it is supported in AdhocWifiMac only.
+Protocol operation strongly depends on broken link detection mechanism.
+We implement the three heuristics recommended.
+
+First, we use layer 2 feedback when possible. A link is considered to be
+broken if frame transmission results in a transmission failure for all
+retries. This mechanism is meant for active links and works much faster than
+in its absence. Layer 2 feedback implementation relies on TxErrHeader trace
+source, currently it is supported in AdhocWifiMac only.
- Second, passive acknowledgment should be used whenever possible. The node turns on "promiscuous" receive mode, in which it can receive
- packet not destined for itself, and when the node assures the delivery of that data packet to its destination, it cancels the passive
- acknowledgment timer.
+Second, passive acknowledgment should be used whenever possible. The node
+turns on "promiscuous" receive mode, in which it can receive packets not
+destined for itself, and when the node assures the delivery of that data
+packet to its destination, it cancels the passive acknowledgment timer.
- Last, we use network layer acknowledge scheme to notify the receipt of a packet. Route request packet will not
- be acknowledge or retransmitted.
+Last, we use a network layer acknowledge scheme to notify the receipt of
+a packet. Route request packet will not be acknowledged or retransmitted.
+
+The following optional protocol optimizations aren't implemented:
- Following optional protocol optimizations aren't implemented:
- - Flow state
- - First Hop External (F), Last Hop External (L) flags
- - Handling unknown DSR options
- - Two types of error headers:
+* Flow state
+* First Hop External (F), Last Hop External (L) flags
+* Handling unknown DSR options
+* Two types of error headers:
1. flow state not supported option
2. unsupported option (not going to happen in simulation)
- DSR operates with direct access to IP header, and operates between network and transport layer.
+DSR operates with direct access to IP header, and operates between
+network and transport layer.
+
+Implementation changes
+======================
- Implementation changes
- - The DsrFsHeader has added 3 fields: message type, source id, destination id, and these changes only for post-processing
- - message type is used to identify the data packet from control packet
- - source id is used to identify the real source of the data packet since we have to deliver the packet hop-by-hop and the ipv4header
- is not carrying the real source and destination ip address as needed
- - destination id is for same reason of above
-
- Changes:
- - Route Reply header is not word-aligned in DSR rfc, change it to word-aligned in implementation
- - DSR works as a shim header between transport and network protocol, it needs its own forwarding mechanism,
- we are changing the packet transmission to hop-by-hop delivery, so we added two fields in dsr fixed header
- to notify packet delivery
+* The DsrFsHeader has added 3 fields: message type, source id, destination id,
+and these changes only for post-processing
+** message type is used to identify the data packet from control packet
+** source id is used to identify the real source of the data packet since we have to deliver the packet hop-by-hop and the ipv4header is not carrying the real source and destination ip address as needed
+** destination id is for same reason of above
+* Route Reply header is not word-aligned in DSR rfc, change it to word-aligned in implementation
+* DSR works as a shim header between transport and network protocol, it needs its own forwarding mechanism, we are changing the packet transmission to hop-by-hop delivery, so we added two fields in dsr fixed header to notify packet delivery
1. message type to notify the type of this packet: data packet or control one
2. source id to identify the real source address of this packet
3. destination id to identify the real destination
- Current Route Cache implementation:
- - This implementation used "path cache", which is simple to implement and ensures loop-free
- - the path cache has automatic expire policy
- - the cache saves multiple route entries for a certain destination and sort the entries based on hop counts
- - the MaxEntriesEachDst can be tuned to change the maximum entries saved for a single destination
- - when adding mulitiple routes for one destination, the route is compared based on hop-count and expire time, the one with less hop count
- or relatively new route is favored
- - Future implementation may include "link cache" as another possibility
+Current Route Cache implementation
+==================================
+
+This implementation used "path cache", which is simple to implement and ensures loop-free paths:
+
+* the path cache has automatic expire policy
+* the cache saves multiple route entries for a certain destination and sort the entries based on hop counts
+* the MaxEntriesEachDst can be tuned to change the maximum entries saved for a single destination
+* when adding mulitiple routes for one destination, the route is compared based on hop-count and expire time, the one with less hop count or relatively new route is favored
+* Future implementation may include "link cache" as another possibility
DSR Instructions
****************
@@ -103,14 +107,15 @@
Helper
******
-To have a node run DSR, the easiest way would be to use the ClickInternetStackHelper
-class in your simulation script. For instance::
+To have a node run DSR, the easiest way would be to use the DsrHelper
+and DsrMainHelpers in your simulation script. For instance::
DsrHelper dsr;
DsrMainHelper dsrMain;
dsrMain.Install (dsr, adhocNodes);
-The example scripts inside ``src/dsr/examples/`` demonstrate the use of DSR based nodes
+The example scripts inside ``src/dsr/examples/`` demonstrate the use of
+DSR based nodes
in different scenarios. The helper source can be found inside ``src/dsr/helper/dsr-main-helper.{h,cc}``
and ``src/dsr/helper/dsr-helper.{h,cc}``
@@ -120,10 +125,9 @@
The example can be found in ``src/dsr/examples/``:
* dsr.cc use DSR as routing protocol within a traditional MANETs environment[3].
-
DSR is also built in the routing comparison case in ``examples/routing/``:
-* manet-routing-compare.cc is a comparison case with built in MANET routing protocols and can generate its own results.
+* ``manet-routing-compare.cc`` is a comparison case with built in MANET routing protocols and can generate its own results.
Validation
**********
@@ -133,10 +137,14 @@
* Unit tests have been written to verify the internals of DSR. This can be found in ``src/dsr/test/dsr-test-suite.cc``. These tests verify whether the methods inside DSR module which deal with packet buffer, headers work correctly.
* Simulation cases similar to [3] have been tested and have comparable results.
* manet-routing-compare.cc has been used to compare DSR with three of other routing protocols.
+
+A paper was presented on these results at the Workshop on ns-3 in 2011.
References
**********
-[1] Link for the original paper: www.monarch.cs.rice.edu/monarch-papers/dsr-chapter00.pdf
-[2] Link for RFC 4728: http://www6.ietf.org/rfc/rfc4728.txt
-[3] Link for the broch's comparison paper: http://www.monarch.cs.rice.edu/monarch-papers/mobicom98.ps
+[1] Link for the `original paper: <http://www.monarch.cs.rice.edu/monarch-papers/dsr-chapter00.pdf>`_
+
+[2] Link for `RFC 4728: <http://www6.ietf.org/rfc/rfc4728.txt>`_
+
+[3] Link for the `Broch's comparison paper: <http://www.monarch.cs.rice.edu/monarch-papers/mobicom98.ps>`_