dsr: Update documentation format

This commit is contained in:
Alberto Gallegos Ramonet
2025-04-13 20:22:11 +09:00
parent 399e31bb90
commit 8916c909dc
8 changed files with 146 additions and 195 deletions

View File

@@ -22,8 +22,9 @@ This file is a best-effort approach to solving this issue; we will do our best b
### Changes to existing API
* (core) ``Object::GetInstanceTypeId()`` can no longer be specialized by subclasses and any such subclass API should be deleted (the base class will handle it).
* (internet-apps) Added a parameter to the RADVD helper to announce a prefix without the autoconfiguration flag.
* (dsr) Reformatted documentation and added a new concept figure.
* (flow-monitor) Reformatted documentation and added a new concept figure.
* (internet-apps) Added a parameter to the RADVD helper to announce a prefix without the autoconfiguration flag.
### Changes to build system

View File

@@ -32,14 +32,15 @@ The required Doxygen version for documentation generation is now version 1.13.
### New user-visible features
- (dsr) !2403 - Reformatted documentation and added a new concept figure.
- (flow-monitor) !2387 - Reformatted documentation and added a new concept figure.
### Bugs fixed
- (bindings) #1187 - Fix library filtering to skip non-ns-3 libraries with "ns3" in their names.
- (mobility) !2397 - Fix Rectangle::GetClosestSideOrCorner. It could assign the incorrect side when the checked position was outside the rectangle.
- (wifi) #2368 - Fix various issues related to Content Channels and RU allocation. Fixes mostly covers cases where OFDMA is used with central 26 tones, where a single user is being assigned the whole PPDU bandwidth or where a RU is larger than 20 MHz.
- (zigbee) !2383 - Fix malformed RREP command with missing command options field.
- (mobility) !2397 - Fix Rectangle::GetClosestSideOrCorner. It could assign the incorrect side when the checked position was outside the rectangle.
- (bindings) #1187 - Fix library filtering to skip non-ns-3 libraries with "ns3" in their names.
## Release 3.44

View File

@@ -118,6 +118,8 @@ SOURCEFIGS = \
$(SRC)/applications/doc/http-num-of-embedded-objects.png \
$(SRC)/applications/doc/http-parsing-time.png \
$(SRC)/applications/doc/http-reading-time.png \
$(SRC)/dsr/doc/figures/dsrRreq.dia \
$(SRC)/dsr/doc/figures/dsrRrep.dia \
$(SRC)/network/doc/packet.dia \
$(SRC)/network/doc/node.dia \
$(SRC)/network/doc/buffer.dia \
@@ -478,6 +480,8 @@ IMAGES_EPS = \
$(FIGURES)/802-15-4-psr-distance.eps \
$(FIGURES)/energyFramework.eps \
$(FIGURES)/flowmonitorArq.eps \
$(FIGURES)/dsrRreq.eps \
$(FIGURES)/dsrRrep.eps \
$(FIGURES)/clear-channel.eps \
$(FIGURES)/assoc-manager.eps \
$(FIGURES)/emlsr-dl-txop.eps \

View File

@@ -1,31 +0,0 @@
/*
* Copyright (c) 2011 Yufei Cheng
*
* SPDX-License-Identifier: GPL-2.0-only
*
* Author: Yufei Cheng <yfcheng@ittc.ku.edu>
*
* James P.G. Sterbenz <jpgs@ittc.ku.edu>, director
* ResiliNets Research Group https://resilinets.org/
* Information and Telecommunication Technology Center (ITTC)
* and Department of Electrical Engineering and Computer Science
* The University of Kansas Lawrence, KS USA.
*
* Work supported in part by NSF FIND (Future Internet Design) Program
* under grant CNS-0626918 (Postmodern Internet Architecture),
* NSF grant CNS-1050226 (Multilayer Network Resilience Analysis and Experimentation on GENI),
* US Department of Defense (DoD), and ITTC at The University of Kansas.
*/
#ifndef DSR_H
#define DSR_H
/**
* @defgroup dsr DSR Routing
*
* This section documents the API of the ns-3 DSR module. For a
* generic functional description, please refer to the ns-3 model
* library document.
*/
#endif /* DSR_H */

View File

@@ -1,150 +1,103 @@
.. include:: replace.txt
Dynamic Source Routing (DSR)
============================
DSR Routing
-----------
.. include:: replace.txt
.. highlight:: cpp
.. heading hierarchy:
============= Chapter
------------- Section (#.#)
~~~~~~~~~~~~~ Subsection (#.#.#)
Dynamic Source Routing (DSR) protocol is a reactive routing protocol designed specifically
for use in multi-hop wireless ad hoc networks of mobile nodes.
for use in multi-hop wireless ad hoc networks of mobile nodes. The current model implementation is based on the RFC 4728 [2_], with some extensions
and modifications. The initial implementation was developed by `the ResiliNets research group <https://resilinets.org/>`_ at the University of Kansas with additions to the link cache mechanism done by Song Luan <lsuper@mail.ustc.edu.cn>.
This model was developed by
`the ResiliNets research group <https://resilinets.org/>`_
at the University of Kansas.
The source code for this module lives in the directory ``src/dsr``.
DSR Routing Overview
********************
.. _fig-dsrRreq:
This model implements the base specification of the Dynamic Source Routing
(DSR) protocol. Implementation is based on :rfc:`4728`, with some extensions
and modifications to the RFC specifications.
.. figure:: figures/dsrRreq.*
DSR operates on a on-demand behavior. 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 route discovery
The maintenance buffer then buffers the already sent out packets and waits
for the notification of packet delivery. Protocol operation strongly
depends on broken link detection mechanism. We implement the three heuristics
recommended based the RFC as follows:
.. _fig-dsrRrep:
First, we use link layer feedback when possible, which is also the fastest
mechanism of these three to detect link errors. 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. DSR is able to
detect the link layer transmission failure and notify that as broken.
Recalculation of routes will be triggered
when needed. If user does not want to use link layer acknowledgment,
it can be tuned by setting "LinkAcknowledgment" attribute to false in
"dsr-routing.cc".
.. figure:: figures/dsrRrep.*
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.
DSR route reply using route caching
Last, we use a network layer acknowledge scheme to notify the receipt of
a packet. Route request packet will not be acknowledged or retransmitted.
DSR creates routes towards a destination by adding the traversed route into the packet header during the discovery phase.
Different packets might have different routes even if they have the same source and the same destination.
The recorded information during the route discovery phase is used by intermediate nodes to determine whom the packet should be forward.
Hence, the term dynamic source routing.
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.
Scope and Limitations
---------------------
DSR operates with direct access to IP header, and operates between network
and transport layer. When packet is sent out from transport layer, it
passes itself to DSR and DSR header is appended.
We have two caching mechanisms: path cache and link cache. The path cache
saves the whole path in the cache. The paths are sorted based on the
hop count, and whenever one path is not able to be used, we change to the
next path. The link cache is a slightly better design in the sense that it
uses different subpaths and uses Implemented Link Cache using
Dijkstra algorithm, and this part is implemented by
Song Luan <lsuper@mail.ustc.edu.cn>.
The 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:
1. flow state not supported option
2. unsupported option (not going to happen in simulation)
DSR update in ns-3.17
=====================
We originally used "TxErrHeader" in Ptr<WifiMac> to indicate the transmission
error of a specific packet in link layer, however, it was not working
quite correctly since even when the packet was dropped, this header was
not recorded in the trace file. We used to a different path on implementing
the link layer notification mechanism. We look into the trace file by
finding packet receive event. If we find one receive event for the
data packet, we count that as the indicator for successful data delivery.
Useful parameters
=================
::
+------------------------- +------------------------------------+-------------+
| Parameter | Description | Default |
+==========================+====================================+=============+
| MaxSendBuffLen | Maximum number of packets that can | 64 |
| | be stored in send buffer | |
+------------------------- +------------------------------------+-------------+
| MaxSendBuffTime | Maximum time packets can be queued | Seconds(30) |
| | in the send buffer | |
+------------------------- +------------------------------------+-------------+
| MaxMaintLen | Maximum number of packets that can | 50 |
| | be stored in maintenance buffer | |
+------------------------- +------------------------------------+-------------+
| MaxMaintTime | Maximum time packets can be queued | Seconds(30) |
| | in maintenance buffer | |
+------------------------- +------------------------------------+-------------+
| MaxCacheLen | Maximum number of route entries | 64 |
| | that can be stored in route cache | |
+------------------------- +------------------------------------+-------------+
| RouteCacheTimeout | Maximum time the route cache can | Seconds(300)|
| | be queued in route cache | |
+------------------------- +------------------------------------+-------------+
| RreqRetries | Maximum number of retransmissions | 16 |
| | for request discovery of a route | |
+------------------------- +------------------------------------+-------------+
| CacheType | Use Link Cache or use Path Cache | "LinkCache" |
| | | |
+------------------------- +------------------------------------+-------------+
| LinkAcknowledgment | Enable Link layer acknowledgment | True |
| | mechanism | |
+------------------------- +------------------------------------+-------------+
Implementation modification
===========================
* The DsrFsHeader has added 3 fields: message type, source id, destination id, and these changes only for post-processing
1. Message type is used to identify the data packet from control packet
2. 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
3. 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
* The model is not fully compliant with RFC 4728 [2_]. As an example, DSR fixed size header has been extended and it is four octets longer then the RFC specification. As a consequence, the DSR headers can not be correctly decoded by Wireshark.
* At the moment, the model does not handle ICMP packets, and assumes that traffic is either TCP or UDP.
* No flow state available.
* No First Hop External (F), Last Hop External (L) flags.
* There are no ways of handling unknown DSR options.
* DSR option ``flow state not supported`` is not handled.
* DSR option ``unsupported option`` is not handled.
* Route Reply header is not aligned to the DSR RFC descriptions.
Current Route Cache implementation
==================================
Protocol operational details
----------------------------
This implementation used "path cache", which is simple to implement and ensures loop-free paths:
DSR operates on a on-demand behavior. Therefore, our DSR model buffers all packets while a route request packet (RREQ) is disseminated.
The packet buffer is implemented in ``dsr-rsendbuff.cc``.
* 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 multiple 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
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 Instructions
****************
The maintenance buffer then buffers the already sent out packets and waits for the notification of packet delivery.
Protocol operation strongly depends on broken link detection mechanism.
Three heuristics detection mechanisms are implementented as recommended by the RFC as follows:
1. A link layer feedback is used when possible, which is also the fastest mechanism of these three to detect link errors. 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. DSR is able to detect the link layer transmission failure and notify that as broken. Recalculation of routes will be triggered when needed. If user does not want to use link layer acknowledgment, it can be tuned by setting the ``LinkAcknowledgment`` attribute to false in ``dsr-routing.cc``.
2. 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.
3. A network layer acknowledment scheme is used to notify the receipt of a packet. Route request packet are not be acknowledged or retransmitted.
Route Cache implementation
~~~~~~~~~~~~~~~~~~~~~~~~~~
The Route Cache implementation support garbage collection of old entries and state machine, as defined in the standard.
It is implemented as a STL map container. The destination IP address is used as a key in the map.
DSR operates with direct access to IP header, and operates between network and transport layer.
When packet is sent out from transport layer, it passes itself to DSR and DSR header is appended.
Two caching mechanisms exists in the implementation: Path cache and Link cache.
- **Path Cache:** As the name implies, this cache saves the whole path and ensures loop-free paths.
The paths are sorted based on the hop count, and whenever one path becomes unusable a different path is chosen. Some of its characteristics are as follows:
* The 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 multiple 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.
- **Link Cache:** This is an improvement over the patch cache in the sense that it uses different subpaths and make use ot the Dijkstra algorithm.
Modifications
~~~~~~~~~~~~~
* The DsrFsHeader has added 3 fields: message type, source id, destination id, and these changes only for post-processing.
1. Message type is used to identify the data packet from control packet.
2. Source id is used to identify the real source of the data packet since the packet is delivered hop-by-hop and the Ipv4Header is not carrying the real source and destination ip address as needed.
3. Destination id is for same reason of above.
* 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.
Other considerations
~~~~~~~~~~~~~~~~~~~~
The following should be kept in mind when running DSR as routing protocol:
@@ -152,60 +105,73 @@ The following should be kept in mind when running DSR as routing protocol:
* PassiveAckTimeout is the time a packet in maintenance buffer wait for passive acknowledgment, normally set as two times of NodeTraversalTime
* RouteCacheTimeout should be set smaller value when the nodes' velocity become higher. The default value is 300s.
Helper
******
Usage
-----
In |ns3|, DSR is used on top of WiFi nodes. The simplest way to use it requires the use of its helper
as explained in the following subsections.
Helpers
~~~~~~~
To have a node run DSR, the easiest way would be to use the DsrHelper
and DsrMainHelpers in your simulation script. For instance:
.. sourcecode:: cpp
NodeContainer adhocNodes;
nodes.Create(5); // Add 5 nodes to the node container
DsrHelper dsr;
DsrMainHelper dsrMain;
dsrMain.Install(dsr, adhocNodes);
dsrMain.Install(dsr, adhocNodes); // Install DSR on each node
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}``
Examples
********
Attributes
~~~~~~~~~~
The complete list of available attributes with descriptions for this model can be found on `this link <https://www.nsnam.org/doxygen/de/deb/classns3_1_1dsr_1_1_dsr_routing.html#details>`_.
Traces
~~~~~~
The complete list of available trace sources with descriptions for this model can be found on `this link <https://www.nsnam.org/doxygen/de/deb/classns3_1_1dsr_1_1_dsr_routing.html#details>`_.
Examples and Tests
------------------
The example can be found in ``src/dsr/examples/``:
* dsr.cc use DSR as routing protocol within a traditional MANETs environment[3].
* ``dsr.cc``: Use DSR as routing protocol within a traditional MANETs environment.
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``: A comparison case with built in MANET routing protocols and can generate its own results.
Validation
**********
----------
This model has been tested as follows:
* 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.
Limitations
***********
The model is not fully compliant with :rfc:`4728`. As an example, Dsr fixed size header
has been extended and it is four octets longer then the RFC specification.
As a consequence, the DSR headers can not be correctly decoded by Wireshark.
The model full compliance with the RFC is planned for the future.
At the moment, the model does not handle ICMP packets, and assumes that traffic is either TCP or UDP.
* 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 [4_].
References
**********
----------
[`1 <https://web.archive.org/web/20150430233910/http://www.monarch.cs.rice.edu/monarch-papers/dsr-chapter00.pdf>`_] Johnson, David B., David A. Maltz, and Josh Broch. "DSR: The dynamic source routing protocol for multi-hop wireless ad hoc networks." Ad hoc networking 5.1 (2001): 139-172.
[`2 <https://datatracker.ietf.org/doc/html/rfc4728>`_] RFC 4728
[`3 <https://dl.acm.org/doi/10.1145/288235.288256>`_] Josh Broch, David A. Maltz, David B. Johnson, Yih-Chun Hu, and Jorjeta Jetcheva. 1998. A performance comparison of multi-hop wireless ad hoc network routing protocols. In Proceedings of the 4th annual ACM/IEEE international conference on Mobile computing and networking (MobiCom '98). Association for Computing Machinery, New York, NY, USA, 8597.
[`4 <https://dl.acm.org/doi/10.5555/2263019.2263077>`_] Yufei Cheng, Egemen K. Çetinkaya, and James P. G. Sterbenz. 2012. Dynamic source routing (DSR) protocol implementation in ns-3. In Proceedings of the 5th International ICST Conference on Simulation Tools and Techniques (SIMUTOOLS '12). ICST (Institute for Computer Sciences, Social-Informatics and Telecommunications Engineering), Brussels, BEL, 367374.
[1] Original paper: https://web.archive.org/web/20150430233910/http://www.monarch.cs.rice.edu/monarch-papers/dsr-chapter00.pdf
[2] RFC 4728 https://datatracker.ietf.org/doc/html/rfc4728
[3] Broch's comparison paper: https://web.archive.org/web/20150725135435/http://www.monarch.cs.rice.edu/monarch-papers/mobicom98.ps

Binary file not shown.

Binary file not shown.

View File

@@ -80,6 +80,16 @@ namespace dsr
class DsrOptions;
/**
* @defgroup dsr Dynamic Source Routing (DSR)
*
* This section documents the API of the Dynamic Source Routing Protocol based on RFC 4728
* with some modifications. For a generic functional description, please refer to the ns-3
* model library document.
*/
/**
* @ingroup dsr
*
* @class DsrRouting
* @brief Dsr Routing base
*/