From d999b6f2552cd0d10ed3f1bde80f7785df63ff34 Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Mon, 18 Mar 2013 22:29:43 -0700 Subject: [PATCH] add documentation for error models --- doc/models/Makefile | 1 + doc/models/source/network.rst | 1 + src/network/doc/error-model.rst | 136 ++++++++++++++++++++++++++++++++ 3 files changed, 138 insertions(+) create mode 100644 src/network/doc/error-model.rst diff --git a/doc/models/Makefile b/doc/models/Makefile index 8f6c74d7e..e9de331c6 100644 --- a/doc/models/Makefile +++ b/doc/models/Makefile @@ -48,6 +48,7 @@ SOURCES = \ $(SRC)/propagation/doc/propagation.rst \ $(SRC)/network/doc/network-overview.rst \ $(SRC)/network/doc/packets.rst \ + $(SRC)/network/doc/error-model.rst \ $(SRC)/network/doc/sockets-api.rst \ $(SRC)/network/doc/simple.rst \ $(SRC)/network/doc/queue.rst \ diff --git a/doc/models/source/network.rst b/doc/models/source/network.rst index 53729620b..bb67a7c36 100644 --- a/doc/models/source/network.rst +++ b/doc/models/source/network.rst @@ -4,6 +4,7 @@ Network Module .. toctree:: packets + error-model network-overview sockets-api simple diff --git a/src/network/doc/error-model.rst b/src/network/doc/error-model.rst new file mode 100644 index 000000000..b2d3e1d61 --- /dev/null +++ b/src/network/doc/error-model.rst @@ -0,0 +1,136 @@ +Error Model +----------- +.. include:: replace.txt + +.. heading hierarchy: + ------------- Chapter + ************* Section (#.#) + ============= Subsection (#.#.#) + ############# Paragraph (no number) + +This section documents a few error model objects, typically associated with +NetDevice models, that are maintained as part of the ``network`` module: + +* RateErrorModel +* ListErrorModel +* ReceiveListErrorModel +* BurstErrorModel + +Error models are used to indicate that a packet should be considered to +be errored, according to the underlying (possibly stochastic or +empirical) error model. + +Model Description +***************** + +The source code for error models live in the directory ``src/packet/utils``. + +Two types of error models are generally provided. The first are stochastic +models. In this case, packets are errored according to underlying +random variable distributions. An example of this is the ``RateErrorModel``. +The other type of model is a deterministic or empirical model, in which +packets are errored according to a particular prescribed pattern. +An example is the ``ListErrorModel`` that allows users to specify +the list of packets to be errored, by listing the specific packet UIDs. + +The ``ns3::RateErrorModel`` errors packets according to an underlying +random variable distribution, which is by default a UniformRandomVariable +distributed between 0.0 and 1.0. The error rate and error units (bit, +byte, or packet) are set by the user. For instance, by setting ErrorRate +to 0.1 and ErrorUnit to "Packet", in the long run, around 10% of the +packets will be lost. + + +Design +====== + +Error models are |ns3| objects and can be created using the typical +pattern of ``CreateObject<>()``. They have configuration attributes. + +An ErrorModel can be applied anywhere, but are commonly deployed on +NetDevice models so that artificial losses (mimicing channel losses) +can be induced. + +Scope and Limitations +===================== + +No known limitations. There are no existing models that try to modify +the packet contents (e.g. apply bit or byte errors to the byte buffers). +This type of operation will likely be performance-expensive, and existing +Packet APIs may not easily support it. + +The |ns3| spectrum model and devices that derive from it (e.g. LTE) have +their own error model base class, found in + +References +========== + +The initial |ns3| error models were ported from ns-2 (queue/errmodel.{cc,h}) + +Usage +***** + +The base class API is as follows: + +* ``bool ErrorModel::IsCorrupt (Ptr pkt)``: Evaluate the packet and + return true or false whether the packet should be considered errored or not. + Some models could potentially alter the contents of the packet bit buffer. +* ``void ErrorModel::Reset (void)``: Reset any state. +* ``void ErrorModel::Enable (void)``: Enable the model +* ``void ErrorModel::Disble (void)``: Disable the model; IsCorrupt() will + always return false. +* ``bool ErrorModel::IsEnabled (void) const``: Return the enabled state + + +Many |ns3| NetDevices contain attributes holding pointers to error +models. The error model is applied in the notional physical layer +processing chain of the device, and drops should show up on the ``PhyRxDrop`` +trace source of the device. The following are known to include an attribute +with a pointer available to hold this type of error model: + +* ``SimpleNetDevice`` +* ``PointToPointNetDevice`` +* ``CsmaNetDevice`` +* ``VirtualNetDevice`` + +However, the ErrorModel could be used anywhere where packets are used + +Helpers +======= + +This model is typically not used with helpers. + +Attributes +========== + +The ``RateErrorModel`` contains the following attributes: + + +Output +====== + +What kind of data does the model generate? What are the key trace +sources? What kind of logging output can be enabled? + +Examples +======== + +Error models are used in the tutorial ``fifth`` and ``sixth`` programs. + +The directory ``examples/error-model/`` contains an example +``simple-error-model.cc`` that exercises the Rate and List error models. + +The TCP example ``examples/tcp/tcp-nsc-lfn.cc`` uses the Rate error model. + +Troubleshooting +=============== + +No known issues. + +Validation +********** + +The ``error-model`` unit test suite provides a single test case of +of a particular combination of ErrorRate and ErrorUnit for the +``RateErrorModel`` applied to a ``SimpleNetDevice``. +