diff --git a/doc/src/developers-guide/ch-authors-guide.rst b/doc/src/developers-guide/ch-authors-guide.rst index 0e8d86a6f36..82dca1d5550 100644 --- a/doc/src/developers-guide/ch-authors-guide.rst +++ b/doc/src/developers-guide/ch-authors-guide.rst @@ -29,12 +29,12 @@ information with other pieces of documentation, namely: Why is duplication to be avoided? Multiple reasons: -- It is a waste of our reader’s time they have to skip information they - have already seen elsewhere +- It is a waste of our reader’s time if they have to skip information they + have already seen elsewhere. -- The text can easily get out of date as the INET Framework evolves +- The text can easily get out of date as the INET Framework evolves. -- It is extra effort for maintainers to keep all copies up to date +- It is extra effort for maintainers to keep all copies up to date. .. _dg:sec:authorsguide:guidelines: @@ -50,23 +50,23 @@ When describing a module that implements protocol X, do not go into lengths explaining what protocol X does and how it works, because that is appropriately (and usually, much better) explained in the specification or books on protocol X. It is OK to summarize the -protocol’s goal and principles in a short paragraph though. +protocol’s goal and principles in a short paragraph, though. In particular, do not describe the *format of the protocol messages*. It surely looks nice and takes up a lot of space, but the same information -can probably be found in a myriad places all over the internet. +can probably be found in myriad places all over the internet. .. _dg:sec:authorsguide:do-not-repeat-neddoc: Do Not Repeat NED Documentation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Things like module parameters, gate names, emitted signals and collected +Things like module parameters, gate names, emitted signals, and collected statistics are appropriately and formally part of the NED definitions, and there is no need to duplicate that information in this *Guide*. Detailed information on the module, such as *usage details* and the list -of *implemented standards* should be covered in the module’s NED +of *implemented standards*, should be covered in the module’s NED documentation, not in this *Guide*. .. _dg:sec:authorsguide:do-not-repeat-cpp: @@ -87,5 +87,5 @@ generally capable of, how the parts fit together, how to use the provided APIs, what were the main design decisions, etc. Give simple yet meaningful examples and just enough information about the API that after a quick read, users can “bootstrap” into implementing their own -protocols and applications. If they have questions afterwards, they -will/should refer to the C++ documentation. +protocols and applications. If they have questions afterward, they +will/should refer to the C++ documentation. \ No newline at end of file diff --git a/doc/src/developers-guide/ch-developing-models.rst b/doc/src/developers-guide/ch-developing-models.rst index cfbea4d55ab..61decefe07d 100644 --- a/doc/src/developers-guide/ch-developing-models.rst +++ b/doc/src/developers-guide/ch-developing-models.rst @@ -11,17 +11,17 @@ Overview This section introduces the most important modeling support features of INET. These features facilitate the implementation of applications and communication protocols by providing various commonly used -functionality. Thus modeling support allows rapid implementation of new +functionalities. Thus, modeling support allows for the rapid implementation of new models by building on already existing APIs while the implementor can focus on the research topics. These features differ from the reusable -NED modules introduced earlier, because they are available in the form +NED modules introduced earlier because they are available in the form of C++ APIs. The easy usage of protocol services is another essential modeling support. Applications often need to use several different protocol -services simultaneously. In order to spare the applications from using +services simultaneously. To spare the applications from using the default OMNeT++ message passing style between modules, INET provides -an easy to use C++ socket API. +an easy-to-use C++ socket API. TODO @@ -42,13 +42,13 @@ The @labels Module Property ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``@labels`` property can be added to modules and gates, and it -allows the OMNeT++ graphical editor to provide better editing -experience. First we look at ``@labels`` as a module property. +allows the OMNeT++ graphical editor to provide a better editing +experience. First, we look at ``@labels`` as a module property. ``@labels(node)`` has been added to all NED module types that may -occur on network level. When editing a network, the graphical editor -will NED types with ``@labels(node)`` to the top of the component -palette, allowing the user to find them easier. +occur on the network level. When editing a network, the graphical editor +will show NED types with ``@labels(node)`` at the top of the component +palette, allowing the user to find them more easily. Other labels can also be specified in the ``@labels(...)`` property. This has the effect that if one module with a particular label has @@ -74,9 +74,9 @@ making it easier to find. } Module types that are already present in the compound module also appear -in the top part of the palette. The reason is that if you already added +in the top part of the palette. The reason is that if you have already added a :ned:`StandardHost`, for example, then you are likely to add more of -the same kind. Gate labels (see next section) also affect palette order: +the same kind. Gate labels (see the next section) also affect the palette order: modules which can be connected to modules already added to the compound module will also be listed at the top of the palette. The final ordering is the result of a scoring algorithm. @@ -84,7 +84,7 @@ is the result of a scoring algorithm. The @labels Gate Property ~~~~~~~~~~~~~~~~~~~~~~~~~ -Gates can also be labelled with ``@labels()``; the purpose is to make +Gates can also be labeled with ``@labels()``. The purpose is to make it easier to connect modules in the editor. If you connect two modules in the editor, the gate selection menu will list gate pairs that have a label in common. @@ -93,7 +93,7 @@ TODO screenshot For example, when connecting hosts and routers, the editor will offer connecting Ethernet gates with Ethernet gates, and PPP gates with PPP -gates. This is the result of gate labelling like this: +gates. This is the result of gate labeling like this: @@ -109,12 +109,12 @@ gates. This is the result of gate labelling like this: } Guidelines for choosing gate label names: For gates of modules that -implement protocols, use the C++ class name of the packet or acompanying +implement protocols, use the C++ class name of the packet or accompanying control info (see later) associated with the gate, whichever applies; append ``/up`` or ``/down`` to the name of the control info class. For gates of network nodes, use the class names of packets (frames) that travel on the corresponding link, with the ``-conn`` suffix. The -suffix prevents protocol-level modules to be promoted in the graphical +suffix prevents protocol-level modules from being promoted in the graphical editor palette when a network is edited. Examples: @@ -165,14 +165,14 @@ Address Types The INET Framework uses a number of C++ classes to represent various addresses in the network. These classes support initialization and -assignment from binary and string representation of the address, and +assignment from binary and string representations of the address, and accessing the address in both forms. Storage is in binary form, and they also support the "unspecified" special value (and the :fun:`isUnspecified()` method) that usually corresponds to the all-zeros address. - :cpp:`MacAddress` represents a 48-bit IEEE 802 MAC address. The - textual notation it understands and produces is hex string. + textual notation it understands and produces is a hex string. - :cpp:`Ipv4Address` represents a 32-bit IPv4 address. It can parse and produce textual representations in the "dotted decimal" syntax. @@ -180,13 +180,13 @@ all-zeros address. - :cpp:`Ipv6Address` represents a 128-bit IPv6 address. It can parse and produce address strings in the canonical (RFC 3513) syntax. -- :cpp:`L3Address` is conceptually a union of a :cpp:`Ipv4Address` and +- :cpp:`L3Address` is conceptually a union of an :cpp:`Ipv4Address` and :cpp:`Ipv6Address`: an instance stores either an IPv4 address or an IPv6 address. :cpp:`L3Address` is mainly used in the transport layer and above to abstract away network addresses. It can be assigned from both :cpp:`Ipv4Address` and :cpp:`Ipv6Address`, and can also parse string representations of both. The :fun:`getType()`, - :fun:`toIpv4()` and :fun:`toIpv6()` methods can be used to access + :fun:`toIpv4()`, and :fun:`toIpv6()` methods can be used to access the value. TODO diff --git a/doc/src/developers-guide/ch-ethernet.rst b/doc/src/developers-guide/ch-ethernet.rst index 044c82d648f..dc2e645417c 100644 --- a/doc/src/developers-guide/ch-ethernet.rst +++ b/doc/src/developers-guide/ch-ethernet.rst @@ -19,10 +19,10 @@ ------ The INET defines these frames in the :file:`EtherFrame.msg` file. - The models supports Ethernet II, 803.2 with LLC header, and 803.3 with + The models support Ethernet II, 803.2 with LLC header, and 803.3 with LLC and SNAP headers. The corresponding classes are: :msg:`EthernetIIFrame`, :msg:`EtherFrameWithLlc` and - :msg:`EtherFrameWithSNAP`. They all class from :msg:`EtherFrame` which + :msg:`EtherFrameWithSNAP`. They all derive from :msg:`EtherFrame` which only represents the basic MAC frame with source and destination addresses. :ned:`EthernetCsmaMac` only deals with :msg:`EtherFrame`’s, and does not care about the specific subclass. @@ -71,7 +71,7 @@ In general, if :ned:`Ieee8022Llc` receives a packet from the higher layers, it interprets the message kind as a command. The commands include IEEE802CTRL_DATA (send a frame), IEEE802CTRL_REGISTER_DSAP (register - highher layer) IEEE802CTRL_DEREGISTER_DSAP (deregister higher layer) and + higher layer) IEEE802CTRL_DEREGISTER_DSAP (deregister higher layer) and IEEE802CTRL_SENDPAUSE (send PAUSE frame) – see EtherLLC for a more complete list. @@ -105,11 +105,11 @@ the interface packets. Using a control structure is more efficient than the interface packet - approach, because the control structure can be created once inside the + approach because the control structure can be created once inside the higher layer and be reused for every packet. It may also appear to be more intuitive in Tkenv because one can observe - data packets travelling between the higher layer and Ethernet modules – + data packets traveling between the higher layer and Ethernet modules – as opposed to "interface" packets. EtherLLC: SAP Registration @@ -144,10 +144,10 @@ When frames collide the transmission is aborted – in this case the transmitting station transmits a jam signal. Jam signals are represented - by a :msg:`EthernetJamSignal` message. The jam message contains the tree + by an :msg:`EthernetJamSignal` message. The jam message contains the tree identifier of the frame whose transmission is aborted. When the :ned:`EthernetCsmaMac` receives a jam signal, it knows that the corresponding - transmission ended in jamming and have been aborted. Thus when it + transmission ended in jamming and has been aborted. Thus when it receives as many jams as collided frames, it can be sure that the channel is free again. (Receiving a jam message marks the beginning of the jam signal, so actually has to wait for the duration of the @@ -169,7 +169,7 @@ ~~~~~~~~ When the transmission line is busy, messages received from the upper - layer needs to be queued. + layer need to be queued. In routers, MAC relies on an external queue module (see :ned:`PacketQueue`), and requests packets from this external queue @@ -197,7 +197,7 @@ resume immediately. :ned:`EthernetCsmaMac` will properly respond to PAUSE frames it receives - (:msg:`EtherPauseFrame` class), however it will never send a PAUSE frame + (:msg:`EtherPauseFrame` class), however, it will never send a PAUSE frame by itself. (For one thing, it doesn’t have an input buffer that can overflow.) diff --git a/doc/src/developers-guide/ch-introduction.rst b/doc/src/developers-guide/ch-introduction.rst index dde8f2f450b..a214b0b06ec 100644 --- a/doc/src/developers-guide/ch-introduction.rst +++ b/doc/src/developers-guide/ch-introduction.rst @@ -8,23 +8,23 @@ Introduction What is INET Framework ---------------------- -INET Framework is an open-source model library for the OMNeT++ -simulation environment. It provides protocols, agents and other models +The INET Framework is an open-source model library for the OMNeT++ +simulation environment. It provides protocols, agents, and other models for researchers and students working with communication networks. INET -is especially useful when designing and validating new protocols, or +is especially useful when designing and validating new protocols or exploring new or exotic scenarios. INET supports a wide class of communication networks, including wired, -wireless, mobile, ad hoc and sensor networks. It contains models for the -Internet stack (TCP, UDP, IPv4, IPv6, OSPF, BGP, etc.), link layer +wireless, mobile, ad hoc, and sensor networks. It contains models for the +Internet stack (TCP, UDP, IPv4, IPv6, OSPF, BGP, etc.), link-layer protocols (Ethernet, PPP, IEEE 802.11, various sensor MAC protocols, etc), refined support for the wireless physical layer, MANET routing protocols, DiffServ, MPLS with LDP and RSVP-TE signalling, several application models, and many other protocols and components. It also provides support for node mobility, advanced visualization, network -emulation and more. +emulation, and more. -Several other simulation frameworks take INET as a base, and extend it +Several other simulation frameworks take INET as a base and extend it into specific directions, such as vehicular networks, overlay/peer-to-peer networks, or LTE. @@ -34,7 +34,7 @@ Scope of this Manual -------------------- This manual is written for developers who intend to extend INET with new -components, written in C++. This manual is accompanied by the INET +components written in C++. This manual is accompanied by the INET Reference, which is generated from NED and MSG files using OMNeT++’s documentation generator, and the documentation of the underlying C++ classes, generated from the source files using Doxygen. A working diff --git a/doc/src/developers-guide/ch-ipv4.rst b/doc/src/developers-guide/ch-ipv4.rst index 3a3dbf56432..5bda5fc8d7e 100644 --- a/doc/src/developers-guide/ch-ipv4.rst +++ b/doc/src/developers-guide/ch-ipv4.rst @@ -14,8 +14,8 @@ Processing time The C++ class of the :ned:`Ipv4` module is derived from :cpp:`QueueBase`. There is a processing time associated with each incoming packet. This processing time is specified by the -:par:`procDelay` module parameter. If a packet arrives, when the -processing of a previous has not been finished, it is placed in a FIFO +:par:`procDelay` module parameter. If a packet arrives when the +processing of a previous packet has not been finished, it is placed in a FIFO queue. The current performance model assumes that each datagram is processed @@ -24,7 +24,7 @@ you need a more sophisticated performance model, you may change the module implementation (the IP class), and: #. override the :fun:`startService()` method which determines - processing time for a packet, or + the processing time for a packet, or #. use a different base class. @@ -37,7 +37,7 @@ Higher layer protocols should be connected to the Sending packets ^^^^^^^^^^^^^^^ -Higher layer protocols can send a packet by attaching a +Higher layer protocols can send a packet by attaching an :cpp:`Ipv4ControlInfo` object to their packet and sending it to the :ned:`Ipv4` module. @@ -48,7 +48,7 @@ The following fields must be set in the control info: - :var:`destAddr`: the ``Destination Address`` of the IP datagram. -Optionally the following fields can be set too: +Optionally, the following fields can be set too: - :var:`scrAddr`: ``Source Address`` of the IP datagram. If given it must match with the address of one of the interfaces of the node, but @@ -59,10 +59,10 @@ Optionally the following fields can be set too: - :var:`timeToLive`: TTL of the IP datagram or -1 (unspecified). If unspecified then the TTL of the datagram will be 1 for destination addresses in the 224.0.0.0 – 224.0.0.255 range. (Datagrams with these - special multicast addresses do not need to go further that one hop, - routers does not forward these datagrams.) Otherwise the TTL field is + special multicast addresses do not need to go further than one hop, + routers do not forward these datagrams.) Otherwise, the TTL field is determined by the :par:`defaultTimeToLive` or - :par:`defaultMCTimeToLive` module parameters depending whether the + :par:`defaultMCTimeToLive` module parameters depending on whether the destination address is a multicast address or not. - :var:`dontFragment`: the ``Don’t Fragment`` flag of the outgoing @@ -73,15 +73,15 @@ Optionally the following fields can be set too: :msg:`Ipv4Header` too.) - :var:`multicastLoop`: if ``true``, then a copy of the multicast - datagrams are sent to the loopback interface, so applications on the + datagrams is sent to the loopback interface, so applications on the same host can receive it. -- :var:`interfaceId`: id of outgoing interface (can be used to limit +- :var:`interfaceId`: id of the outgoing interface (can be used to limit broadcast or restrict routing). - :var:`nextHopAddr`: explicit routing info, used by Manet DSR routing. If specified, then ``interfaceId`` must also be specified. Ignored - in Manet routing is disabled. + if Manet routing is disabled. The IP module encapsulates the transport layer datagram into an :msg:`Ipv4Header` and fills in the header fields according to the @@ -89,16 +89,16 @@ control info. The ``Identification`` field is generated by incrementing a counter. The generated IP datagram is passed to the routing algorithm. The -routing decides if the datagram should be delivered locally, or passed -to one of the network interfaces with a specified next hop address, or +routing decides if the datagram should be delivered locally or passed +to one of the network interfaces with a specified next hop address or broadcasted on one or all of the network interfaces. The details of the -routing is described in the next subsection +routing are described in the next subsection (`1.1.3 <#subsec:ip_routing>`__) in detail. Before sending the datagram on a specific interface, the :ned:`Ipv4` module checks if the packet length is smaller than the ``MTU`` of the interface. If not, then the datagram is fragmented. When the ``Don’t -Fragment`` flag forbids fragmentation, an ``Destination Unreachable`` +Fragment`` flag forbids fragmentation, a ``Destination Unreachable`` ICMP error is generated with the ``Fragmentation Error (5)`` error code. @@ -110,7 +110,7 @@ code. The fragments are sent to the :ned:`Arp` module through the ``queueOut`` gate. The :ned:`Arp` module forwards the datagram immediately to point-to-point interface cards. If the outgoing interface -is a 802.x card, then before forwarding the datagram it performs address +is a 802.x card, then before forwarding the datagram, it performs address resolution to obtain the MAC address of the destination. Receiving packets @@ -125,41 +125,41 @@ the network in three steps: #. Dispatch the datagram to the appropriate transport protocol -When a fragment received, it is added to the fragment buffer of the IP. +When a fragment is received, it is added to the fragment buffer of the IP. If the fragment was the last fragment of a datagram, the processing of the datagram continues with step 2. The fragment buffer stores the reception time of each fragment. Fragments older than :par:`fragmentTimeout` are purged from the buffer. The default value of the timeout is 60s. The timeout is only checked when a fragment is -received, and at least 10s elapsed since the last check. +received, and at least 10s has elapsed since the last check. -An :msg:`Ipv4ControlInfo` attached to the decapsulated transport layer +An :msg:`Ipv4ControlInfo` is attached to the decapsulated transport layer packet. The control info contains fields copied from the IP header (source and destination address, protocol, TTL, ToS) as well as the -interface id through it was received. The control info also stores the -original IP datagram, because the transport layer might signal an ICMP -error, and the ICMP packet must encapsulate the erronous IP datagram. +interface id through which it was received. The control info also stores +the original IP datagram because the transport layer might signal an ICMP +error, and the ICMP packet must encapsulate the erroneous IP datagram. .. note:: - IP datagrams containing a DSR packet are not decapsulated, the unchanged IP + IP datagrams containing a DSR packet are not decapsulated; the unchanged IP datagram is passed to the DSR module instead. After decapsulation, the transport layer packet will be passed to the appropriate transport protocol. It must be connected to one of the -``transportOut[]`` gate. The :ned:`Ipv4` module finds the gate using -the ``protocol id``\ :math:`\rightarrow` ``gate index`` mapping +``transportOut[]`` gates. The :ned:`Ipv4` module finds the gate using +the ``protocol id`` :math:`\rightarrow` ``gate index`` mapping given in the :par:`protocolMapping` string parameter. The value must be -a comma separated list of ”:” items. For -example the following line in the ini file maps TCP (6) to gate 0, UDP -(17) to gate 1, ICMP (1) to gate 2, IGMP (2) to gate 3, and RVSP (46) to +a comma-separated list of ”:” items. For +example, the following line in the ini file maps TCP (6) to gate 0, UDP +(17) to gate 1, ICMP (1) to gate 2, IGMP (2) to gate 3, and RSVP (46) to gate 4. .. code-block:: ini **.ip.protocolMapping="6:0,17:1,1:2,2:3,46:4" -If the protocol of the received IP datagram is not mapped, or the gate +If the protocol of the received IP datagram is not mapped or the gate is not connected, the datagram will be silently dropped. Some protocols are handled differently: @@ -168,7 +168,7 @@ Some protocols are handled differently: triggered the error. Only ICMP query requests and responses are sent to the :ned:`Icmp` module. -- ``IP``: sent through ``preRoutingOut`` gate. (bug!) +- ``IP``: sent through the ``preRoutingOut`` gate. (bug!) - ``DSR``: ??? (subsection about Manet routing?) @@ -177,64 +177,64 @@ Some protocols are handled differently: Routing, and interfacing with lower layers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The output of the network interfaces are connected to the ``queueIn`` +The output of the network interfaces is connected to the ``queueIn`` gates of the :ned:`Ipv4` module. The incoming packets are either IP datagrams or ARP responses. The IP datagrams are processed by the -:ned:`Ipv4` module, the ARP responses are forwarded to the :ned:`Arp`. +:ned:`Ipv4` module; the ARP responses are forwarded to the :ned:`Arp`. The :ned:`Ipv4` module first checks the error bit of the incoming IP datagrams. There is a :math:`header length/packet length` probability that the IP header contains the error (assuming 1 bit error). With this -probability an ICMP ``Parameter Problem`` generated, and the datagram +probability, an ICMP ``Parameter Problem`` is generated, and the datagram is dropped. -When the datagram does not contain error in the IP header, a routing -decision is made. As a result of the routing the datagram is either -delivered locally, or sent out one or more output interface. When it is +When the datagram does not contain an error in the IP header, a routing +decision is made. As a result of the routing, the datagram is either +delivered locally or sent out through one or more output interfaces. When it is sent out, the routing algorithm must compute the next hop of its route. -The details are differ, depending on that the destination address is -multicast address or not. +The details differ depending on whether the destination address is +a multicast address or not. When the datagram is decided to be sent up, it is processed as described in the previous subsection (Receiving packets). If it is decided to be sent out through some interface, it is actually sent to the :ned:`Arp` module through the ``queueOut`` gate. An :msg:`IPv4RoutingDecision` control info is attached to the outgoing packet, containing the outgoing -interface id, and the IP address of the next hop. The :ned:`Arp` module -resolve the IP address to a hardware address if needed, and forwards the -datagram to next hop. +interface id and the IP address of the next hop. The :ned:`Arp` module +resolves the IP address to a hardware address if needed and forwards the +datagram to the next hop. Unicast/broadcast routing ^^^^^^^^^^^^^^^^^^^^^^^^^ -When the higher layer generated the datagram, it will be processed in +When the higher layer generates the datagram, it will be processed in these steps: #. If the destination is the address of a local interface, then the datagram is locally delivered. -#. If the destination is the limited broadcast address, or a local +#. If the destination is the limited broadcast address or a local broadcast address, then it will be broadcasted on one or more - interface. If the higher layer specified am outgoing interface + interfaces. If the higher layer specifies an outgoing interface (:var:`interfaceId` in the control info), then it will be broadcasted - on that interface only. Otherwise if the :par:`forceBroadcast` module - parameter is ``true``, then it will broadcasted on all interfaces - including the loopback interface. The default value of the + on that interface only. Otherwise, if the :par:`forceBroadcast` module + parameter is ``true``, then it will be broadcasted on all interfaces + including the loopback interface. The default value of :par:`forceBroadcast` is ``false``. -#. If the higher layer provided the routing decision (Manet routing), +#. If the higher layer provides the routing decision (Manet routing), then the datagram will be sent through the specified interface to the specified next hop. -#. Otherwise IP finds the outgoing interface and the address of the next - hop by consulting the routing table, and sends the datagram to the - next hop. If no route found, then a ``Destination Unreachable`` +#. Otherwise, IP finds the outgoing interface and the address of the next + hop by consulting the routing table and sends the datagram to the + next hop. If no route is found, then a ``Destination Unreachable`` ICMP error is generated. Incoming datagrams having unicast or broadcast destination addresses are routed in the following steps: -#. Deliver datagram locally. If the destination address is a local +#. Deliver the datagram locally. If the destination address is a local address, the limited broadcast address (255.255.255.255), or a local broadcast address, then it will be sent to the transport layer. @@ -244,7 +244,7 @@ routed in the following steps: #. Forward the datagram to the next hop. The next hop is determined by looking up the best route to the destination from the routing table. If the gateway is set in the route, then the datagram will be - forwarded to the gateway, otherwise it is sent directly to the + forwarded to the gateway; otherwise, it is sent directly to the destination. If no route is found, then a ``Destination Unreachable`` ICMP error is sent to the source of the datagram. @@ -253,31 +253,31 @@ Multicast routing Outgoing multicast datagrams are handled as follows: -If the higher layer set the :var:`multicastLoop` variable to -``true``, the IP will send up a copy of the datagram through the +If the higher layer sets the :var:`multicastLoop` variable to +``true``, IP will send a copy of the datagram through the loopback interface. -Determine the outgoing interface for the multicast datagram, and send +Determine the outgoing interface for the multicast datagram and send out the datagram through that interface. The outgoing interface is determined by the following rules: -if the HL specified the outgoing interface in the control info, the it +if the HL specifies the outgoing interface in the control info, then it will be used otherwise use the interface of the route configured in the routing table for the destination address -if no route found, then use the interface whose address matches the +if no route is found, then use the interface whose address matches the source address of the datagram if the HL did not specify the source address, then use the first -multicast capable interface +multicast-capable interface -if no such interface found, then the datagram is unroutable and droppped +if no such interface is found, then the datagram is unroutable and dropped Incoming multicast datagrams are forwarded according to their source -address (Reverse Path Forwarding), i.e. datagrams are sent away from -their sources instead towards their destinations. The multicast routing +address (Reverse Path Forwarding), i.e., datagrams are sent away from +their sources instead of towards their destinations. The multicast routing table maintains a spanning tree for each source network and multicast group. The source network is the root of the tree, and there is a path to each LAN that has members of the multicast group. Each node expects @@ -292,12 +292,12 @@ these steps: datagram arrived belongs to the multicast group specified by the destination address, it is sent up to the transport layer. -#. Discard incoming packets that can not be delivered locally and can - not be forwarded. A non-local packet can not be forwarded if - multicast forwarding is disabled, the destination is a link local +#. Discard incoming packets that cannot be delivered locally and cannot + be forwarded. A non-local packet cannot be forwarded if + multicast forwarding is disabled, the destination is a link-local multicast address (224.0.0.x), or the TTL field reached 0. -#. Discard the packet if no multicast route found, or if it did not +#. Discard the packet if no multicast route is found or if it did not arrive on the parent interface of the route (to avoid multicast loops). If the parent is not set in the route, then the shortest path interface to the source is assumed. @@ -305,8 +305,8 @@ these steps: #. Forward the multicast datagram. A copy of the datagram is sent on each child interface described by multicast routes (except the incoming interface). Interfaces may have a :var:`ttlThreshold` - parameter, that limits the scope of the multicast: only datagrams - with higher TTL are forwarded. + parameter that limits the scope of the multicast: only datagrams + with a higher TTL are forwarded. The IPv4RoutingTable Module --------------------------- @@ -317,97 +317,98 @@ every L2 module adds its own interface entry to the table. The route table is read from a file; the file can also fill in or overwrite interface settings. The route table can also be read and modified during simulation, typically by routing protocol -implementations (e.g. OSPF). +implementations (e.g., OSPF). Entries in the route table are represented by :cpp:`Ipv4Route` objects. :cpp:`Ipv4Route` objects can be polymorphic: if a routing protocol needs -to store additional data, it can simply subclass from :cpp:`Ipv4Route`, +to store additional data, it can simply subclass from :cpp:`Ipv4Route` and add the derived object to the table. The :cpp:`Ipv4Route` object has the following fields: - ``host`` is the IP address of the target of the route (can be a - host or network). When an entry searched for a given destination + host or network). When an entry is searched for a given destination address, the destination address is compared with this ``host`` address using the ``netmask`` below, and the longest match wins. -- ``netmask`` used when comparing ``host`` with the detination +- ``netmask`` is used when comparing ``host`` with the destination address. It is 0.0.0.0 for the default route, 255.255.255.255 for host routes (exact match), or the network or subnet mask for network routes. - ``gateway`` is the IP address of the gateway for indirect routes, or 0.0.0.0 for direct routes. Note that 0.0.0.0 can be used even if - the destination is not directly connected to this node, but can be + the destination is not directly connected to this node but can be found using proxy ARP. -- ``interface`` the outgoing interface to be used with this route. +- ``interface`` is the outgoing interface to be used with this route. -- ``type`` ``DIRECT`` or ``REMOTE``. For direct routes, the - next hop address is the destination address, for remote routes it is +- ``type`` can be ``DIRECT`` or ``REMOTE``. For direct routes, the + next hop address is the destination address; for remote routes, it is the gateway address. -- ``source`` ``MANUAL``, ``IFACENETMASK``, ``RIP``, +- ``source`` can be ``MANUAL``, ``IFACENETMASK``, ``RIP``, ``OSPF``, ``BGP``, ``ZEBRA``, ``MANET``, or ``MANET2``. ``MANUAL`` means that the route was added by a - routing file, or a network configurator. ``IFACENETMASK`` routes - are added for each interface of the node. Other values means that the + routing file or a network configurator. ``IFACENETMASK`` routes + are added for each interface of the node. Other values mean that the route is managed by the specific routing daemon. -- ``metric`` the “cost” of the route. Currently not used when +- ``metric`` is the “cost” of the route. Currently not used when choosing the best route. -In multicast routers the routing table contains multicast routes too. A +In multicast routers, the routing table contains multicast routes too. A multicast route is represented by an instance of the :cpp:`Ipv4MulticastRoute` class. The :cpp:`Ipv4MulticastRoute` instance stores the following fields: -- :var:`origin` IP address of the network of the source of the datagram +- :var:`origin` is the IP address of the network of the source of the + datagram. -- :var:`originNetmask` netmask of the source network +- :var:`originNetmask` is the netmask of the source network. -- :var:`group` the multicast group to be matched the destination of the +- :var:`group` is the multicast group to be matched to the destination of the datagram. If unspecified, then the route matches with -- :var:`parent` interface towards the parent link in the multicast +- :var:`parent` is the interface towards the parent link in the multicast tree. Only those datagrams are forwarded that arrived on the parent interface. -- :var:`children` the interfaces on which the multicast datagram to be - forwarded. Each entry contains a flag indicating if this interface is +- :var:`children` is the interfaces on which the multicast datagram is + to be forwarded. Each entry contains a flag indicating if this interface is a leaf in the multicast tree. The datagram is forwarded to leaf interfaces only if there are known members of the group in the attached LAN. -- :var:`source` enumerated value identifying the creator of the entry. - ``MANUAL`` for static routes, ``DVRMP`` for the DVMRP routers, - ``PIM_SM`` for PIM SM routers. +- :var:`source` is an enumerated value identifying the creator of the entry. + ``MANUAL`` means static routes; ``DVRMP`` means the DVMRP routers; + ``PIM_SM`` means PIM SM routers. -- :var:`metric` the “cost“ of the route. +- :var:`metric` is the “cost“ of the route. When there are several multicast routes matching the source and destination of the datagram, then the forwarding algorithm chooses the one with the -#. the longest matching source +#. longest matching source -#. the more specific group +#. most specific group -#. the smallest metric. +#. smallest metric. The ICMP Module --------------- -The :ned:`Icmp` module has two methods which can be used by other +The :ned:`Icmp` module has two methods that can be used by other modules to send ICMP error messages: - :fun:`sendErrorMessage(IPv4Datagram*, ICMPType, ICMPCode)` - used by the network layer to report erronous IPv4 datagrams. The ICMP + used by the network layer to report erroneous IPv4 datagrams. The ICMP header fields are set to the given type and code, and the ICMP message will encapsulate the given datagram. - :fun:`sendErrorMessage(cPacket*, IPv4ControlInfo*, ICMPType, ICMPCode)` - used by the transport layer components to report erronous packets. + used by the transport layer components to report erroneous packets. The transport packet will be encapsulated into an IP datagram before wrapping it into the ICMP message. @@ -419,18 +420,18 @@ sends it out on the ``errorOut`` gate unchanged. It is assumed that an external module is connected to ``errOut`` that can process the error packet. There is a simple module (:ned:`ErrorHandling`) that simply logs the error and drops the message. Note that the :ned:`Ipv4` -module does not send REDIRECT, DESTINATION_UNREACHABLE, TIME_EXCEEDED -and PARAMETER_PROBLEM messages to the :ned:`Icmp` module, it will send +module does not send REDIRECT, DESTINATION_UNREACHABLE, TIME_EXCEEDED, +and PARAMETER_PROBLEM messages to the :ned:`Icmp` module; it will send them to the transport layer module that sent the bogus packet encapsulated in the ICMP message. .. note:: - ICMP protocol encapsulates only the IP header + 8 byte following the IP header + The ICMP protocol encapsulates only the IP header + 8 bytes following the IP header from the bogus IP packet. The ICMP packet length computed from this truncated packet, despite it encapsulates the whole IP message object. As a consequence, calling :fun:`decapsulate()` on the ICMP message - will cause an "packet length became negative" error. To avoid this, + will cause a "packet length became negative" error. To avoid this, use :fun:`getEncapsulatedMsg()` to access the IP packet that caused the ICMP error. @@ -441,10 +442,11 @@ with an :msg:`IcmpHeader` and handed over to the IP. If :ned:`Icmp` receives an echo request from IP, the original message object will be returned as the echo reply. Of course, before sending -back the object to IP, the source and destination addresses are swapped +back the object to IP, the source and destination addresses are swapped, and the message type changed to ICMP_ECHO_REPLY. -When an ICMP echo reply received, the application message decapsulated +When an ICMP echo reply is received, the application message is decapsulated from it and passed to the application through the ``pingOut`` gate. -The :cpp:`Ipv4ControlInfo` also copied from the :msg:`IcmpHeader` to +The :cpp:`Ipv4ControlInfo` is also copied from the :msg:`IcmpHeader` to the application message. + diff --git a/doc/src/developers-guide/ch-logging.rst b/doc/src/developers-guide/ch-logging.rst index f0112b1092a..e6cf45143b4 100644 --- a/doc/src/developers-guide/ch-logging.rst +++ b/doc/src/developers-guide/ch-logging.rst @@ -16,21 +16,21 @@ letter and ending with correct punctuation. Log output that spans multiple lines should use indentation where it isn’t immediately obvious that the lines are related to each other. Dynamic content should be marked with single quotes. Key value pairs should be labeled and -separated by ’=’. Enumerated values should be properly separated with +separated by '='. Enumerated values should be properly separated with spaces. Target Audience --------------- -The people who read the log output can be divided based on the knowledge -they have regarding the protocol specification. They may know any of the +The people who read the log output can be divided based on their knowledge +regarding the protocol specification. They may know any of the following: -- public interface of the protocol +- Public interface of the protocol -- internal operation of the protocol +- Internal operation of the protocol -- actual implementation of the protocol +- Actual implementation of the protocol Log Levels ---------- @@ -42,52 +42,52 @@ OMNeT++ documentation. Fatal log level ~~~~~~~~~~~~~~~ -Target for people (not necessarily programmers) who know the public +Target audience: people (not necessarily programmers) who know the public interface. Don’t report programming errors, use C++ exceptions for this -purpose. Report protocol specific unrecoverable fatal error situations. +purpose. Report protocol-specific unrecoverable fatal error situations. Use rarely if at all. Error log level ~~~~~~~~~~~~~~~ -Target for people (not necessarily programmers) who know the public +Target audience: people (not necessarily programmers) who know the public interface. Don’t report programming errors, use C++ exceptions for this -purpose. Report protocol specific recoverable error situations. +purpose. Report protocol-specific recoverable error situations. Warn log level ~~~~~~~~~~~~~~ -Target for people (not necessarily programmers) who know the public -interface. Report protocol specific exceptional situations. Don’t report +Target audience: people (not necessarily programmers) who know the public +interface. Report protocol-specific exceptional situations. Don’t report things that occur too often such as collisions on a radio channel. Info log level ~~~~~~~~~~~~~~ -Target for people (not necessarily programmers) who know the public +Target audience: people (not necessarily programmers) who know the public interface. Think about the module as a closed (black) box. Report -protocol specific public input, output, state changes and decisions. +protocol-specific public input, output, state changes, and decisions. Detail log level ~~~~~~~~~~~~~~~~ -Target for users (not necessarily programmers) who know the internals. -Think about the module as an open (white) box. Report protocol specific +Target audience: users (not necessarily programmers) who know the internals. +Think about the module as an open (white) box. Report protocol-specific internal state changes and decisions. Report scheduling and processing -of protocol specific timers. +of protocol-specific timers. Debug log level ~~~~~~~~~~~~~~~ -Target for developers/maintainers who know the actual implementation. -Report implementation specific state changes and decisions. Report +Target audience: developers/maintainers who know the actual implementation. +Report implementation-specific state changes and decisions. Report important internal variable and data structure states and changes. Report current states and transitions of state machines. Trace log level ~~~~~~~~~~~~~~~ -Target for developers/maintainers who know the actual implementation. +Target audience: developers/maintainers who know the actual implementation. Report the execution of initialize stages, operation stages. Report entering/leaving functions, loops, code blocks, conditional branches, and recursions. @@ -95,13 +95,13 @@ and recursions. Log Categories -------------- -- *test*: report output that is checked for in automated tests +- *test*: report output that is checked for in automated tests -- *time*: report performance related data (e.g. measured wall clock +- *time*: report performance-related data (e.g. measured wall clock time) -- *parameter*: report actual parameter values picked up during +- *parameter*: report actual parameter values picked up during initialization -- *default (empty)*: report any other information using the default - category +- *default (empty)*: report any other information using the default + category \ No newline at end of file diff --git a/doc/src/developers-guide/ch-mobility.rst b/doc/src/developers-guide/ch-mobility.rst index c5e6920ca92..de6776f2111 100644 --- a/doc/src/developers-guide/ch-mobility.rst +++ b/doc/src/developers-guide/ch-mobility.rst @@ -15,40 +15,39 @@ The abstract :cpp:`MobilityBase` class is the base of the mobility modules defined in the INET framework. This class implements things like constraint area (or cubic volume), initial position, and border policy. -When the module is initialized it sets the initial position of the node +When the module is initialized, it sets the initial position of the node by calling the :fun:`initializePosition()` method. The default implementation handles the :par:`initFromDisplayString`, -:par:`initialX`, :par:`initialY`, :par:`initialZ` parameters. +:par:`initialX`, :par:`initialY`, and :par:`initialZ` parameters. The module is responsible for periodically updating the position. For -this purpose it should send timer messages to itself. These messages are +this purpose, it should send timer messages to itself. These messages are processed in the :fun:`handleSelfMessage` method. In derived classes, -:fun:`handleSelfMessage` should compute the new position and update the -display string and publish the new position by calling the +:fun:`handleSelfMessage` should compute the new position, update the +display string, and publish the new position by calling the :fun:`positionUpdated` method. When the node reaches the boundary of the constraint area, the mobility -component has to prevent the node to exit. It can call the +component has to prevent the node from exiting. It can call the :fun:`handleIfOutside` method, which offers policies like reflect, torus, random placement, and error. -MovingMobilityBase +MovingMobilityBase class ~~~~~~~~~~~~~~~~~~ -The abstract :cpp:`MovingMobilityBase` class can be used to model -mobilities when the node moves on a continous trajectory and updates its -position periodically. Subclasses only need to implement the -:fun:`move` method that is responsible to update the current position -and speed of the node. +The abstract :cpp:`MovingMobilityBase` class can be used to model mobilities +when the node moves on a continuous trajectory and updates its position +periodically. Subclasses only need to implement the :fun:`move` method, which is +responsible for updating the current position and speed of the node. -The abstract :fun:`move` method is called autmotically in every +The abstract :fun:`move` method is called automatically every :par:`updateInterval` steps. The method is also called when a client -requested the current position or speed or when the :fun:`move` method -requested an update at a future moment by setting the :var:`nextChange` +requests the current position or speed or when the :fun:`move` method +requests an update at a future moment by setting the :var:`nextChange` field. This can be used when the state of the motion changes at a specific time that is not a multiple of :par:`updateInterval`. The method can set the :par:`stationary` field to ``true`` to indicate -that the node reached its final position and no more position update is +that the node has reached its final position and no more position updates are needed. .. graphviz:: figures/mobility_classes.dot @@ -57,14 +56,14 @@ needed. LineSegmentsMobilityBase ~~~~~~~~~~~~~~~~~~~~~~~~ -The path of a mobile node often consist of linear movements of constant +The path of a mobile node often consists of linear movements of constant speed. The node moves with some speed for some time, then with another -speed for another duration and so on. If a mobility model fits this +speed for another duration, and so on. If a mobility model fits this description, it might be suitable to derive the implementing C++ class from :cpp:`LineSegmentsMobilityBase`. -The module first choose a target position and a target time by calling +The module first chooses a target position and a target time by calling the :fun:`setTargetPosition` method. If the target position differs from the current position, it starts to move toward the target and -updates the position in the configured :par:`updateInterval` intervals. -When the target position reached, it chooses a new target. +updates the position at the configured :par:`updateInterval` intervals. +When the target position is reached, it chooses a new target. \ No newline at end of file diff --git a/doc/src/developers-guide/ch-mpls.rst b/doc/src/developers-guide/ch-mpls.rst index e856585249e..4ec220251d3 100644 --- a/doc/src/developers-guide/ch-mpls.rst +++ b/doc/src/developers-guide/ch-mpls.rst @@ -16,21 +16,21 @@ The following algorithm is carried out by the MPLS module: :: - Step 1: - Check which layer the packet is coming from + Step 1: - Check from which layer the packet is coming Alternative 1: From layer 3 Step 1: Find and check the next hop of this packet Alternative 1: Next hop belongs to this MPLS cloud Step 1: Encapsulate the packet in an MPLS packet with IP_NATIVE_LABEL label - Step 2: Send to the next hop + Step 2: Send it to the next hop Step 3: Return Alternative 2: Next hop does not belong to this MPLS cloud Step 1: Send the packet to the next hop Alternative 2: From layer 2 - Step 1: Record the packet incoming interface + Step 1: Record the packet's incoming interface Step 2: - Check if the packet is for this LSR Alternative 1: Yes - Step 1: Check if the packet has label + Step 1: Check if the packet has a label Alternative 1: Yes Step 1: Strip off all labels and send the packet to L3 Step 2: Return @@ -43,14 +43,14 @@ The following algorithm is carried out by the MPLS module: Alternative 1: The packet is native IP Step 1: Check the LSR type Alternative 1: The LSR is an Ingress Router - Step 1: Look up LIB for outgoing label + Step 1: Look up the LIB for the outgoing label Alternative 1: Label cannot be found Step 1: Check if the label for this FEC is being requested Alternative 1: Yes Step 1: Return Alternative 2: No Step 1: Store the packet with FEC id - Step 2: Do request the signalling component + Step 2: Request the signalling component Step 3: Return Alternative 2: Label found Step 1: Carry out the label operation on the packet @@ -66,14 +66,14 @@ The following algorithm is carried out by the MPLS module: Step 2: Forward the packet to the outgoing interface found Step 3: Return Alternative 2: The LSR is not an Egress Router - Step 1: Look up LIB for outgoing label + Step 1: Look up the LIB for the outgoing label Alternative 1: Label cannot be found Step 1: Check if the label for this FEC is being requested Alternative 1: Yes Step 1: Return Alternative 2: No Step 1: Store the packet with FEC id - Step 2: Do request the signalling component + Step 2: Request the signalling component Step 3: Return Alternative 2: Label found Step 1: Carry out the label operation on the packet @@ -84,23 +84,23 @@ The following algorithm is carried out by the MPLS module: LDP Message Processing ---------------------- -The simulation follows message processing rules specified in RFC 3036 +The simulation follows the message processing rules specified in RFC 3036 (LDP Specification). A summary of the algorithm used in the RFC is presented below. Label Request Message processing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -An LSR may transmit a Request message under any of the conditions below: +An LSR may transmit a Request message under any of the following conditions: -- The LSR recognizes a new FEC via the forwarding tale, and the next +- The LSR recognizes a new FEC via the forwarding table, and the next hop is its LDP peer. The LIB of this LSR does not have a mapping from the next hop for the given FEC. -- Network topology changes, the next hop to the FEC is no longer valid +- Network topology changes, and the next hop to the FEC is no longer valid and new mapping is not available. -- The LSR receives a Label Request for a FEC from an upstream LDP and +- The LSR receives a Label Request for a FEC from an upstream LDP, and it does not have label binding information for this FEC. The FEC next hop is an LDP peer. @@ -124,9 +124,9 @@ performed: Alternative 2: There is no match Step 1: Construct a Notification message of No route and send this message back to the sender. - Step 4: Make query to local LIB to find out the corresponding label. - Alternative 1: The label found - Step 1: Construct a Label Mapping message and send over + Step 4: Make a query to the local LIB to find out the corresponding label. + Alternative 1: The label was found + Step 1: Construct a Label Mapping message and send it over the incoming interface. Alternative 2: The label cannot be found for this FEC Step 1: Construct a new Label Request message and send @@ -149,29 +149,29 @@ performed: Alternative 1: This FEC is outstanding Step 1: Continue Alternative 2: This FEC is not outstanding - Step 1: Send back the server an Notification of Error message. + Step 1: Send back the server a Notification of Error message. Step 3: Install the new label to the local LIB using the extracted label, - FEC and the message incoming interface. + FEC, and the message's incoming interface. The CSPF Algorithm ------------------ CSPF stands for Constraint Shortest Path First. This constraint-based -routing is executed online by Ingress Router. The CSPF calculates an +routing is executed online by the Ingress Router. The CSPF calculates an optimum explicit route (ER), based on specific constraints. CSPF relies on a Traffic Engineering Database (TED) to do those calculations. The resulting route is then used by RSVP-TE. -The CSPF in particular and any constraint based routing process requires -following inputs: +The CSPF, in particular, and any constraint-based routing process require +the following inputs: -- Attributes of the traffic trunks, e.g., bandwidth, link affinities +- Attributes of the traffic trunks, e.g., bandwidth, link affinities -- Attributes of the links of the network, e.g. bandwidth, delay +- Attributes of the links of the network, e.g. bandwidth, delay -- Attributes of the LSRs, e.g. types of signaling protocols supported +- Attributes of the LSRs, e.g. types of signaling protocols supported -- Other topology state information. +- Other topology state information. There has been no standard for CSPF so far. The implementation of CSPF in the simulation is based on the concept of "induced graph" introduced @@ -183,7 +183,7 @@ or links that do not match color constraints or configured policy. The CSPF algorithm used in the simulation has two phases. In the first phase, all the links that do not satisfy the constraints of bandwidth are excluded from the network topology. The link affinity is also -examined in this phase. In the second phase, Dijkstra algorithm is +examined in this phase. In the second phase, the Dijkstra algorithm is performed. Dijkstra Algorithm: diff --git a/doc/src/developers-guide/ch-naming.rst b/doc/src/developers-guide/ch-naming.rst index bff8cc62b63..1566f6ac55c 100644 --- a/doc/src/developers-guide/ch-naming.rst +++ b/doc/src/developers-guide/ch-naming.rst @@ -40,7 +40,7 @@ Modules - Ieee*: standard specific models - Ep*: energy/power related - Cc*: charge/current related -- *Source, *Sink, *Queue, *Server, *Buffer, *Filter, *Classifier, *Scheduler, *Gate: queueing model elements +- *Source, *Sink, *Queue, *Server, *Buffer, *Filter, *Classifier, *Scheduler, *Gate: queuing model elements - *CanvasVisualizer, *OsgVisualizer: visualizer modules - *Host, *Router: network nodes - *6: IPv6 variants @@ -50,7 +50,7 @@ C++ Classes ----------- - *Chunk: packet data representation -- *Serializer: protocol specific header and message serialiers +- *Serializer: protocol specific header and message serializers - *ProtocolDissector: protocol specific header and message dissectors - *ProtocolPrinter: protocol specific header and message printers - *Signal: physical layer signals (in contrast with binary data) @@ -69,9 +69,9 @@ Packets Tags ---- -- *Tag packet specific (meta information) +- *Tag: packet specific (meta information) - *Req -- *Ind packet specific protocol requests and indications (meta information) +- *Ind: packet specific protocol requests and indications (meta information) Signals ------- diff --git a/doc/src/developers-guide/ch-network-interfaces.rst b/doc/src/developers-guide/ch-network-interfaces.rst index b495ceb22bc..bba58c9abdf 100644 --- a/doc/src/developers-guide/ch-network-interfaces.rst +++ b/doc/src/developers-guide/ch-network-interfaces.rst @@ -2,7 +2,7 @@ .. _dg:cha:network-interfaces: -Network Interafces +Network Interfaces ================== Overview @@ -27,8 +27,6 @@ If a module wants to work with the interface table, first it needs to obtain a pointer to it. This can be done with the help of the :cpp:`InterfaceTableAccess` utility class: - - .. code-block:: c++ IInterfaceTable *ift = InterfaceTableAccess().get(); @@ -38,7 +36,7 @@ direct child of the host and be called ``"interfaceTable"`` in order to be able to find it. The :fun:`get()` method never returns ``NULL``: if it cannot find the interface table module or cannot cast it to the appropriate C++ type (:cpp:`IInterfaceTable`), it throws an -exception and stop the simulation with an error message. +exception and stops the simulation with an error message. For completeness, :cpp:`InterfaceTableAccess` also has a :fun:`getIfExists()` method which can be used if the code does not @@ -57,13 +55,13 @@ Interface Entries Interfaces in the interface table are represented with the :cpp:`NetworkInterface` class. :cpp:`IInterfaceTable` provides member -functions for adding, removing, enumerating and looking up interfaces. +functions for adding, removing, enumerating, and looking up interfaces. Interfaces have unique names and interface IDs; either can be used to look up an interface (IDs are naturally more efficient). Interface IDs are invariant to the addition and removal of other interfaces. -Data stored by an interface entry include: +Data stored by an interface entry includes: - *name* and *interface ID* (as described above) @@ -75,9 +73,9 @@ Data stored by an interface entry include: - *broadcast*: whether the interface supports broadcast - - *multicast* whether the interface supports multicast + - *multicast*: whether the interface supports multicast - - *pointToPoint*: whether the interface is point-to-point link + - *pointToPoint*: whether the interface is a point-to-point link - *loopback*: whether the interface is a loopback interface diff --git a/doc/src/developers-guide/ch-packets.rst b/doc/src/developers-guide/ch-packets.rst index 9ae3f181eaa..8c7bd071e99 100644 --- a/doc/src/developers-guide/ch-packets.rst +++ b/doc/src/developers-guide/ch-packets.rst @@ -8,10 +8,10 @@ Working with Packets Overview -------- -The INET Packet API is designed to ease the implementation of +The INET Packet API is designed to facilitate the implementation of communication protocols and applications by providing many useful C++ -components. In the following sections, we introduce the Packet API in -detail, and we shed light on many common API usages through examples. +components. In the following sections, we will introduce the Packet API in +detail, and we will shed light on many common API usages through examples. .. note:: @@ -23,7 +23,7 @@ detail, and we shed light on many common API usages through examples. The representation of packets is essential for communication network simulation. Applications and communication protocols construct, deconstruct, encapsulate, fragment, aggregate, and -manipulate packets in many ways. In order to ease the implementation of +manipulate packets in many ways. In order to facilitate the implementation of these behavioral patterns, INET provides a feature-rich general data structure, the :cpp:`Packet` class. @@ -33,7 +33,7 @@ packets, :protocol:`TCP` segments, :protocol:`IP` datagrams, kinds of digital data. It is designed to provide efficient storage, duplication, sharing, encapsulation, aggregation, fragmentation, serialization, and data representation selection. Additional functionality, -such as support for enqueueing data for transmisson and buffering received +such as support for enqueueing data for transmission and buffering received data for reassembly and/or for reordering, is provided as separate C++ data structures on top of :cpp:`Packet`. @@ -94,7 +94,7 @@ concatenation. :end-before: !End :name: Chunk concatenation example -Protocols often need to slice data, for example to provide +Protocols often need to slice data, for example, to provide fragmentation, which is also directly supported by the chunk API. .. literalinclude:: lib/Snippets.cc @@ -142,7 +142,7 @@ Representing Packets The :cpp:`Packet` data structure uses a single chunk data structure to represent its contents. The contents may be as simple as raw bytes -(:cpp:`BytesChunk`), but most likely it will be the concatenation +(:cpp:`BytesChunk`), but most likely, it will be the concatenation (:cpp:`SequenceChunk`) of various protocol specific headers (e.g., :cpp:`FieldsChunk` subclasses) and application data (e.g., :cpp:`ByteCountChunk`). @@ -212,7 +212,7 @@ but computationally expensive solutions. - change bits in raw chunks (accurate) -The first example shows how to represent transmission erros on the +The first example shows how to represent transmission errors on the packet level. A packet is marked as erroneous based on its length and the associated bit error rate. This representation doesn’t give too much chance for a protocol to do anything else than discard an erroneous @@ -250,7 +250,7 @@ or correct any part based on checksums. The physical layer models support the above mentioned different error representations via configurable parameters. Higher layer protocols -detect errors by chechking the error bit on packets and chunks, and by +detect errors by checking the error bit on packets and chunks, and by standard CRC mechanisms. .. _dg:sec:packets:packet-tagging: @@ -278,7 +278,7 @@ Packet tags are not transmitted from one network node to another. All physical layer protocols delete all packet tags from a packet before sending it to the connected peer or to the transmission medium. -For more details on what kind of tags are there see the +For more details on what kinds of tags are there, see the .. _dg:sec:packets:region-tagging: @@ -322,7 +322,7 @@ Dissecting Packets Understanding what’s inside a packet is a very important and often used functionality. Simply using the representation may be insufficient, because the :cpp:`Packet` may be represented with a :cpp:`BytesChunk`, -for exmple. The Packet API provides a :cpp:`PacketDissector` class which +for example. The Packet API provides a :cpp:`PacketDissector` class which analyzes a packet solely based on the assigned packet protocol and the actual data it contains. @@ -363,12 +363,12 @@ Filtering Packets Filtering packets based on the actual data they contain is another widely used and very important feature. With the help of the packet -dissector, it is very simple to create arbitrary custom packet filters. +dissector, it is straightforward to create arbitrary custom packet filters. Packet filters are generally used for recording packets and visualizing -various packet related information. +various packet-related information. In order to simplify filtering, the Packet API provides a generic -expression based packet filter which is implemented in the +expression-based packet filter that is implemented in the :cpp:`PacketFilter` class. The expression syntax is the same as other OMNeT++ expressions, and the data filter is matched against individual chunks of the packet as found by the packet dissector. @@ -390,20 +390,18 @@ prefix. Printing Packets ---------------- -During model development, packets often need to be displayed in a human -readable form. The Packet API provides a :cpp:`PacketPrinter` class -which is capable of forming a human readable string representation of -:cpp:`Packet`’s. The :cpp:`PacketPrinter` class relies on small -registered protocol-specific printer classes (e.g. -:cpp:`Ipv4ProtocolPrinter` subclassing the required +During model development, packets often need to be displayed in a human-readable +form. The Packet API provides a :cpp:`PacketPrinter` class that is capable of +forming a human-readable string representation of :cpp:`Packet`'s. The +:cpp:`PacketPrinter` class relies on small registered protocol-specific printer +classes (e.g. :cpp:`Ipv4ProtocolPrinter`) subclassing the required :cpp:`ProtocolPrinter` base class. -The packet printer is automatically used by the OMNeT++ runtime user -interface to display packets in the packet log window. The packet -printer contributes several log window columns into the user interface: -’Source’, ’Destination’, ’Protocol’, ’Length’, and ’Info’. These columns -display packet data similarly to the well-known Wireshark protocol -analyzer. +The packet printer is automatically used by the OMNeT++ runtime user interface +to display packets in the packet log window. The packet printer contributes +several log window columns into the user interface: 'Source', 'Destination', +'Protocol', 'Length', and 'Info'. These columns display packet data similarly to +the well-known Wireshark protocol analyzer. .. literalinclude:: lib/Snippets.cc :language: cpp @@ -411,9 +409,8 @@ analyzer. :end-before: !End :name: Packet printing example -The :cpp:`PacketPrinter` provides a few other functions which have -additional options to control the details of the resulting human -readable form. +The :cpp:`PacketPrinter` provides a few other functions that have additional +options to control the details of the resulting human readable form. .. _dg:sec:packets:recording-pcap: @@ -421,9 +418,9 @@ Recording PCAP -------------- Exporting the packets from a simulation into a PCAP file allows further -processing with 3rd party tools. The Packet API provides a -:cpp:`PcapDump` class for creating PCAP files. Packet filtering can be -used to reduce the file size and increase performance. +processing with 3rd party tools. The Packet API provides a :cpp:`PcapDump` class +for creating PCAP files. Packet filtering can be used to reduce the file size +and increase performance. .. literalinclude:: lib/Snippets.cc :language: cpp @@ -437,13 +434,13 @@ Encapsulating Packets --------------------- Many communication protocols work with simple packet encapsulation. They -encapsulate packets with their own protocol specific headers and trailers at -the sender node, and they decapsulate packets at the reciver node. The headers +encapsulate packets with their own protocol-specific headers and trailers at +the sender node, and they decapsulate packets at the receiver node. The headers and trailers carry the information that is required to provide the protocol specific service. For example, the Ethernet MAC protocol encapsulates an IP datagram by prepending -the packet with an Ethernet MAC header, and also by appending the packet with an +the packet with an Ethernet MAC header and also by appending the packet with an optional padding and an Ethernet FCS. The following example shows how a MAC protocol could encapsulate a packet: @@ -454,7 +451,7 @@ protocol could encapsulate a packet: :name: Packet encapsulation example When receiving a packet, the Ethernet MAC protocol removes an Ethernet MAC header -and an Ethernet FCS from the packet, and passes the resulting IP datagram along. +and an Ethernet FCS from the packet and passes the resulting IP datagram along. The following example shows how a MAC protocol could decapsulate a packet: .. literalinclude:: lib/Snippets.cc @@ -464,9 +461,9 @@ The following example shows how a MAC protocol could decapsulate a packet: :name: Packet decapsulation example Although the :fun:`popAtFront` and :fun:`popAtBack` functions change the remaining -unprocessed part of the packet, they don’t have effect on the actual packet data. -That is when the packet reaches high level protocol, it still contains all the -received data but the remaining unprocessed part is smaller. +unprocessed part of the packet, they do not have an effect on the actual packet data. +That is when the packet reaches high-level protocol, it still contains all the +received data, but the remaining unprocessed part is smaller. .. _dg:sec:packets:fragmenting-packets: @@ -490,7 +487,7 @@ example shows how a MAC protocol could fragment a packet: :name: Packet fragmentation example When receiving fragments, protocols need to collect the coherent -fragments of the same packet until all fragments becomes available. The +fragments of the same packet until all fragments become available. The following example shows how a MAC protocol could form the original packet from a set of coherent fragments: @@ -508,13 +505,13 @@ Aggregating Packets Communication protocols often provide aggregation to better utilize the communication channel by reducing protocol overhead. They wait for several packets to arrive at the sender node, then they form a large -aggregated packet which is in turn sent at once. At the receiver node +aggregated packet which is in turn sent at once. At the receiver node, the aggregated packet is split into the original packets, and they are passed along. For example, the IEEE 802.11 protocol aggregates packets for better channel utilization at both MSDU and MPDU levels. The following example -shows a version of how a MAC protocol could create an aggregate packet: +shows how a MAC protocol could create an aggregate packet: .. literalinclude:: lib/Snippets.cc :language: cpp @@ -522,7 +519,7 @@ shows a version of how a MAC protocol could create an aggregate packet: :end-before: !End :name: Packet aggregation example -The following example shows a version of how a MAC protocol could +The following example shows how a MAC protocol could disaggregate a packet: .. literalinclude:: lib/Snippets.cc @@ -536,11 +533,11 @@ disaggregate a packet: Serializing Packets ------------------- -In real communication systems packets are usually stored as a sequence +In real communication systems, packets are usually stored as a sequence of bytes directly in network byte order. In contrast, INET usually -stores packets in small field based C++ classes (generated by the +stores packets in small field-based C++ classes (generated by the OMNeT++ MSG compiler) to ease debugging. In order to calculate checksums -or to communicate with real hardware, all protocol specific parts must +or to communicate with real hardware, all protocol-specific parts must be serializable to a sequence of bytes. The protocol header serializers are separate classes from the actual @@ -555,7 +552,7 @@ sequence of bytes: :end-before: !End :name: Packet serialization example -Deserialization is somewhat more complicated than serialization, because +Deserialization is somewhat more complicated than serialization because it must be prepared to handle incomplete or even incorrect data due to errors introduced by the network. The following example shows how a MAC protocol header could be deserialized from a sequence of bytes: @@ -576,10 +573,10 @@ converted to and from a sequence of bytes. The reason is that the programming interface of operating systems and external libraries work with sending and receiving raw data. -All protocol headers and data chunks which are present in a packet must +All protocol headers and data chunks that are present in a packet must have a registered serializer to be able to create the raw sequence of bytes. Protocol modules must also be configured to either disable or -compute checksums, because serializers cannot carry out the checksum +compute checksums because serializers cannot carry out the checksum calculation. The following example shows how a packet could be converted to a @@ -602,11 +599,11 @@ sequence of bytes when receiving from an external interface: In INET, all protocols automatically support hardware emulation due to the dual representation of packets. The above example creates a packet -which contains a single chunk with a sequence of bytes. As the packet is -passed through the protocols, they can interpret the data (e.g. by +that contains a single chunk with a sequence of bytes. As the packet is +passed through the protocols, they can interpret the data (e.g., by calling :fun:`peekAtFront`) as they see fit. The Packet API always provides the requested representation, either because it’s already -available in the packet, or because it gets automatically deserialized. +available in the packet or because it gets automatically deserialized. .. _dg:sec:packets:queueing-packets: @@ -615,7 +612,7 @@ Queueing Packets Some protocols store packet data temporarily at the sender node before actual processing can occur. For example, the TCP protocol must store -the outgoing data received from the application in order to be able to +the outgoing data received from the application to be able to provide transmission flow control. The following example shows how a transport protocol could store the @@ -628,8 +625,8 @@ received data temporarily until the data is actually used: :name: Packet queueing example The :cpp:`ChunkQueue` class acts similarly to a binary FIFO queue except -it works with chunks. Similarly to the :cpp:`Packet` it also -automatically merge consecutive data and selects the most appropriate +it works with chunks. Similarly to the :cpp:`Packet`, it also +automatically merges consecutive data and selects the most appropriate representation. .. _dg:sec:packets:buffering-packets: @@ -642,22 +639,22 @@ until the actual processing can occur. For example, packets may arrive out of order, and the data they contain must be reassembled or reordered before it can be passed along. -INET provides a few special purpose C++ classes to support data +INET provides a few special-purpose C++ classes to support data buffering: - :cpp:`ChunkBuffer` provides automatic merging for large data chunks from out of order smaller data chunks. -- :cpp:`ReassemblyBuffer` provides reassembling for out of order data +- :cpp:`ReassemblyBuffer` provides reassembling for out-of-order data according to an expected length. -- :cpp:`ReorderBuffer` provides reordering for out of order data into a +- :cpp:`ReorderBuffer` provides reordering for out-of-order data into a continuous data stream from an expected offset. All buffers deal with only the data, represented by chunks, instead of packets. They automatically merge consecutive data and select the most appropriate representation. Protocols using these buffers automatically -support all data representation provided by INET, and any combination +support all data representations provided by INET, and any combination thereof. For example, :cpp:`ByteCountChunk`, :cpp:`BytesChunk`, :cpp:`FieldsChunk`, and :cpp:`SliceChunk` can be freely mixed in the same buffer. @@ -673,7 +670,7 @@ node to be prepared for receiving parts out of order and potentially duplicated. For example, the IP protocol must store incoming fragments at the -receiver node, because it must wait until the datagram becomes complete, +receiver node because it must wait until the datagram becomes complete before it can be passed along. The IP protocol must also be prepared for receiving the individual fragments out of order and potentially duplicated. @@ -703,7 +700,7 @@ to be prepared for receiving parts out of order and potentially duplicated. For example, the TCP protocol must buffer the incoming data at the -receiver node, because the TCP segments may arrive out of order and +receiver node because the TCP segments may arrive out of order and potentially duplicated or overlapping, and TCP is required to provide the data to the application in the correct order and only once. diff --git a/doc/src/developers-guide/ch-physicallayer.rst b/doc/src/developers-guide/ch-physicallayer.rst index 184848d8cf9..f0169672ddb 100644 --- a/doc/src/developers-guide/ch-physicallayer.rst +++ b/doc/src/developers-guide/ch-physicallayer.rst @@ -52,7 +52,7 @@ physical medium model where communication takes place. Simulating the physical layer is generally a computation-intensive task. A detailed simulation of signal propagation, signal fading, signal -interference, and signal decoding often results in an unacceptable +interference, and signal decoding often results in unacceptable performance. Finding the right abstractions, the right level of detail, and the right trade-offs between accuracy and performance is both difficult and important. @@ -77,7 +77,7 @@ Customizability ~~~~~~~~~~~~~~~ Real-world communication devices often provide a wide variety of -configuration options to allow them to be adaped to the physical +configuration options to allow them to be adapted to the physical conditions where they are required to operate. For example, a Wifi router’s administration interface often provides parameters to configure the transmission power, bitrate, preamble type, carrier frequency, RTS @@ -130,7 +130,7 @@ Scalable Level of Detail There are many possible ways to model various aspects of the physical layer. The most important difference lies in the trade-off between performance versus accuracy. In order to support the different -trade-offs the physical layer is designed to be scalable with respect to +trade-offs, the physical layer is designed to be scalable with respect to the simulated level of detail. In other words, it is scalable from high-performance less accurate simulations to high fidelity slower simulations. @@ -165,14 +165,14 @@ provides more customization opportunities to replace parts with alternative implementations and to do research easier in the area. The data representation might vary from scalar to multidimensional -values. In the analog domain of the physical layer data quite often +values. In the analog domain of the physical layer, data quite often changes over time, frequency, space, or any combination thereof. The most obvious example is the analog signal power, but there are others such as signal phase or the signal to noise ratio. The number of messages per transmission added to the future event queue might vary from one to the number of radios. One message might be -sufficient, for example, if the transmission is intended to a single +sufficient, for example, if the transmission is intended for a single destination, and other receivers are either not affected, or the effect is negligible. On the other hand, it might be necessary to process all transmissions by all receivers in order to have the desired effect on @@ -187,10 +187,10 @@ parallel. The computation of the transmission arrival space-time coordinates, the analog signal representation of transmissions and receptions, the interfering receptions and noises, the signal to noise ratio, the decoded bits, the bit errors, and the physical layer -indications all provide a good parallelization opportunity, because they +indications all provide a good parallelization opportunity because they dominate the physical layer performance and are independent for each -receiver. Therefore the physical layer is designed to be able to utilize -parallel hardware, multi-core CPUs, vector instructions and the highly +receiver. Therefore, the physical layer is designed to be able to utilize +parallel hardware, multi-core CPUs, vector instructions, and the highly parallel GPU. The idea is to have a central component in the software architecture @@ -198,7 +198,7 @@ where parallel computation can happen. This central component is the medium model that knows about all radios, transmissions, interferences, and receptions anyway. It uses optimistic parallel computation in multiple background threads while the main simulation thread continues -normal execution. When a new transmission enters the channel the already +normal execution. When a new transmission enters the channel, the already computed and affected results are invalidated or updated, and the affected ongoing optimistic parallel computations are canceled. @@ -211,7 +211,7 @@ model, a transmitter model, a receiver model, and an energy consumer model. The antenna model is shared between the transmitter model and the receiver model. The separation of the transmitter model and the receiver model allows asymmetric configurations. The energy consumer model is -optional and it is only used when the simulation of energy consumption +optional, and it is only used when the simulation of energy consumption is necessary. The radio model has an operational mode that is called the radio mode. @@ -260,22 +260,22 @@ The signaled receiver states are the following: When a radio wants to transmit a signal on the medium, it sends direct messages to all affected radios with the help of the central medium -module. The messages contain a shared data structure which describes the +module. The messages contain a shared data structure that describes the transmission the way it entered the medium. The messages arrive at the -moment when start of the transmission arrive at the receiver. The +moment when start of the transmission arrives at the receiver. The receiver radios also handle the incoming messages with the help of the central medium module. This kind of centralization allows the medium to do shared computations in a more efficient way and it also makes parallel computation possible. -To maintain modularity, the radio module delegates many of is functions +To maintain modularity, the radio module delegates many of its functions to submodules. The following sections describe the parts of the radio model. Antenna Models ~~~~~~~~~~~~~~ -The antenna model describes the effects of the physical device which +The antenna model describes the effects of the physical device that converts electric signals into radio waves, and vice versa. This model captures the antenna characteristics that heavily affect the quality of the communication channel. For example, various antenna shapes, antenna @@ -307,30 +307,30 @@ directory. Transmitter Models ~~~~~~~~~~~~~~~~~~ -The transmitter model describes the physical process which converts +The transmitter model describes the physical process that converts packets into electric signals. In other words, this model converts a MAC packet into a signal that is transmitted on the medium. The conversion -process and the representation of the signal depends on the level of +process and the representation of the signal depend on the level of detail and the physical characteristics of the implemented protocol. -In the flat model the transmitter model skips the symbol domain and the +In the flat model, the transmitter model skips the symbol domain and the sample domain representations, and it directly creates the analog domain representation. The bit domain representation is reduced to the bit -length of the packet and the actual bits are ignored. +length of the packet, and the actual bits are ignored. -In the layered model the conversion process involves various processing +In the layered model, the conversion process involves various processing steps such as packet serialization, forward error correction encoding, scrambling, interleaving, and modulation. This transmitter model requires much more computation, but it produces accurate bit domain, symbol domain, and sample domain representations. -The various protocol specific transmitter models are in the +The various protocol-specific transmitter models are in the corresponding directories. Receiver Models ~~~~~~~~~~~~~~~ -The receiver model describes the physical process which converts +The receiver model describes the physical process that converts electric signals into packets. In other words, this model converts a reception, along with an interference computed by the medium model, into a MAC packet and a reception indication. It also determines the @@ -347,19 +347,19 @@ following for each transmission: based on the error model and the simulated part of the signal decoding -In the flat model the receiver model skips the sample domain, the symbol +In the flat model, the receiver model skips the sample domain, the symbol domain, and the bit domain representations, and it directly creates the packet domain representation by copying the packet from the transmission. It uses the error model to decide if the reception is successful or not. -In the layered model the conversion process involves various processing +In the layered model, the conversion process involves various processing steps such as demodulation, descrambling, deinterleaving, forward error correction decoding, and deserialization. This reception model requires much more computation, but it produces accurate sample domain, symbol domain, and bit domain representations. -The various protocol specific receiver models are in the corresponding +The various protocol-specific receiver models are in the corresponding directories. Transmission Error Modeling @@ -367,22 +367,22 @@ Transmission Error Modeling Determining the reception errors is a crucial part of the reception process. There are often several different statistical error models in -the literature even for a particular physical layer. In order to support -this diversity the error model is a separate replaceable component of +the literature, even for a particular physical layer. In order to support +this diversity, the error model is a separate replaceable component of the receiver. -The error model describes how the signal to noise ratio affects the +The error model describes how the signal-to-noise ratio affects the amount of errors at the receiver. The main purpose of this model is to -determine whether if the received packet has errors or not. It also +determine whether the received packet has errors or not. It also computes various physical layer indications for higher layers such as packet error rate, bit error rate, and symbol error rate. For the -layered reception model it needs to compute the erroneous bits, symbols, -or samples depending on the lowest simulated physical domain where the -real decoding starts. The error model is optional, if omitted all +layered reception model, it needs to compute the erroneous bits, symbols, +or samples, depending on the lowest simulated physical domain where the +real decoding starts. The error model is optional; if omitted, all receptions are considered successful. The error models are in the ``src/physicallayer/errormodel/`` -directory and also in the corresponding protocol specific directories. +directory and also in the corresponding protocol-specific directories. Power Consumption Models ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -390,15 +390,20 @@ Power Consumption Models A substantial part of the energy consumption of communication devices comes from transmitting and receiving signals. The energy consumer model describes how the radio consumes energy depending on its activity. This -model is optional, if omitted energy consumption is ignored. The +model is optional; if omitted, energy consumption is ignored. The following list provides some examples: -- :ned:`StateBasedEpEnergyConsumer`: Models energy consuption based on power. The constant power consumption is - determined by valid combinations of the radio mode, the transmitter - state and the receiver state. To be used with energy generator and storage modules using `energy and power` (denoted with `Ep` in the module name). -- :ned:`StateBasedCcEnergyConsumer`: Models energy consuption based on current. The constant current consumption is - determined by valid combinations of the radio mode, the transmitter - state and the receiver state. To be used with energy generator and storage modules using `charge and current` (denoted with `Ep` in the module name). +- :ned:`StateBasedEpEnergyConsumer`: Models energy consumption based on power. + The constant power consumption is determined by valid combinations of the + radio mode, the transmitter state, and the receiver state. To be used with + energy generator and storage modules using `energy and power` (denoted with + ``Ep`` in the module name). + +- :ned:`StateBasedCcEnergyConsumer`: Models energy consumption based on + current. The constant current consumption is determined by valid combinations + of the radio mode, the transmitter state, and the receiver state. To be used + with energy generator and storage modules using `charge and current` (denoted + with ``Ep`` in the module name). The energy consumer models are in the ``src/physicallayer/energyconsumer/`` directory. @@ -450,10 +455,10 @@ The Medium Model The medium model describes the shared physical medium where communication takes place. It keeps track of radios, noise sources, ongoing transmissions, background noise, and other ongoing noises. The -medium computes when, where and how transmissions and noises arrive at +medium computes when, where, and how transmissions and noises arrive at receivers. It also efficiently provides the set of interfering transmissions and noises for the receivers. It doesn’t send or handle -messages on its own, it rather acts as a mediator between radios. +messages on its own; it rather acts as a mediator between radios. The medium model has a separate chapter devoted to it, see :doc:`ch-transmission-medium`. @@ -461,7 +466,7 @@ The medium model has a separate chapter devoted to it, see Signal Representation --------------------- -The data structures that represent the transmitted and the received +The data structures that represent the transmitted and received signals might contain many different data depending on the simulated level of detail. In addition, the reception data structure might contain various physical layer indications, which are computed during the @@ -487,11 +492,11 @@ reception process. The following list provides some examples: power, receive signal strength indication, signal to noise and interference ratio, etc. -In simple case the packet domain specifies the MAC packet only, and the +In a simple case, the packet domain specifies the MAC packet only, and the bit domain specifies the bit length and the bitrate. The symbol domain -specifies the used modulation, and the sample domain is simply ignored. +specifies the modulation used, and the sample domain is simply ignored. The most important part is the analog domain representation, because it -is indispensable to be able to compute some kind of signal to noise and +is indispensable to be able to compute some kind of signal-to-noise and interference ratio. The following figure shows four different kinds of analog domain representations, but other representations are also possible. @@ -504,7 +509,7 @@ possible. Various analog signal representations -The first representation is called range-based, and it is used by the +The first representation is called *range-based*, and it is used by the unit disc radio. The advantage of this data structure is that it is compact, predictable, and provides high performance. The disadvantage is that it is very inaccurate in terms of modeling reality. Nevertheless, @@ -513,26 +518,26 @@ protocol if accurate simulation of packet loss is not important. The second data structure represents a narrowband signal with a scalar signal power, a carrier frequency, and a bandwidth. The advantage of -this representation is that it allows to compute a real signal to noise +this representation is that it allows to compute a real signal-to-noise ratio, which in turn can be used by the error model to compute bit and packet error rates. This representation is most of the time sufficient for the simulation of IEEE 802.11 networks. The third data structure describes a signal power that changes over -time. In this case the signal power is represented with a -one-dimensional time dependent value that precisely follows the +time. In this case, the signal power is represented with a +one-dimensional time-dependent value that precisely follows the transmitted pulses. This representation is used by the IEEE 802.15.4a UWB radio. The last representation uses a multi-dimensional value to describe the signal power that changes over both time and frequency. The IEEE 802.11b model might use this representation to simulate crosstalk, where one -channel interferes with another. In order to make it work the frequency +channel interferes with another. In order to make it work, the frequency spectrum of the signal has to follow the real spectrum more precisely at both ends of the band. The flat signal representation uses a single object to simulatenously -describe all domains of the transmission or the reception. In contrast, +describe all domains of the transmission or reception. In contrast, the layered signal representation uses one object to describe every domain seperately. The advantage of the latter is that it is extensible with alternative implementations for each domain. The disadvantage is @@ -543,7 +548,7 @@ Signal Processing The following figure shows the process of how a MAC packet gets from the transmitter radio through the medium to the receiver radio. The figure -focues on how data flows between the processing components of the +focuses on how data flows between the processing components of the physical layer. The blue boxes represent the data structures, and the red boxes represent the processing components. @@ -557,56 +562,56 @@ red boxes represent the processing components. The transmission process starts in the transmitter radio when it receives a MAC packet from the higher layer. The radio must be in -transmitter or transceiver mode before receiving a MAC packet, otherwise -it throws an exception. At first the transmitter model creates a data +transmitter or transceiver mode before receiving a MAC packet; otherwise, +it throws an exception. At first, the transmitter model creates a data structure that describes the transmitted signal based on the received MAC packet and the attached transmission request. The resulting data -structure is immutable, it is not going to be changed in any later +structure is immutable; it is not going to be changed in any later processing step. -Thereafter the propagation model computes the arrival space-time -coordinates for all receivers. In the next step the medium model +Thereafter, the propagation model computes the arrival space-time +coordinates for all receivers. In the next step, the medium model determines the set of affected receivers. Which radio constitutes -affected depends on a number of factors such as the maximum +affected depends on a number of factors, such as the maximum communication range of the transmitter, the radio mode of the receiver, the listening mode of the receiver, or potentially the MAC address of -the receiver. Using the result the medium model sends a separate message +the receiver. Using the result, the medium model sends a separate message with the shared transmission data structure to all affected receivers. There’s no need to send a message to all radios on the channel, because the computation of interfering signals is independent of this step. -Thereafter the attenuation model computes the reception for the receiver +Thereafter, the attenuation model computes the reception for the receiver using the original transmission and the arrival data structure. It -applies the path loss model, the obstacle loss model and the multipath +applies the path loss model, the obstacle loss model, and the multipath model to the transmission. The resulting data structure is also -immutable, it is not going to be changed in any later processing step. +immutable; it is not going to be changed in any later processing step. -Thereafter the medium model computes the interference for the reception +Thereafter, the medium model computes the interference for the reception by collecting all interfering receptions and noises. Another signal is -considered interfering if it owerlaps both in time and frequency domains +considered interfering if it overlaps both in time and frequency domains with respect to the minimum interference parameters. The background noise model also computes a noise signal that is added to the interference. The reception process starts in the receiver radio when it receives a message from the transmitter radio. The radio must be in receiver or -transceiver mode before the message arrives, otherwise it ignores the -message. At first the receiver model determines is whether the reception +transceiver mode before the message arrives; otherwise, it ignores the +message. At first, the receiver model determines whether the reception is actually attempted or not. This decision depends on the reception power, whether there’s another ongoing reception process, and capturing is enabled or not. -Thereafter the receiver model computes the signal to noise and +Thereafter, the receiver model computes the signal to noise and interference ratio from the reception and the interference. Using the -result, the bitrate, and the modulation scheme the error model computes -the necessary error rates. Alternatively the error model might compute -the erroneous bits, or symbols by altering the corresponding data of the +result, the bitrate, and the modulation scheme, the error model computes +the necessary error rates. Alternatively, the error model might compute +the erroneous bits or symbols by altering the corresponding data of the original transmission. -Thereafter the receiver determines the received MAC packet by either -simply reusing the original, or actually decoding from the lowest +Thereafter, the receiver determines the received MAC packet by either +simply reusing the original or actually decoding from the lowest represented domain in the reception. Finally, it attaches the physical -layer indication to the MAC packet, and sends it up to the higher layer. +layer indication to the MAC packet and sends it up to the higher layer. The following sections describe the data structures that are created during signal processing. @@ -616,7 +621,7 @@ Transmission Request This data structure contains parameters that control how the transmitter produces the transmission. For example, it might override the default -transmission power, ot the default bitrate of the transmitter. It is +transmission power or the default bitrate of the transmitter. It is attached as a control info object to the MAC packet sent down from the MAC module to the radio. @@ -625,14 +630,14 @@ Transmission This data structure describes the transmission of a signal. It specifies the start/end time, start/end antenna position, start/end antenna -orientation of the transmitter. In other words, it describes when, where +orientation of the transmitter. In other words, it describes when, where, and how the signal started/ended to interact with the medium. The transmitter model creates one transmission instance per MAC packet. Arrival ~~~~~~~ -This data structure decscirbes the space and time coordinates of a +This data structure describes the space and time coordinates of a transmission arriving at a particular receiver. It specifies the start/end time, start/end antenna position, start/end antenna orientation of the receiver. The propagation model creates one arrival @@ -660,7 +665,7 @@ Noise This data structure describes a meaningless signal or a meaningless composition of multiple signals. All models contain at least the -start/end time, and start/end position. +start/end time and start/end position. Interference ~~~~~~~~~~~~ @@ -679,7 +684,7 @@ and interference ratio. Reception Decision ~~~~~~~~~~~~~~~~~~ -This data structure describes whether if the reception of a signal is +This data structure describes whether the reception of a signal is possible or not, is attempted or not, and is successful or not. Reception Indication @@ -695,7 +700,7 @@ module. Visualization ------------- -In order to help understanding the communication in the network the +In order to help understand the communication in the network, the physical layer supports visualizing its state. The following list shows what can be displayed: @@ -705,9 +710,9 @@ what can be displayed: - recent obstacle intersections and surface normal vectors -The ongoing transmissions can be displayed with 3 dimensional spheres or -with 2 dimensional rings laying in the XY plane. As the signal -propagates through space the figure grows with it to show where the +The ongoing transmissions can be displayed with 3-dimensional spheres or +with 2-dimensional rings laying in the XY plane. As the signal +propagates through space, the figure grows with it to show where the beginning of the signal is. The inner circle of the ring figure shows as the end of the signal propagates through space. @@ -731,3 +736,5 @@ TODO: wireless vs. wired medium Use Cases --------- + +Describe use cases here. \ No newline at end of file diff --git a/doc/src/developers-guide/ch-ppp.rst b/doc/src/developers-guide/ch-ppp.rst index 8710167fcdd..05b089edbd9 100644 --- a/doc/src/developers-guide/ch-ppp.rst +++ b/doc/src/developers-guide/ch-ppp.rst @@ -28,8 +28,9 @@ Extending the PPP Module TODO how (override handleMessage etc.) -signals: +Signals: +--------- -Notifications are sent when transmission of a new PPP frame started -(``NF_PP_TX_BEGIN``), finished (``NF_PP_TX_END``) or when a PPP frame -received (``NF_PP_RX_END``). +Notifications are sent when transmission of a new PPP frame starts +(``NF_PP_TX_BEGIN``), finishes (``NF_PP_TX_END``), or when a PPP frame +is received (``NF_PP_RX_END``). \ No newline at end of file diff --git a/doc/src/developers-guide/ch-sockets.rst b/doc/src/developers-guide/ch-sockets.rst index 622d4a31b65..012db9b5b5b 100644 --- a/doc/src/developers-guide/ch-sockets.rst +++ b/doc/src/developers-guide/ch-sockets.rst @@ -50,7 +50,7 @@ Identifying Sockets All sockets have a socket identifier which is unique within the network node. It is automatically assigned to the sockets when they are created. -The identifier can accessed with :fun:`getSocketId()` throughout the +The identifier can be accessed with :fun:`getSocketId()` throughout the lifetime of the socket. The socket identifier is also passed along in :cpp:`SocketReq` and @@ -113,7 +113,7 @@ In general, sockets can process all incoming messages which were sent by the underlying protocol. The received messages must be processed by the socket where they belong to. -For example, an application can simply go through each knonwn socket in +For example, an application can simply go through each known socket in any order, and decide which one should process the received message as follows: @@ -138,7 +138,7 @@ in general the state of the socket is expected to affect it. For example, after the socket is properly configured, the application can start sending packets without attaching any tags, because the socket -takes care of the necessary technical details: +takes cares of the necessary technical details: .. literalinclude:: lib/Snippets.cc :language: cpp @@ -164,7 +164,7 @@ Closing Sockets Sockets must be closed before deleting them. Closing a socket allows the underlying communication protocol to release allocated resources. These resources are often allocated on the local network node, the remote -nework node, or potentially somewhere else in the network. +network node, or potentially somewhere else in the network. For example, a socket for a connection oriented protocol must be closed to release the allocated resources at the peer: @@ -230,8 +230,8 @@ Configuring Sockets ~~~~~~~~~~~~~~~~~~~ For receiving :protocol:`UDP` datagrams on a socket, it must be bound to -an address and a port. Both the address and port is optional. If the -address is unspecified, than all :protocol:`UDP` datagrams with any +an address and a port. Both the address and port are optional. If the +address is unspecified, then all :protocol:`UDP` datagrams with any destination address are received. If the port is -1, then an unused port is selected automatically by the :ned:`Udp` module. The address and port pair must be unique within the same network node. @@ -284,7 +284,7 @@ connect to the destination. The :protocol:`UDP` protocol is in fact connectionless, so when the :ned:`Udp` module receives the connect request, it simply remembers the -remote address and port, and use it as default destination for later +remote address and port, and uses it as the default destination for later sends. .. literalinclude:: lib/Snippets.cc @@ -340,7 +340,7 @@ indication: Configuring Connections ~~~~~~~~~~~~~~~~~~~~~~~ -The :ned:`Tcp` module supports several :protocol:`TCP` different +The :ned:`Tcp` module supports several different :protocol:`TCP` congestion algorithms, which can also be configured using the :cpp:`TcpSocket`: @@ -351,13 +351,13 @@ congestion algorithms, which can also be configured using the :name: TCP socket configure example Upon setting the individual parameters, the socket immediately sends -sevice requests to the underlying :ned:`Tcp` protocol module. +service requests to the underlying :ned:`Tcp` protocol module. Setting up Connections ~~~~~~~~~~~~~~~~~~~~~~ -Since :protocol:`TCP` is a connection oriented protocol, a connection -must be established before applications can exchange data. On the one +Since :protocol:`TCP` is a connection-oriented protocol, a connection +must be established before applications can exchange data. On one side, the application listens at a local address and port for incoming :protocol:`TCP` connections: @@ -380,7 +380,7 @@ Accepting Connections ~~~~~~~~~~~~~~~~~~~~~ The :ned:`Tcp` module automatically notifies the :cpp:`TcpSocket` about -incoming connections. The socket in turn notifies the application using +incoming connections. The socket, in turn, notifies the application using the :fun:`ICallback::socketAvailable` method of the callback interface. Finally, incoming :protocol:`TCP` connections must be accepted by the application before they can be used: @@ -482,15 +482,13 @@ specific connection parameters directly: :name: SCTP socket configure example Upon setting the individual parameters, the socket immediately sends -sevice requests to the underlying :ned:`Sctp` protocol module. - -.. _setting-up-connections-1: +service requests to the underlying :ned:`Sctp` protocol module. Setting up Connections ~~~~~~~~~~~~~~~~~~~~~~ -Since :protocol:`SCTP` is a connection oriented protocol, a connection -must be established before applications can exchange data. On the one +Since :protocol:`SCTP` is a connection-oriented protocol, a connection +must be established before applications can exchange data. On one side, the application listens at a local address and port for incoming :protocol:`SCTP` connections: @@ -515,7 +513,7 @@ Accepting Connections ~~~~~~~~~~~~~~~~~~~~~ The :ned:`Sctp` module automatically notifies the :cpp:`SctpSocket` -about incoming connections. The socket in turn notifies the application +about incoming connections. The socket, in turn, notifies the application using the :fun:`ICallback::socketAvailable` method of the callback interface. Finally, incoming :protocol:`SCTP` connections must be accepted by the application before they can be used: @@ -594,9 +592,9 @@ the received data: Configuring Sockets ~~~~~~~~~~~~~~~~~~~ -In order to only receive :protocol:`IPv4` datagrams which are sent to a -specific local address or contain a specific protocol, the socket can be -bound to the desired local address or protocol. +In order to only receive :protocol:`IPv4` datagrams sent to a specific +local address or containing a specific protocol, the socket can be bound +to the desired local address or protocol. For example, the following code fragment shows how the INET :ned:`PingApp` binds to the :protocol:`ICMPv4` protocol to receive all @@ -644,7 +642,7 @@ destination: The :protocol:`IPv4` protocol is in fact connectionless, so when the :ned:`Ipv4` module receives the connect request, it simply remembers the -remote address, and uses it as the default destination address for later +remote address and uses it as the default destination address for later sends. The application can call :fun:`connect()` several times on the same @@ -696,9 +694,9 @@ the received data: Configuring Sockets ~~~~~~~~~~~~~~~~~~~ -In order to only receive :protocol:`IPv6` datagrams which are sent to a -specific local address or contain a specific protocol, the socket can be -bound to the desired local address or protocol. +In order to only receive :protocol:`IPv6` datagrams sent to a specific +local address or containing a specific protocol, the socket can be bound +to the desired local address or protocol. For example, the following code fragment shows how the INET :ned:`PingApp` binds to the :protocol:`ICMPv6` protocol to receive all @@ -744,10 +742,9 @@ destination: :end-before: !End :name: IPv6 socket send example -The :protocol:`IPv6` protocol is in fact connectionless, so when the +The :protocol:`IPv6` protocol is, in fact, connectionless, so when the :ned:`Ipv6` module receives the connect request, it simply remembers the -remote address, and uses it as the default destination address for later -sends. +remote address and uses it as the default destination for later sends. The application can call :fun:`connect()` several times on the same socket. @@ -785,7 +782,7 @@ Callback Interface ~~~~~~~~~~~~~~~~~~ Messages received from the network protocol module must be processed by -the associated socket where as shown in the general section. The +the associated socket as shown in the general section. The :cpp:`L3Socket` deconstructs the message and uses the :cpp:`L3Socket::ICallback` interface to notify the application about the received data: @@ -858,7 +855,7 @@ destination address, it can optionally connect to the destination: :end-before: !End :name: L3 socket send example -The network protocols are in fact connectionless, so when the protocol +The network protocols are, in fact, connectionless, so when the protocol module receives the connect request, it simply remembers the remote address, and uses it as the default destination address for later sends. diff --git a/doc/src/developers-guide/ch-tags.rst b/doc/src/developers-guide/ch-tags.rst index 7aadb27f3e1..624edb773ef 100644 --- a/doc/src/developers-guide/ch-tags.rst +++ b/doc/src/developers-guide/ch-tags.rst @@ -10,19 +10,19 @@ Overview Modules often exchange information by sending packets along with supplementary data, referred to as tags. A tag is usually a small data structure that focuses -on a single parameterization aspect of a protocol. Tags can be attached to the +on a single aspect of a protocol's parameterization. Tags can be attached to the whole packet, known as packet tags, or to specific parts of the packet, known -as region tags. Tags are implemented as data container C++ classes and they are -usually generated by the OMNeT++ MSG compiler. These are the primary types of -tags: +as region tags. Tags are implemented as C++ classes that serve as data containers +and are usually generated by the OMNeT++ MSG compiler. The primary types of tags +are as follows: -- *requests* carry information from higher layers to lower layers (e.g. :cpp:`MacAddressReq`). -- *indications* carry information from lower layers to higher layers (e.g. :cpp:`InterfaceInd`). -- *plain tags* contain some meta-information (e.g. :cpp:`PacketProtocolTag`). -- *base classes* must not be attached to packets (e.g. :cpp:`TagBase`). +- *Requests* carry information from higher layers to lower layers (e.g., :cpp:`MacAddressReq`). +- *Indications* carry information from lower layers to higher layers (e.g., :cpp:`InterfaceInd`). +- *Plain tags* contain meta-information (e.g., :cpp:`PacketProtocolTag`). +- *Base classes* must not be attached to packets (e.g., :cpp:`TagBase`). For example, a request tag that specifies the source and destination MAC address -could be implemented in an MSG file as follows: +could be implemented in an MSG file as shown below: .. literalinclude:: lib/Snippets.msg :language: msg @@ -30,104 +30,91 @@ could be implemented in an MSG file as follows: :end-before: !End :name: Tag definition example -The following list gives a short description of several often used packet tags: - -- :cpp:`PacketProtcolTag` specifies the protocol of the packet's contents -- :cpp:`DispatchProtocolReq` specifies the receiver protocol module inside the network node -- :cpp:`EncapsulationProcotolReq` specifies the requested protocol header encapsulation order -- :cpp:`SocketReq` specifies the application socket -- :cpp:`L4PortReq` specifies the source and destination ports -- :cpp:`L3AddressReq` specifies source and destination network addresses -- :cpp:`InterfaceReq` specifies the outgoing network interface -- :cpp:`NextHopAddressReq` specifies the next hop address for packet routing -- :cpp:`VlanReq` specifies the virtual LAN identifier of IEEE 802.1Q -- :cpp:`PcpReq` specifies the priority code point of IEEE 802.1Q -- :cpp:`StreamReq` specifies the TSN stream identifier inside the network node -- :cpp:`MacAddressReq` specifies source and destination MAC addresses -- :cpp:`Ieee80211ModeReq` specifies the IEEE 802.11 PHY mode -- :cpp:`Ieee80211ChannelReq` specifies the IEEE 802.11 channel -- :cpp:`SignalPowerReq` specifies transmit signal power - -All request tags have their indication counterparts. For example, there are -indications such as :cpp:`SocketInd`, :cpp:`InterfaceInd`, :cpp:`StreamInd`. -The requests are usually attached to outgoing packets, the indications are +The following is a short description of several commonly used packet tags: + +- :cpp:`PacketProtcolTag`: Specifies the protocol of the packet's contents. +- :cpp:`DispatchProtocolReq`: Specifies the receiver protocol module inside the network node. +- :cpp:`EncapsulationProcotolReq`: Specifies the requested protocol header encapsulation order. +- :cpp:`SocketReq`: Specifies the application socket. +- :cpp:`L4PortReq`: Specifies the source and destination ports. +- :cpp:`L3AddressReq`: Specifies source and destination network addresses. +- :cpp:`InterfaceReq`: Specifies the outgoing network interface. +- :cpp:`NextHopAddressReq`: Specifies the next-hop address for packet routing. +- :cpp:`VlanReq`: Specifies the virtual LAN identifier of IEEE 802.1Q. +- :cpp:`PcpReq`: Specifies the priority code point of IEEE 802.1Q. +- :cpp:`StreamReq`: Specifies the TSN stream identifier inside the network node. +- :cpp:`MacAddressReq`: Specifies source and destination MAC addresses. +- :cpp:`Ieee80211ModeReq`: Specifies the IEEE 802.11 PHY mode. +- :cpp:`Ieee80211ChannelReq`: Specifies the IEEE 802.11 channel. +- :cpp:`SignalPowerReq`: Specifies transmit signal power. + +All request tags have their corresponding indication tags. For example, there +are indications such as :cpp:`SocketInd`, :cpp:`InterfaceInd`, and :cpp:`StreamInd`. +The requests are usually attached to outgoing packets, while the indications are usually attached to incoming packets. -The following list gives a short description of several often used region tags: +The following is a short description of several commonly used region tags: -- :cpp:`IdentityTag` uniquely identifies individual bits in the network over - the lifetime of the whole simulation -- :cpp:`CreationTimeTag` specifies the creation time of data regions for - lifetime measurements -- :cpp:`FlowTag` specifies the packet flows of data regions for various flow - specific measurements -- :cpp:`PacketEventTag` carries information about queueing, processing, - transmission, etc. events that happened to data regions +- :cpp:`IdentityTag`: Uniquely identifies individual bits in the network over the lifetime of the whole simulation. +- :cpp:`CreationTimeTag`: Specifies the creation time of data regions for lifetime measurements. +- :cpp:`FlowTag`: Specifies the packet flows of data regions for various flow-specific measurements. +- :cpp:`PacketEventTag`: Carries information about queueing, processing, transmission, etc. events that happened to data regions. -.. _dg:sec:tags:protocol-layers: Communicating Through Protocol Layers ------------------------------------- -Tags can pass through protocol modules, and they can reach far beyond the module -that initially attached them, in both downward and upward directions. Typically, -tags are removed at the point where they are processed, usually being transformed -into header fields within a packet, or used for some protocol specific decisions. -Protocols have the liberty to disregard any tags at their discretion based on -their configuration and state. +Tags can pass through protocol modules, potentially reaching far beyond the module +that initially attached them, in both the downward and upward directions. Typically, +tags are removed at the point where they are processed, either by being transformed +into header fields within a packet or used for some protocol-specific decision-making. +Protocols have the freedom to disregard any tags based on their configuration and state. -Both packet tags and region tags remain unchanged for many operations that protocol -modules carry out with packets. For example, when packets are enqueued/dequeued, -encapsulated/decapsulated, cloned, buffered, or stored for later reuse, the tags -remain unchanged. - -.. _dg:sec:tags:packet-protocol: +Both packet tags and region tags usually remain unchanged for many operations +that protocol modules carry out with packets. For example, when packets are +enqueued/dequeued, encapsulated/decapsulated, cloned, buffered, or stored for later reuse, +the tags remain unchanged. Specifying the Protocol of a Packet ------------------------------------ +---------------------------------- The most important packet tag is the :cpp:`PacketProtocolTag`. It specifies the -outermost protocol of the packet. This tag should always be present, because the +outermost protocol of the packet. This tag should always be present because the packet protocol cannot be correctly determined just by looking at the raw data. -In contrast, the inner protocol headers in the packet can be usually recursively +In contrast, the inner protocol headers in the packet can usually be recursively identified by protocol fields such as the protocol ID field of the IPv4 header. -The :cpp:`PacketProtocolTag` is used among others for dissecting the packet -along the protocol headers, or for printing the packet as a human readable -string to help interpreting its contents. +The :cpp:`PacketProtocolTag` is used, among other things: +- for dissecting the packet along the protocol headers, +- for printing the packet as a human-readable string to help interpret its contents. -Normally a packet is transformed from one protocol to another in a single step, +Normally, a packet is transformed from one protocol to another in a single step, so the packet protocol tag either specifies the protocol before the operation or the protocol after the operation. For example, the :ned:`Udp` protocol module encapsulates the outgoing packet using a :cpp:`UdpHeader`. The packet protocol -is set to an application specific protocol before the UDP encapsulation and it's -set to UDP protocol after the encapsulation. +is set to an application-specific protocol before the UDP encapsulation, and it's +set to the UDP protocol after the encapsulation. Sometimes, protocol implementations themselves are split up into several smaller modules. For example, the modular Ethernet implementation uses a separate module -for the insertion of the Ethernet MAC header and the Ethernet FCS. This module -structure implies that the packet can be seen between the modules as a partially -built Ethernet MAC protocol packet. In such a case the packet protocol tag can -only specify the inner protocol that is being encapsulated into an Ethernet MAC -frame. - -.. _dg:sec:tags:dispatching-packets: +for the insertion of the Ethernet MAC header and the Ethernet FCS. In such a case, +the packet protocol tag can only specify the inner protocol that is being encapsulated +into an Ethernet MAC frame. Dispatching Packets to Protocol Modules ---------------------------------------- +-------------------------------------- Inside a network node, protocol modules interact with one another by sending -:cpp:`Packet` or :cpp:`Message` objects. INET is very flexible in terms of what -structure the protocol modules can be connected. Protocols can be connected -directly to each other, or they can be connected through one or more -:ned:`MessageDispatcher` modules. This flexibility allows for the creation of -both simple and complex network node architectures. +:cpp:`Packet` or :cpp:`Message` objects. INET provides great flexibility in terms +of how the protocol modules can be connected. Protocols can be connected directly +to each other or they can be connected through one or more :ned:`MessageDispatcher` +modules. This flexibility allows for the creation of simple as well as complex +network node architectures. How to Connect Protocol Modules ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Simple network nodes can be constructed, for example, using a linear protocol -stack, where protocol modules are directly connected to one another without -using message dispatcher modules. +Simple network nodes can be constructed using a linear protocol stack, where +protocol modules are directly connected to one another without using message dispatcher modules. .. figure:: figures/SimpleHost.png :width: 160 @@ -135,7 +122,7 @@ using message dispatcher modules. Simple network node structure in the IDE More complex network nodes can be created by grouping protocols into layers and -connecting them through :ned:`MessageDispatcher` modules, which facilitates +connecting them through :ned:`MessageDispatcher` modules, which facilitate many-to-one and many-to-many relationships among the protocols of the layers. .. figure:: figures/ComplexHost.png @@ -145,15 +132,14 @@ many-to-one and many-to-many relationships among the protocols of the layers. It's also possible to use message dispatcher modules hierarchically within multiple levels of nested compound modules. Ultimately, one could even connect -all protocols to a single central message dispatcher module. There is an important -limitation though, only one instance of a given protocol module can be connected -to a message dispatcher. +all protocols to a single central message dispatcher module. However, please note +that only one instance of a given protocol module can be connected to a message dispatcher. To support the packet dispatching mechanism, certain additional requirements -must be met in C++ code: +must be met in the C++ code: -- protocols must be registered using :fun:`registerProtocol` -- packets must have :cpp:`DispatchProtocolReq` tags attached +- Protocols must be registered using the :fun:`registerProtocol` function. +- Packets must have the :cpp:`DispatchProtocolReq` tags attached. Registering Protocols ~~~~~~~~~~~~~~~~~~~~~ @@ -170,15 +156,15 @@ IPv4 protocol implementation: Registering the protocols allows the dispatcher modules to learn which gates the protocol modules are connected to. The same protocol is not allowed to be -registered in the same message dispatcher using different gates, because that +registered in the same message dispatcher using different gates because that would make the dispatching mechanism ambiguous. Sending Packets with Dispatch Request ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Packets and messages must have the :cpp:`DispatchProtocolReq` tag attached to -them in order for the message dispatcher modules to correctly dispatch them to -the intended recipient within the network node. The following example shows how +In order for the message dispatcher modules to correctly dispatch packets to +the intended recipient within the network node, packets and messages must have +the :cpp:`DispatchProtocolReq` tag attached. The following example shows how a MAC protocol could send up a packet to the :ned:`Ipv4` protocol module without actually knowing where that module is connected in the network node architecture: @@ -190,7 +176,7 @@ actually knowing where that module is connected in the network node architecture The :cpp:`DispatchProtocolReq` tag specifies both the intended recipient protocol and the requested service primitive. The service primitive, similarly to OSI -terminology, can be one of: +terminology, can be one of the following: - :cpp:`SP_REQUEST` for service requests from layer N+1 to layer N - :cpp:`SP_CONFIRM` for service confirmations from layer N to layer N+1 @@ -198,35 +184,35 @@ terminology, can be one of: - :cpp:`SP_RESPONSE` for protocol response from layer N+1 to layer N Currently, INET modules only use the :cpp:`SP_REQUEST` and :cpp:`SP_INDICATION` -service primitives, the other two are only present for completeness. The request -service primitive is used when a higher layer protocol module (e.g. :ned:`Tcp`) -wants to deliver a packet to a lower layer protocol module (e.g. :ned:`Ipv4`). +service primitives; the other two are only present for completeness. The request +service primitive is used when a higher layer protocol module (e.g., :ned:`Tcp`) +wants to deliver a packet to a lower layer protocol module (e.g., :ned:`Ipv4`). Similarly, the :cpp:`SP_INDICATION` service primitive is used when a lower layer -protocol module (e.g. :ned:`Ethernet`) wants to deliver a packet to a higher layer -protocol module (e.g. :ned:`Ipv4`). +protocol module (e.g., :ned:`Ethernet`) wants to deliver a packet to a higher layer +protocol module (e.g., :ned:`Ipv4`). Determining the Next Protocol ----------------------------- A protocol module has several options for determining which protocol to forward -a packet to. The list below shows some possibilities: +a packet to. Some possibilities include: -- The next protocol can be hard-coded in C++. For example, the UDP protocol is - hard-coded in C++ in the :cpp:`UdpSocket` class, and similarly other protocols - are also hard-coded in other protocol specific sockets. +- Hard-coding the next protocol in C++. For example, the UDP protocol is + hard-coded in C++ in the :cpp:`UdpSocket` class, and similarly, other protocols + are also hard-coded in other protocol-specific sockets. -- The next protocol can be specified by a module parameter, as is the case of - a network interface module specifying its expected protocol. The :ned:`Ipv4` - module uses this information to dispatch a packet to the expected protocol - of the selected route's network interface. +- Specifying the next protocol using a module parameter. For instance, a network + interface module can specify its expected protocol. The :ned:`Ipv4` module + uses this information to dispatch a packet to the expected protocol of the + selected route's network interface. -- The next protocol can be dependent on module state. For example, the TSN +- Determining the next protocol based on module state. For example, the TSN stream encoder module forwards packets that match the TSN stream mapping to the 802.1 Q-TAG protocol for encapsulation. -- The next protocol can be determined by a packet header field. For example, - the :ned:`Ipv4` module uses the IP protocol ID header field from the - :cpp:`Ipv4Header` to look up the next protocol as shown below: +- Determining the next protocol based on a packet header field. The :ned:`Ipv4` + module, for example, uses the IP protocol ID header field from the + :cpp:`Ipv4Header` to look up the next protocol, as shown below: .. literalinclude:: lib/Snippets.cc :language: cpp @@ -234,32 +220,29 @@ a packet to. The list below shows some possibilities: :end-before: !End :name: Next protocol example -- The next protocol can be determined by some packet meta-data. For example, - the :ned:`Tcp` module uses the type of the destination address from the - :cpp:`L3AddressReq` tag to determine if the packet should be sent to the - :ned:`Ipv4` or :ned:`Ipv6` module. +- Determining the next protocol based on packet metadata. For instance, the :ned:`Tcp` module + uses the type of the destination address from the :cpp:`L3AddressReq` tag to determine + whether the packet should be sent to the :ned:`Ipv4` or :ned:`Ipv6` module. -- The next protocol can be indirectly specified by a protocol encapsulation - request. For example, other modules may have attached an :cpp:`EncapsulationProtocolReq` - to the packet in an earlier stage of the packet processing. - -.. _dg:sec:tags:encapsulation-order: +- Indirectly specifying the next protocol via a protocol encapsulation request. + Other modules may have attached an :cpp:`EncapsulationProtocolReq` to the + packet in an earlier stage of the packet processing. Controlling the Packet Encapsulation Order ------------------------------------------ A packet typically contains multiple protocol-specific headers, such as TCP, IP, Ethernet, and sometimes additional optional headers like 802.1Q, 802.1R, 802.1AE, -and others. The order of packet headers is determined by the order in which the -packet reaches the relevant protocol modules for encapsulation. +and others. The order of the packet headers is determined by the order in which +the packet reaches the relevant protocol modules for encapsulation. The encapsulation process may need to be different for each packet. For example, an application may need to send a packet to a specific VLAN. In this case, the application should attach a :cpp:`VlanReq` tag to the packet with the desired VLAN ID. However, it cannot directly send the packet to the relevant 802.1Q -protocol module, because the packet may need to be delivered to the UDP protocol +protocol module because the packet may need to be delivered to the UDP protocol first. To achieve the desired protocol encapsulation order, the application should -also attach an :cpp:`EncapsulationProtocolReq` tag specifying that the packet +also attach an :cpp:`EncapsulationProtocolReq` tag that specifies that the packet should ultimately be delivered to the 802.1Q protocol for encapsulation. The underlying protocol modules will use this information to determine when the 802.1Q encapsulation should take place. @@ -268,40 +251,37 @@ The :cpp:`EncapsulationProtocolReq` generally outlines the sequence of protocol modules that a packet should be delivered to for further encapsulation. Additional tags attached to the packet are used as additional parameters for the requested processing steps. The attached encapsulation request may be changed several times -during packet processing, new protocols may be added, already added protocols -may be removed, and so on. +during packet processing; new protocols may be added, already added protocols +may be removed, etc. For example, the IP protocol determines the outgoing interface using the routing table and the destination address. The selected network interface specifies the expected protocol that the packet should have in order for the interface module to operate properly. The specified protocol is appended to the end of the requested -encapsulation protocols of the packet, because it should be the last encapsulation +encapsulation protocols of the packet because it should be the last encapsulation before the packet reaches the network interface. For example, if the IP module selects an Ethernet network interface, then it appends the Ethernet MAC protocol -to the :cpp:`EncapsulationProtocolReq`, and the packet is ultimately encapsulated +to the :cpp:`EncapsulationProtocolReq`. As a result, the packet is ultimately encapsulated into an :cpp:`EthernetMacHeader` before reaching the network interface module. -.. _dg:sec:tags:inbound-packets-to-outbound: - Transforming Inbound Packets to Outbound ---------------------------------------- As part of the forwarding process of Ethernet switches, an inbound packet is -transformed into an outbound packet. This process is carried out by default in +transformed into an outbound packet. By default, this process is carried out by the :ned:`PacketDirectionReverser` module. The transformation is more like a -policy and it can be replaced by the user with other modules. The default module -doesn't change the packet contents except for removing the already popped front -and back parts, but it changes the attached packet tags significantly. +policy and can be replaced by the user with other modules. The default module +doesn't change the packet contents, except for removing the already popped front +and back parts. However, it changes the attached packet tags significantly. The inbound packet usually contains a few tags such as :cpp:`PacketProtocolTag` and :cpp:`DirectionTag`, and it also contains several indications such as the :cpp:`InterfaceInd`, :cpp:`MacAddressInd`, :cpp:`VlandInd`, :cpp:`PcpInd`, -:cpp:`EncapsulationProtocolInd` and so on. The transformation keeps only the -:cpp:`PacketProtocolTag`, it removes all attached indications, and attaches a -set of requests so that the packet will be encapsulated in the same protocol -headers, and it will be sent out on the same interface as it came in. +:cpp:`EncapsulationProtocolInd`, etc. During the transformation, only the +:cpp:`PacketProtocolTag` is kept, and all attached indications are removed. +Additionally, a set of requests is attached to the packet so that the packet will +be encapsulated in the same protocol headers and sent out on the same interface as it came in. Of course, this is just the start of the processing of the outbound packet. -During the several steps that follows any of the attached requests can be -replaced with new ones potentially ultimately resulting in the packet to be -handled in a completely different way. +During the several steps that follow, any of the attached requests can be +replaced with new ones, potentially resulting in the packet being handled in a completely different way. \ No newline at end of file diff --git a/doc/src/developers-guide/ch-tcp.rst b/doc/src/developers-guide/ch-tcp.rst index fe923165c82..08c489b5a75 100644 --- a/doc/src/developers-guide/ch-tcp.rst +++ b/doc/src/developers-guide/ch-tcp.rst @@ -12,10 +12,10 @@ The :ned:`Tcp` model relies on sending and receiving :cpp:`IPControlInfo` objects attached to TCP segment objects as control info (see :fun:`cMessage::setControlInfo()`). -The :ned:`Tcp` module manages several :cpp:`TcpConnection` object each +The :ned:`Tcp` module manages several :cpp:`TcpConnection` objects, each holding the state of one connection. The connections are identified by a -connection identifier which is choosen by the application. If the -connection is established it can also be identified by the local and +connection identifier which is chosen by the application. If the +connection is established, it can also be identified by the local and remote addresses and ports. The TCP module simply dispatches the incoming application commands and packets to the corresponding object. @@ -27,25 +27,25 @@ TCP packets The INET framework models the TCP header with the :msg:`TcpHeader` message class. This contains the fields of a TCP frame, except: -- *Data Offset*: represented by :fun:`cMessage::length()` +- *Data Offset*: represented by :fun:`cMessage::length()` -- *Reserved* +- *Reserved* -- *Checksum*: modelled by :fun:`cMessage::hasBitError()` +- *Checksum*: modeled by :fun:`cMessage::hasBitError()` -- *Options*: only EOL, NOP, MSS, WS, SACK_PERMITTED, SACK and TS are - possible +- *Options*: only EOL, NOP, MSS, WS, SACK_PERMITTED, SACK, and TS are + possible -- *Padding* +- *Padding* The Data field can either be represented by (see :cpp:`TcpDataTransferMode`): -- encapsulated C++ packet objects, +- encapsulated C++ packet objects, -- raw bytes as a :cpp:`ByteArray` instance, +- raw bytes as a :cpp:`ByteArray` instance, -- its byte count only, +- its byte count only, corresponding to transfer modes OBJECT, BYTESTREAM, BYTECOUNT resp. @@ -107,95 +107,95 @@ TCP parameters The :ned:`Tcp` module has the following parameters: -- :par:`advertisedWindow` in bytes, corresponds with the maximal - receiver buffer capacity (Note: normally, NIC queues should be at - least this size, default is 14*mss) +- :par:`advertisedWindow` in bytes, corresponds with the maximal + receiver buffer capacity (Note: normally, NIC queues should be at + least this size, default is 14*mss) -- :par:`delayedAcksEnabled` delayed ACK algorithm (RFC 1122) - enabled/disabled +- :par:`delayedAcksEnabled` delayed ACK algorithm (RFC 1122) + enabled/disabled -- :par:`nagleEnabled` Nagle’s algorithm (RFC 896) enabled/disabled +- :par:`nagleEnabled` Nagle’s algorithm (RFC 896) enabled/disabled -- :par:`limitedTransmitEnabled` Limited Transmit algorithm (RFC 3042) - enabled/disabled (can be used for - TCPReno/TCPTahoe/TCPNewReno/TCPNoCongestionControl) +- :par:`limitedTransmitEnabled` Limited Transmit algorithm (RFC 3042) + enabled/disabled (can be used for + TCPReno/TCPTahoe/TCPNewReno/TCPNoCongestionControl) -- :par:`increasedIWEnabled` Increased Initial Window (RFC 3390) - enabled/disabled +- :par:`increasedIWEnabled` Increased Initial Window (RFC 3390) + enabled/disabled -- :par:`sackSupport` Selective Acknowledgment (RFC 2018, 2883, 3517) - support (header option) (SACK will be enabled for a connection if - both endpoints support it) +- :par:`sackSupport` Selective Acknowledgment (RFC 2018, 2883, 3517) + support (header option) (SACK will be enabled for a connection if + both endpoints support it) -- :par:`windowScalingSupport` Window Scale (RFC 1323) support (header - option) (WS will be enabled for a connection if both endpoints - support it) +- :par:`windowScalingSupport` Window Scale (RFC 1323) support (header + option) (WS will be enabled for a connection if both endpoints + support it) -- :par:`timestampSupport` Timestamps (RFC 1323) support (header option) - (TS will be enabled for a connection if both endpoints support it) +- :par:`timestampSupport` Timestamps (RFC 1323) support (header option) + (TS will be enabled for a connection if both endpoints support it) -- :par:`mss` Maximum Segment Size (RFC 793) (header option, default is - 536) +- :par:`mss` Maximum Segment Size (RFC 793) (header option, default is + 536) -- :par:`tcpAlgorithmClass` the name of TCP flavour +- :par:`tcpAlgorithmClass` the name of the TCP flavour - Possible values are “TCPReno” (default), “TCPNewReno”, “TCPTahoe”, - “TCPNoCongestionControl” and “DumpTCP”. In the future, other classes - can be written which implement Vegas, LinuxTCP or other variants. See - section `1.3 <#sec:tcp_algorithms>`__ for detailed description of - implemented flavours. + Possible values are “TCPReno” (default), “TCPNewReno”, “TCPTahoe”, + “TCPNoCongestionControl” and “DumpTCP”. In the future, other classes + can be written which implement Vegas, LinuxTCP or other variants. See + section `1.3 <#sec:tcp_algorithms>`__ for detailed description of + implemented flavours. - Note that TCPOpenCommand allows tcpAlgorithmClass to be chosen - per-connection. + Note that TCPOpenCommand allows tcpAlgorithmClass to be chosen + per-connection. -- :par:`recordStats` if set to false it disables writing excessive - amount of output vectors +- :par:`recordStats` if set to false it disables writing an excessive + amount of output vectors TCP connections --------------- -Most part of the TCP specification is implemented in the -:cpp:`TcpConnection` class: takes care of the state machine, stores the +Most of the TCP specification is implemented in the +:cpp:`TcpConnection` class: it takes care of the state machine, stores the state variables (TCB), sends/receives SYN, FIN, RST, ACKs, etc. TCPConnection itself implements the basic TCP “machinery”, the details of congestion control are factored out to :cpp:`TcpAlgorithm` classes. -There are two additional objects the :cpp:`TcpConnection` relies on +There are two additional objects that the :cpp:`TcpConnection` relies on internally: instances of :cpp:`TcpSendQueue` and :cpp:`TcpReceiveQueue`. -These polymorph classes manage the actual data stream, so +These polymorph classes manage the actual data stream, so the :cpp:`TcpConnection` itself only works with sequence number variables. -This makes it possible to easily accommodate need for various types of +This makes it possible to easily accommodate the need for various types of simulated data transfer: real byte stream, "virtual" bytes (byte counts -only), and sequence of :cpp:`cMessage` objects (where every message +only), and a sequence of :cpp:`cMessage` objects (where every message object is mapped to a TCP sequence number range). Data transfer modes ~~~~~~~~~~~~~~~~~~~ -Different applications have different needs how to represent the +Different applications have different needs as to how to represent the messages they communicate with. Sometimes it is enough to simulate the -amount of data transmitted (“200 MB”), contents does not matter. In -other scenarios contents matters a lot. The messages can be represented +amount of data transmitted (“200 MB”), and contents do not matter. In +other scenarios, contents matter a lot. The messages can be represented as a stream of bytes, but sometimes it is easier for the applications to pass message objects to each other (e.g. HTTP request represented by a :msg:`HTTPRequest` message class). The TCP modules in the INET framework support 3 data transfer modes: -- ``TCP_TRANSFER_BYTECOUNT``: only byte counts are represented, no - actual payload in :msg:`TcpHeader`’s. The TCP sends as many TCP - segments as needed +- ``TCP_TRANSFER_BYTECOUNT``: only byte counts are represented, no + actual payload in :msg:`TcpHeader`’s. The TCP sends as many TCP + segments as needed -- ``TCP_TRANSFER_BYTESTREAM``: the application can pass byte arrays - to the TCP. The sending TCP breaks down the bytes into MSS sized - chunks and transmits them as the payload of the TCP segments. The - receiving application can read the chunks of the data. +- ``TCP_TRANSFER_BYTESTREAM``: the application can pass byte arrays + to the TCP. The sending TCP breaks down the bytes into MSS sized + chunks and transmits them as the payload of the TCP segments. The + receiving application can read the chunks of the data. -- ``TCP_TRANSFER_OBJECT``: the application pass a :cpp:`cMessage` - object to the TCP. The sending TCP sends as many TCP segments as - needed according to the message length. The :cpp:`cMessage` object is - also passed as the payload of the first segment. The receiving - application receives the object only when its last byte is received. +- ``TCP_TRANSFER_OBJECT``: the application passes a :cpp:`cMessage` + object to the TCP. The sending TCP sends as many TCP segments as + needed according to the message length. The :cpp:`cMessage` object is + also passed as the payload of the first segment. The receiving + application receives the object only when its last byte is received. These values are defined in :file:`TCPCommand.msg` as the :cpp:`TcpDataTransferMode` enumeration. The application can set the data @@ -206,10 +206,10 @@ Opening connections ~~~~~~~~~~~~~~~~~~~ Applications can open a local port for incoming connections by sending -the TCP a TCP_C_PASSIVE_OPEN message. The attached control info (an +the TCP a TCP_C_PASSIVE_OPEN message. The attached control info (a :cpp:`TcpOpenCommand`) contains the local address and port. The application can specify that it wants to handle only one connection at a -time, or multiple simultanous connections. If the :var:`fork` field is +time or multiple simultaneous connections. If the :var:`fork` field is true, it emulates the Unix accept(2) semantics: a new connection structure is created for the connection (with a new :var:`connId`), and the connection with the old connection id remains listening. If @@ -217,18 +217,18 @@ the connection with the old connection id remains listening. If original :var:`connId`), and further incoming connections will be refused by the TCP by sending an RST segment. The :var:`dataTransferMode` field in :cpp:`TcpOpenCommand` specifies whether -the application data is transmitted as C++ objects, real bytes or byte +the application data is transmitted as C++ objects, real bytes, or byte counts only. The congestion control algorithm can also be specified on a -per connection basis by setting :var:`tcpAlgorithmClass` field to the +per-connection basis by setting the :var:`tcpAlgorithmClass` field to the name of the algorithm. The application opens a connection to a remote server by sending the TCP a TCP_C_OPEN_ACTIVE command. The TCP creates a :cpp:`TcpConnection` -object an sends a SYN segment. The initial sequence number selected -according to the simulation time: 0 at time 0, and increased by 1 in -each 4\ :math:`\mu`\ s. If there is no response to the SYN segment, it -retry after 3s, 9s, 21s and 45s. After 75s a connection establishment -timeout (TCP_I_TIMEOUT) reported to the application and the connection +object and sends a SYN segment. The initial sequence number is selected +according to the simulation time: 0 at time 0, and increased by 1 each +4 µs. If there is no response to the SYN segment, it retries after 3s, +9s, 21s, and 45s. After 75s, a connection establishment +timeout (TCP_I_TIMEOUT) is reported to the application and the connection is closed. When the connection gets established, TCP sends a TCP_I_ESTABLISHED @@ -242,8 +242,8 @@ receives a TCP_I_CONNECTION_REFUSED message. .. note:: - If you do active OPEN, then send data and close before the connection - has reached ESTABLISHED, the connection will go from SYN\_SENT to CLOSED + If you do an active OPEN, then send data and close before the connection + has reached ESTABLISHED, the connection will go from SYN_SENT to CLOSED without actually sending the buffered data. This is consistent with RFC 793 but may not be what you would expect. @@ -251,7 +251,7 @@ receives a TCP_I_CONNECTION_REFUSED message. .. note:: - Handling segments with SYN+FIN bits set (esp. with data too) is + Handling segments with SYN+FIN bits set (especially with data too) is inconsistent across TCPs, so check this one if it is of importance. Sending Data @@ -261,47 +261,47 @@ The application can write data into the connection by sending a message with TCP_C_SEND kind to the TCP. The attached control info must be of type :cpp:`TCPSendCommand`. -The TCP will add the message to the *send queue*. There are three type -of send queues corresponding to the three data transfer mode. If the +The TCP will add the message to the *send queue*. There are three types +of send queues corresponding to the three data transfer modes. If the payload is transmitted as a message object, then -:cpp:`TCPMsgBasedSendQueue`; if the payload is a byte array then +:cpp:`TCPMsgBasedSendQueue`; if the payload is a byte array, then :cpp:`TCPDataStreamSendQueue`; if only the message lengths are -represented then :cpp:`TCPVirtualDataSendQueue` are the classes of send +represented, then :cpp:`TCPVirtualDataSendQueue` are the classes of send queues. The appropriate queue is created based on the value of the :par:`dataTransferMode` parameter of the Open command, no further configuration is needed. The message is handed over to the IP when there is enough room in the -windows. If Nagle’s algorithm is enabled, the TCP will collect 1 SMSS -data and sends them toghether. +window. If Nagle’s algorithm is enabled, the TCP will collect 1 SMSS +data and send them together. .. note:: - There is no way to set the PUSH and URGENT flags, when sending data. + There is no way to set the PUSH and URGENT flags when sending data. Receiving Data ~~~~~~~~~~~~~~ The TCP connection stores the incoming segments in the *receive queue*. -The receive queue also has three flavours: :cpp:`TCPMsgBasedRcvQueue`, -:cpp:`TCPDataStreamRcvQueue` and :cpp:`TCPVirtualDataRcvQueue`. The +The receive queue also has three flavors: :cpp:`TCPMsgBasedRcvQueue`, +:cpp:`TCPDataStreamRcvQueue`, and :cpp:`TCPVirtualDataRcvQueue`. The queue is created when the connection is opened according to the :var:`dataTransferMode` of the connection. Finite receive buffer size is modeled by the :par:`advertisedWindow` -parameter. If receive buffer is exhausted (by out-of-order segments) and -the payload length of a new received segment is higher than the free -receiver buffer, the new segment will be dropped. Such drops are -recorded in *tcpRcvQueueDrops* vector. +parameter. If the receive buffer is exhausted (by out-of-order segments) and +the payload length of a newly received segment is higher than the free +receive buffer, the new segment will be dropped. Such drops are +recorded in the *tcpRcvQueueDrops* vector. If the *Sequence Number* of the received segment is the next expected one, then the data is passed to the application immediately. The :fun:`recv()` call of Unix is not modeled. The data of the segment, which can be either a :cpp:`cMessage` object, a -:cpp:`ByteArray` object, or a simply byte count, is passed to the +:cpp:`ByteArray` object, or simply a byte count, is passed to the application in a message that has TCP_I_DATA kind. @@ -309,31 +309,31 @@ application in a message that has TCP_I_DATA kind. .. note:: The TCP module does not handle the segments with PUSH or URGENT - flags specially. The data of the segment passed to the application - as soon as possible, but the application can not find out if that + flags specially. The data of the segment is passed to the application + as soon as possible, but the application cannot find out if that data is urgent or pushed. RESET handling -~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^ -When an error occures at the TCP level, an RST segment is sent to the -communication partner and the connection is aborted. Such error can be: +When an error occurs at the TCP level, an RST segment is sent to the +communication partner and the connection is aborted. Such an error can be: -- arrival of a segment in CLOSED state +- arrival of a segment in CLOSED state -- an incoming segment acknowledges something not yet sent. +- an incoming segment acknowledges something not yet sent. -The receiver of the RST it will abort the connection. If the connection +The receiver of the RST will abort the connection. If the connection is not yet established, then the passive end will go back to the LISTEN -state and waits for another incoming connection instead of aborting. +state and wait for another incoming connection instead of aborting. Closing connections ~~~~~~~~~~~~~~~~~~~ When the application does not have more data to send, it closes the connection by sending a TCP_C_CLOSE command to the TCP. The TCP will -transmit all data from its buffer and in the last segment sets the FIN -flag. If the FIN is not acknowledged in time it will be retransmitted +transmit all data from its buffer and in the last segment set the FIN +flag. If the FIN is not acknowledged in time, it will be retransmitted with exponential backoff. The TCP receiving a FIN segment will notify the application that there @@ -342,7 +342,7 @@ TCP_I_PEER_CLOSED message to the application containing the connection identifier in the control info. When both parties have closed the connection, the applications receive a -TCP_I_CLOSED message and the connection object is deleted. (Actually one +TCP_I_CLOSED message, and the connection object is deleted. (Actually one of the TCPs waits for :math:`2 MSL` before deleting the connection, so it is not possible to reconnect with the same addresses and port numbers immediately.) @@ -351,23 +351,23 @@ Aborting connections ~~~~~~~~~~~~~~~~~~~~ The application can also abort the connection. This means that it does -not wait for incoming data, but drops the data associated with the -connection immediately. For this purpose the application sends a +not wait for incoming data but drops the data associated with the +connection immediately. For this purpose, the application sends a TCP_C_ABORT message specifying the connection identifier in the attached -control info. The TCP will send a RST to the communication partner and -deletes the connection object. The application should not reconnect with +control info. The TCP will send an RST to the communication partner and +delete the connection object. The application should not reconnect with the same local and remote addresses and ports within MSL (maximum -segment lifetime), because segments from the old connection might be +segment lifetime) because segments from the old connection might be accepted in the new one. Status Requests ~~~~~~~~~~~~~~~ Applications can get detailed status information about an existing -connection. For this purpose they send the TCP module a TCP_C_STATUS -message attaching an :cpp:`TcpCommand` info with the identifier of the +connection. For this purpose, they send the TCP module a TCP_C_STATUS +message attaching a :cpp:`TcpCommand` info with the identifier of the connection. The TCP will respond with a TCP_I_STATUS message with a -:cpp:`TcpStatusInfo` attachement. This control info contains the current +:cpp:`TcpStatusInfo` attachment. This control info contains the current state, local and remote addresses and ports, the initial sequence numbers, windows of the receiver and sender, etc. @@ -377,13 +377,13 @@ TCP algorithms -------------- The :cpp:`TcpAlgorithm` object controls retransmissions, congestion -control and ACK sending: delayed acks, slow start, fast retransmit, etc. -They are all extends the :cpp:`TcpAlgorithm` class. This simplifies the +control, and ACK sending: delayed ACKs, slow start, fast retransmit, etc. +They all extend the :cpp:`TcpAlgorithm` class. This simplifies the design of :cpp:`TcpConnection` and makes it a lot easier to implement -TCP variations such as Tahoe, NewReno, Vegas or LinuxTCP. +TCP variations such as Tahoe, NewReno, Vegas, or LinuxTCP. Currently implemented algorithm classes are :cpp:`TcpReno`, -:cpp:`TcpTahoe`, :cpp:`TcpNewReno`, :cpp:`TcpNoCongestionControl` and +:cpp:`TcpTahoe`, :cpp:`TcpNewReno`, :cpp:`TcpNoCongestionControl`, and :cpp:`DumbTcp`. It is also possible to add new TCP variations by implementing :cpp:`TcpAlgorithm`. @@ -396,11 +396,11 @@ OPEN) or in a module parameter. DumbTcp ~~~~~~~ -A very-very basic :cpp:`TcpAlgorithm` implementation, with hardcoded +A very basic :cpp:`TcpAlgorithm` implementation, with a hardcoded retransmission timeout (2 seconds) and no other sophistication. It can -be used to demonstrate what happened if there was no adaptive timeout -calculation, delayed acks, silly window avoidance, congestion control, -etc. Because this algorithm does not send duplicate ACKs when receives +be used to demonstrate what happens if there was no adaptive timeout +calculation, delayed ACKs, silly window avoidance, congestion control, +etc. Because this algorithm does not send duplicate ACKs when it receives out-of-order segments, it does not work well together with other algorithms. @@ -408,7 +408,7 @@ TcpBaseAlg ~~~~~~~~~~ The :cpp:`TcpBaseAlg` is the base class of the INET implementation of -Tahoe, Reno and New Reno. It implements basic TCP algorithms for +Tahoe, Reno, and NewReno. It implements basic TCP algorithms for adaptive retransmissions, persistence timers, delayed ACKs, Nagle’s algorithm, Increased Initial Window – EXCLUDING congestion control. Congestion control is implemented in subclasses. @@ -416,22 +416,22 @@ Congestion control is implemented in subclasses. Delayed ACK ^^^^^^^^^^^ -When the :par:`delayedAcksEnabled` parameter is set to , +When the :par:`delayedAcksEnabled` parameter is set to true, the :cpp:`TcpBaseAlg` applies a 200ms delay before sending ACKs. Nagle’s algorithm ^^^^^^^^^^^^^^^^^ -When the :par:`nagleEnabled` parameter is , then the algorithm does not +When the :par:`nagleEnabled` parameter is true, then the algorithm does not send small segments if there is outstanding data. See also `[subsec:trans_policies] <#subsec:trans_policies>`__. Persistence Timer ^^^^^^^^^^^^^^^^^ -The algorithm implements *Persistence Timer* (see +The algorithm implements a *Persistence Timer* (see `[subsec:flow_control] <#subsec:flow_control>`__). When a zero-sized -window is received it starts the timer with 5s timeout. If the timer +window is received, it starts the timer with a 5s timeout. If the timer expires before the window is increased, a 1-byte probe is sent. Further probes are sent after 5, 6, 12, 24, 48, 60, 60, 60, ... seconds until the window becomes positive. @@ -444,7 +444,7 @@ If the :par:`increasedIWEnabled` parameter is true, then the initial window is increased to 4380 bytes, but at least 2 SMSS and at most 4 SMSS. The congestion window is not updated afterwards; subclasses can add congestion control by redefining virtual methods of the -:cpp:`TcpBaseAlg` class. +:cpp:`TcpBaseAlg` class in their own class implementation. Duplicate ACKs ^^^^^^^^^^^^^^ @@ -456,7 +456,7 @@ the sequence space. RTO calculation ^^^^^^^^^^^^^^^ -Retransmission timeout (:math:`RTO`) is calculated according to Jacobson +Retransmission timeout (:math:`RTO`) is calculated according to Jacobson's algorithm (with :math:`\alpha=7/8`), and Karn’s modification is also applied. The initial value of the :math:`RTO` is 3s, its minimum is 1s, maximum is 240s (2 MSL). @@ -464,14 +464,14 @@ maximum is 240s (2 MSL). TCPNoCongestion ~~~~~~~~~~~~~~~ -TCP with no congestion control (i.e. congestion window kept very large). -Can be used to demonstrate effect of lack of congestion control. +TCP with no congestion control (i.e., congestion window kept very large). +Can be used to demonstrate the effect of lack of congestion control. TcpTahoe ~~~~~~~~ The :cpp:`TcpTahoe` algorithm class extends :cpp:`TcpBaseAlg` with *Slow -Start*, *Congestion Avoidance* and *Fast Retransmit* congestion control +Start*, *Congestion Avoidance*, and *Fast Retransmit* congestion control algorithms. This algorithm initiates a *Slow Start* when a packet loss is detected. @@ -479,55 +479,55 @@ Slow Start ^^^^^^^^^^ The congestion window is initially set to 1 SMSS or in case of -:par:`increasedIWEnabled` is to 4380 bytes (but no less than 2 SMSS and -no more than 4 SMSS). The window is increased on each incoming ACK by 1 +:par:`increasedIWEnabled` to 4380 bytes (but no less than 2 SMSS and +no more than 4 SMSS). The window is increased with each incoming ACK by 1 SMSS, so it is approximately doubled in each RTT. Congestion Avoidance ^^^^^^^^^^^^^^^^^^^^ -When the congestion window exceeded :math:`ssthresh`, the window is -increased by :math:`SMSS^2/cwnd` on each incoming ACK event, so it is +When the congestion window exceeds :math:`ssthresh`, the window is +increased by :math:`SMSS^2/cwnd` with each incoming ACK event, so it is approximately increased by 1 SMSS per RTT. Fast Retransmit ^^^^^^^^^^^^^^^ -When the 3rd duplicate ACK received, a packet loss is detected and the -packet is retransmitted immediately. Simultanously the :math:`ssthresh` +When the 3rd duplicate ACK is received, a packet loss is detected and the +packet is retransmitted immediately. Simultaneously, the :math:`ssthresh` variable is set to half of the :math:`cwnd` (but at least 2 SMSS) and :math:`cwnd` is set to 1 SMSS, so it enters slow start again. Retransmission timeouts are handled the same way: :math:`ssthresh` will -be :math:`cwnd/2`, :math:`cwnd` will be 1 SMSS. +be :math:`cwnd/2`, and :math:`cwnd` will be 1 SMSS. TcpReno ~~~~~~~ -The :cpp:`TcpReno` algorithm extends the behavior :cpp:`TcpTahoe` with +The :cpp:`TcpReno` algorithm extends the behavior of :cpp:`TcpTahoe` with *Fast Recovery*. This algorithm can also use the information transmitted in SACK options, which enables a much more accurate congestion control. Fast Recovery ^^^^^^^^^^^^^ -When a packet loss is detected by receiveing 3 duplicate ACKs, -:math:`ssthresh` set to half of the current window as in Tahoe. However +When a packet loss is detected by receiving 3 duplicate ACKs, +:math:`ssthresh` is set to half of the current window as in Tahoe. However, :math:`cwnd` is set to :math:`ssthresh + 3*SMSS` so it remains in congestion avoidance mode. Then it will send one new segment for each -incoming duplicate ACK trying to keep the pipe full of data. This -requires the congestion window to be inflated on each incoming duplicate -ACK; it will be deflated to :math:`ssthresh` when new data gets +incoming duplicate ACK, trying to keep the pipe full of data. This +requires the congestion window to be inflated with each incoming duplicate +ACK. It will be deflated to :math:`ssthresh` when new data gets acknowledged. -However a hard packet loss (i.e. RTO events) cause a slow start by +However, a hard packet loss (i.e., RTO events) cause a slow start by setting :math:`cwnd` to 1 SMSS. SACK congestion control ^^^^^^^^^^^^^^^^^^^^^^^ This algorithm can be used with the SACK extension. Set the -:par:`sackSupport` parameter to to enable sending and receiving *SACK* +:par:`sackSupport` parameter to true to enable sending and receiving *SACK* options. TcpNewReno @@ -537,6 +537,7 @@ This class implements the TCP variant known as New Reno. New Reno recovers more efficiently from multiple packet losses within one RTT than Reno does. -It does not exit fast-recovery phase until all data which was -out-standing at the time it entered fast-recovery is acknowledged. Thus +It does not exit the fast-recovery phase until all data which was +outstanding at the time it entered fast-recovery is acknowledged. This avoids reducing the :math:`cwnd` multiple times. + diff --git a/doc/src/developers-guide/ch-testing.rst b/doc/src/developers-guide/ch-testing.rst index 7a406e1cdf7..d5cfbe6acec 100644 --- a/doc/src/developers-guide/ch-testing.rst +++ b/doc/src/developers-guide/ch-testing.rst @@ -17,7 +17,7 @@ up the environment with: Regression Testing ------------------ -The most often used tests are the so called fingerprint tests, which are generally +The most often used tests are the so-called fingerprint tests, which are generally useful for regression testing. Fingerprint tests are a low-cost but effective tool for regression testing of simulation models during development. For more details on fingerprint testing, please refer to the `OMNeT++ manual @@ -28,7 +28,7 @@ Each test is basically a simulation scenario described by one line in a CSV file INET contains several such CSV files for different groups of tests. One CSV line describes a simulation by specifying the working directory, command line arguments, simulation time limit, expected fingerprint and test result (e.g. pass or fail), -and several user defined tags to help filtering. +and several user-defined tags to help filtering. Fingerprint tests can be run using the :command:`fingerprinttest` script found in the above folder. To run all fingerprint tests, simply run the script without @@ -49,7 +49,7 @@ Running all INET fingerprint tests takes several minutes even on a modern computer. By default, the script utilizes all available CPUs, the tests are run in parallel (non-deterministic order). -The simplest way to make the tests run faster, is to run only a subset of all +The simplest way to make the tests run faster is to run only a subset of all fingerprint tests. The script provides a filter parameter (-m) which takes a regular expression that is matched against all information of the test. @@ -64,7 +64,7 @@ For example, the following command runs all wireless tests in release mode: $ ./fingerprinttest --release -m wireless While the tests are running, the script prints some information about each test -followed by the test result. The test result is either PASS, FAIL or ERROR (plus +followed by the test result. The test result is either PASS, FAIL, or ERROR (plus some optional details): .. code-block:: shell @@ -73,7 +73,7 @@ some optional details): /examples/bgpv4/BgpCompleteTest/ -f omnetpp.ini -c config1 -r 0 ... : FAIL When testing is finished, the script also prints a short summary of the results -with the total number of tests, failures and errors: +with the total number of tests, failures, and errors: .. code-block:: shell @@ -90,22 +90,22 @@ tests, and one for the test which couldn't finish without an error. The updated file can be used to overwrite the original CSV file to accept the new fingerprints. Usually, when a simulation model is being developed, the fingerprint tests should -be run every now and then, to make sure there are no regressions (i.e. all tests +be run every now and then to make sure there are no regressions (i.e. all tests run with the expected result). How often tests should be run depends on the kind -of development, tests may be run from several times a day to a few times a week. +of development; tests may be run from several times a day to a few times a week. For example, if a completely new simulation model is developed with new examples, then the new fingerprint tests can be run as late as when the first version is pushed into the repository. In contrast, during an extensive model refactoring, -it's adivsable to run the affected tests more often (e.g. after each small step). -Running the tests more often helps avoiding getting into a situation where it's -difficult to tell if the new fingerprints is acceptable or not. +it's advisable to run the affected tests more often (e.g. after each small step). +Running the tests more often helps avoid getting into a situation where it's +difficult to tell if the new fingerprints are acceptable or not. In any case, certain correct changes in the simulation model break fingerprint tests. When this happens, there are two ways to validate the changes: - One is when the changes are further divided until the smallest set of changes - are found, which still break fingerprints. In this case, this set is carefully + is found, which still break fingerprints. In this case, this set is carefully reviewed (potentially by multiple people), and if it is found to be correct, then the fingerprint changes are simply accepted. @@ -117,11 +117,11 @@ tests. When this happens, there are two ways to validate the changes: With this method, the fingerprint tests must be re-run before the changes are applied using the modified fingerprint calculation. The updated fingerprint CSV files must be used to run the fingerprint tests after applying the changes. - This method is often time consuming, but may be worth the efforts for complex - changes, because it allows having a far greater confidence in correctness. + This method is often time-consuming but may be worth the effort for complex + changes because it allows having far greater confidence in correctness. -For a simple example, a timing change which neither changes the order of events -nor where the events happen, can be easily validated by changing the fingerprint +For a simple example, a timing change that neither changes the order of events +nor where the events happen can be easily validated by changing the fingerprint and removing time from the ingredients (default is tplx) as follows: .. code-block:: shell @@ -132,7 +132,7 @@ Another common example is when a submodule is renamed. Since the default fingerp ingredients contain the full module path of all events, this change will break fingerprint tests. If the module is not optional or not accessed by other modules using its name, then removing the module path from the fingerprint ingredients -(i.e. using tlx) can be used to validate this change. +(i.e., using tlx) can be used to validate this change. For a more complicated example, when the IEEE 802.11 MAC (very complex) model is refactored to a large extent, then it's really difficult to validate the changes. @@ -149,8 +149,8 @@ IEEE 802.11 MAC models: INET uses continuous integration on Github. Fingerprint and other tests are run automatically for changes on the master and integration branches. Moreover, all submitted pull requests are automatically tested the same way. The result of the -test suite is clearly marked on the pull request with check mark or a red cross. +test suite is clearly marked on the pull request with a check mark or a red cross. In general, contributors are expected to take care of not breaking the fingerprint -tests. In case of a necessary fingerprint change, the CSV files should be updated -in separate patches. +tests. In the case of a necessary fingerprint change, the CSV files should be updated +in separate patches. \ No newline at end of file diff --git a/doc/src/developers-guide/ch-udp.rst b/doc/src/developers-guide/ch-udp.rst index 6d7f80e92a0..7c57e60572c 100644 --- a/doc/src/developers-guide/ch-udp.rst +++ b/doc/src/developers-guide/ch-udp.rst @@ -8,50 +8,50 @@ The UDP Model The UDP module -------------- -The state of the sockets are stored within the UDP module and the -application can configure the socket by sending command messages to the +The states of the sockets are stored within the UDP module and +the application can configure the socket by sending command messages to the UDP module. These command messages are distinguished by their kind and the type of their control info. The control info identifies the socket and holds the parameters of the command. Applications don’t have to send messages directly to the UDP module, as they can use the :cpp:`UdpSocket` utility class, which encapsulates the -messaging and provides a socket like interface to applications. +messaging and provides a socket-like interface to applications. Sending UDP datagrams ~~~~~~~~~~~~~~~~~~~~~ -If the application want to send datagrams, it optionally can connect to -the destination. It does this be sending a message with UDP_C_CONNECT +If the application wants to send datagrams, it optionally can connect to +the destination. It does this by sending a message with UDP_C_CONNECT kind and :cpp:`UdpConnectCommand` control info containing the remote -address and port of the connection. The UDP protocol is in fact +address and port of the connection. The UDP protocol is, in fact, connectionless, so it does not send any packets as a result of the connect call. When the UDP module receives the connect request, it -simply remembers the destination address and port and use it as default +simply remembers the destination address and port and uses it as the default destination for later sends. The application can send several connect commands to the same socket. -For sending an UDP packet, the application should attach an -:cpp:`UDPSendCommand` control info to the packet, and send it to +For sending a UDP packet, the application should attach an +:cpp:`UDPSendCommand` control info to the packet and send it to :ned:`Udp`. The control info may contain the destination address and port. If the destination address or port is unspecified in the control -info then the packet is sent to the connected target. +info, then the packet is sent to the connected target. The :ned:`Udp` module encapsulates the application’s packet into an -:msg:`UdpHeader`, creates an appropriate IP control info and send it +:msg:`UdpHeader`, creates an appropriate IP control info, and sends it over ipOut or ipv6Out depending on the destination address. The destination address can be the IPv4 local broadcast address (255.255.255.255) or a multicast address. Before sending broadcast messages, the socket must be configured for broadcasting. This is done -by sending an message to the UDP module. The message kind is +by sending a message to the UDP module. The message kind is UDP_C_SETOPTION and its control info (an :cpp:`UdpSetBroadcastCommand`) tells if the broadcast is enabled. You can limit the multicast to the local network by setting the TTL of the IP packets to 1. The TTL can be -configured per socket, by sending a message to the UDP with an +configured per socket by sending a message to the UDP with an :cpp:`UDPSetTimeToLive` control info containing the value. If the node has multiple interfaces, the application can choose which is used for -multicast messages. This is also a socket option, the id of the +multicast messages. This is also a socket option; the ID of the interface (as registered in the interface table) can be given in an :cpp:`UdpSetMulticastInterfaceCommand` control info. @@ -72,48 +72,48 @@ packet. After the application finished using a socket, it should close it by sending a message UDP_C_CLOSE kind and :cpp:`UdpCloseCommand` control info. The control info contains only the socket identifier. This command -frees the resources associated with the given socket, for example its +frees the resources associated with the given socket, for example, its socket identifier or bound address/port. Receiving UDP datagrams ~~~~~~~~~~~~~~~~~~~~~~~ -Before receiving UDP datagrams applications should first “bind” to the +Before receiving UDP datagrams, applications should first “bind” to the given UDP port. This can be done by sending a message with message kind UDP_C_BIND attached with an :cpp:`UdpBindCommand` control info. The control info contains the socket identifier and the local address and -port the application want to receive UDP packets. Both the address and -port is optional. If the address is unspecified, than the UDP packets -with any destination address is passed to the application. If the port -is -1, then an unused port is selected automatically by the UDP module. +port the application wants to receive UDP packets. Both the address and +port are optional. If the address is unspecified, then the UDP packets +with any destination address are passed to the application. If the port +is -1, then an unused port is automatically selected by the UDP module. The localAddress/localPort combination must be unique. When a packet arrives from the network, first its error bit is checked. -Erroneous messages are dropped by the UDP component. Otherwise the +Erroneous messages are dropped by the UDP component. Otherwise, the application bound to the destination port is looked up, and the -decapsulated packet passed to it. If no application is bound to the +decapsulated packet is passed to it. If no application is bound to the destination port, an ICMP error is sent to the source of the packet. If the socket is connected, then only those packets are delivered to the -application, that received from the connected remote address and port. +application that received from the connected remote address and port. -The control info of the decapsulated packet is an +The control info of the decapsulated packet is a :cpp:`UDPDataIndication` and contains information about the source and destination address/port, the TTL, and the identifier of the interface card on which the packet was received. -The applications are bound to the unspecified local address, then they +The applications are bound to the unspecified local address; then, they receive any packets targeted to their port. UDP also supports multicast -and broadcast addresses; if they are used as destination address, all -nodes in the multicast group or subnet receives the packet. The socket +and broadcast addresses; if they are used as the destination address, all +nodes in the multicast group or subnet receive the packet. The socket receives the broadcast packets only if it is configured for broadcast. -To receive multicast messages, the socket must join to the group of the -multicast address. This is done be sending the UDP module an +To receive multicast messages, the socket must join the group of the +multicast address. This is done by sending the UDP module an UDP_C_SETOPTION message with :cpp:`UdpJoinMulticastGroupsCommand` control info. The control info specifies the multicast addresses and the -interface identifiers. If the interface identifier is given only those +interface identifiers. If the interface identifier is given, only those multicast packets are received that arrived at that interface. The socket can stop receiving multicast messages if it leaves the multicast -group. For this purpose the application should send the UDP another +group. For this purpose, the application should send the UDP another UDP_C_SETOPTION message in their control info (:cpp:`UdpLeaveMulticastGroupsCommand`) specifying the multicast addresses of the groups. @@ -123,12 +123,13 @@ Signals The :ned:`Udp` module emits the following signals: -- when an UDP packet sent to the IP, the packet +- when an UDP packet is sent to the IP, the packet -- when an UDP packet received from the IP, the packet +- when an UDP packet is received from the IP, the packet -- when a packet passed up to the application, the packet +- when a packet is passed up to the application, the packet -- when an undeliverable UDP packet received, the packet +- when an undeliverable UDP packet is received, the packet + +- when an erroneous UDP packet is received, the packet -- when an erronous UDP packet received, the packet diff --git a/doc/src/developers-guide/ch-usage.rst b/doc/src/developers-guide/ch-usage.rst index fc8c93da60e..885e1a27c4d 100644 --- a/doc/src/developers-guide/ch-usage.rst +++ b/doc/src/developers-guide/ch-usage.rst @@ -10,10 +10,10 @@ Getting Started Introduction ------------ -where to put the source files: you can copy and modify the INET -framework (fork it) in the hope that you’ll contribute back the changes; -or you can develop in a separate project (create new project in the IDE; -mark INET as referenced project) +Where to put the source files: You can copy and modify the INET +framework (fork it) in the hope that you'll contribute back the changes; +or you can develop in a separate project (create a new project in the IDE; +mark INET as a referenced project). .. _dg:cha:gettingstarted:contributing-to-inet: @@ -22,26 +22,26 @@ Contributing to INET Workflow: -Fork on Github. +1. Fork on GitHub. -Check out the INET project from GitHub, and import it into the OMNeT++ +2. Check out the INET project from GitHub, and import it into the OMNeT++ IDE. -Develop. +3. Develop. -Submit pull requests. +4. Submit pull requests. .. _dg:cha:gettingstarted:setting-up-inet-based: Setting Up a New INET-Based Project ----------------------------------- -Create new project in the IDE. +Create a new project in the IDE. -NED and source files in the same folder; examples under examples/; etc. +Keep NED and source files in the same folder; examples under examples/; etc. -Set INET as referenced project. +Set INET as a referenced project. Set up version control (git, GitHub). -Develop. +Develop. \ No newline at end of file diff --git a/doc/src/developers-guide/index.rst b/doc/src/developers-guide/index.rst index 07c18cf86f3..26e81e1fd51 100644 --- a/doc/src/developers-guide/index.rst +++ b/doc/src/developers-guide/index.rst @@ -4,7 +4,7 @@ Release: |release| .. only:: html - This manual is written for developers who intend to extend INET with new components, written in C++. + This manual is written for developers who intend to extend INET with new components written in C++. Table of Contents diff --git a/doc/src/migration-guide/index.rst b/doc/src/migration-guide/index.rst index b2c629bac86..f0bcb5784cd 100644 --- a/doc/src/migration-guide/index.rst +++ b/doc/src/migration-guide/index.rst @@ -9,7 +9,7 @@ Release: |release| Network Node Architecture ------------------------- -The internal structure of network nodes has been changed considerably. With the +The internal structure of network nodes has been considerably changed. With the new architecture, applications can directly talk to any protocol down to the link layer, and protocols don't have to deal with dispatching to other protocols. @@ -32,7 +32,7 @@ and commands to the intended receiver module based on various tags: The :ned:`MessageDispatcher` is also used inside network layer compound modules such as the :ned:`Ipv4NetworkLayer`. This usage is not accidental, it solves dispatching -ARP, ICMP and IPv4 packets to the appropriate protocol modules. +ARP, ICMP, and IPv4 packets to the appropriate protocol modules. .. _mg:sec:migrationguide:extendingprotocols: @@ -41,8 +41,8 @@ Extending the Known Protocols Internally, protocols first must be added to the list of known protocols in the Protocol class before they can be used. Some protocols (such as IP) have a mapping -between protocol specific integer identifiers and actual protocols. These mapping -should be created as a :cpp:`ProtocolGroup`. Here are some examples how to do this: +between protocol-specific integer identifiers and actual protocols. These mappings +should be created as a :cpp:`ProtocolGroup`. Here are some examples of how to do this: .. code-block:: c++ @@ -62,7 +62,7 @@ Registering Protocols for Dispatching Modules must register supported protocols with the :ned:`MessageDispatcher` to operate properly. This is done by calling ``inet::registerProtocol(...)`` for each supported protocol on each gate in ``initialize()``. Interfaces (usually MAC protocols modules) -must also register with calling ``inet::registerInterface(...)`` for the corresponding +must also register by calling ``inet::registerInterface(...)`` for the corresponding :cpp:`NetworkInterface` and gate in ``initialize()``. On the other hand, sockets are learned by the :ned:`MessageDispatcher` automatically on the fly. @@ -73,8 +73,8 @@ Attaching Tags for Dispatching When a protocol sends a packet or command to another protocol or interface, it must attach the appropriate tag for the :ned:`MessageDispatcher`. The dispatcher uses -the attached tags to lookup the intended receiver in its registration list and -forwards the message on the appropriate gate. Here are some examples how to do +the attached tags to look up the intended receiver in its registration list and +forwards the message on the appropriate gate. Here are some examples of how to do this: .. code-block:: c++ @@ -93,9 +93,9 @@ into a single application vector (``app``). The merged vector can contain all ki of applications, which are free to use any protocol they see fit. This change requires updating the configuration of applications in INI files. In -the simplest case this can be done by simply replacing the application vector +the simplest case, this can be done by simply replacing the application vector names. If the example uses more than one kind of application in a single network -node then the submodule vector indexes must be also updated. +node, then the submodule vector indexes must also be updated. For example, the existing configuration: @@ -142,14 +142,14 @@ Some notable tag examples: - :cpp:`L3AddressReq`, :cpp:`L3AddressInd` specifies source and destination network addresses - :cpp:`SignalPowerReq`, :cpp:`SignalPowerInd` specifies send and receive signal power - :cpp:`DispatchProtocolReq`, :cpp:`DispatchProtocolInd` specifies intended receiver protocol -- :cpp:`PacketProtcolTag` specifies protocol of the packet +- :cpp:`PacketProtcolTag` specifies the protocol of the packet Tags come in three flavors: -- requests (are called ``SomethingReq``) carry information from higher layer to lower layer protocols -- indications (are called ``SomethingInd``) carry information from lower layer to higher layer protocols -- plain tags (are called ``SomethingTag``) contain some meta information -- base classes (are called ``SomethingTagBase``) must not be attached to packets +- requests (called ``SomethingReq``) carry information from a higher layer to lower layer protocols +- indications (called ``SomethingInd``) carry information from a lower layer to higher layer protocols +- plain tags (called ``SomethingTag``) contain some meta information +- base classes (called ``SomethingTagBase``) must not be attached to packets .. _mg:sec:migrationguide:controlinfo: @@ -158,13 +158,13 @@ Splitting Control Infos When migrating a protocol, the old control info data structures, which were attached to packets, must be replaced with a set of tags. Implementors should -use already existing tags if possible, otherwise they are free to create new +use already existing tags if possible; otherwise, they are free to create new ones as they see fit. -Any code that sets, reads or removes control info objects of packets must be -replaced with code that adds, reads or removes the appropriate tags. +Any code that sets, reads, or removes control info objects of packets must be +replaced with code that adds, reads, or removes the appropriate tags. -Setting control info on commands need not be changed, but may be adapted for +Setting control info on commands need not be changed but may be adapted for consistency. .. _mg:sec:migrationguide:communicating: @@ -179,9 +179,9 @@ protocols are free to ignore any tag they wish based on their configuration and state. When a packet is reused for any purpose (e.g. forwarding, loopback interface, -echo application), most likely all tags on the packet should be removed. The +echo application), most likely, all tags on the packet should be removed. The reason is that the implementor can never be sure what kind of tags are attached -to a packet, and what unintended effects those tags will have at a later stage +to a packet and what unintended effects those tags will have at a later stage in some protocol. Finally, it's important to note that tags are not transmitted from one network @@ -196,13 +196,13 @@ Determining the Protocol of Packets ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ With the new packet API, packets can no longer be differentiated using the C++ -dynamic_cast operator with the desired type. The reason is that all packets are +`dynamic_cast` operator with the desired type. The reason is that all packets are instances of the :cpp:`Packet` class. In fact, this is quite understandable if one views packets as a sequence of bytes. Any sequence of bytes, no matter how it is represented by a :cpp:`Packet`, can be interpreted by any protocol, even if the packet was not intended to be processed by that protocol. Therefore, before a protocol is sending out a packet using any of its gates, it must attach a -:cpp:`PacketProtocolTag` to it. Here is an example how to do this: +:cpp:`PacketProtocolTag` to it. Here is an example of how to do this: .. code-block:: c++ @@ -214,10 +214,10 @@ Packet API ---------- INET provides a new packet API that supports efficient construction, sharing, -duplication, encapsulation, aggregation, fragmentation and serialization. The -data structure also supports dual representation by default. That is data can -be accessed as raw bytes and also as field based classes. Internally, packets -store their data in different kind of chunks. +duplication, encapsulation, aggregation, fragmentation, and serialization. The +data structure also supports dual representation by default. That is, data can +be accessed as raw bytes and also as field-based classes. Internally, packets +store their data in different kinds of chunks. The new API uses the following classes at the chunk level: @@ -248,11 +248,11 @@ The new API uses the following classes for serialization: Protocol Header Classes ~~~~~~~~~~~~~~~~~~~~~~~ -The most substantial change regarding protocols is that protocol specific headers +The most substantial change regarding protocols is that protocol-specific headers (or messages) are no longer subclasses of :cpp:`cPacket`. Protocol headers subclass the :cpp:`Chunk` class instead, and they are simply added to Packets during processing. Variable references to :cpp:`Chunk` objects must use shared pointers (``Ptr``) -types. Here is an example how to do this: +types. Here is an example of how to do this: .. code-block:: c++ @@ -265,9 +265,9 @@ types. Here is an example how to do this: Sometimes processing in a protocol module requires multiple utility functions and classes. Some functions may need the packet and the protocol header at the -same time. Only passing the protocol header is not sufficient, because due to -the shared nature of chunks they don't have an owner packet. Only passing the -packet requires the called function to peek the protocol header which might +same time. Only passing the protocol header is not sufficient because due to +the shared nature of chunks, they don't have an owner packet. Only passing the +packet requires the called function to peek at the protocol header, which might unnecessarily slow down execution. In such cases, it is a good idea to pass the packet and the protocol header in separate parameters. Whether this is desirable or not highly depends on the complexity of the protocol and the organization of @@ -278,22 +278,22 @@ its implementation. Immutability of Chunks ~~~~~~~~~~~~~~~~~~~~~~ -Another important to note difficulty is that chunks can only be added to packets +Another important difficulty to note is that chunks can only be added to packets if they are immutable. This requirement comes from the fact that packets support peeking into their data regardless of how the data is represented. The result of -peek operations are required to stay consistent with the original content of the +peek operations is required to stay consistent with the original content of the packet. Moreover, the content of packets can be arbitrarily shared with other -packets which may be potentially present in different network nodes. Unfortunately +packets that may be potentially present in different network nodes. Unfortunately, these properties forbid arbitrary changes once the chunk has been added to the -packet. Of course internally, packets do their best to reuse any chunk data +packet. Of course, internally, packets do their best to reuse any chunk data structure if possible. -When the need arises to change the contents of the packet such as forwarding a +When the need arises to change the contents of the packet, such as forwarding a packet in a network protocol, the best thing to do is the following. Remove the part that is to be updated, create a mutable copy, update it according to the protocol, and add the updated part back to the packet. In fact, this is like saying that forwarding a packet is the same as sending out another packet that -shares some structure with the received one. Here is an example how to do this: +shares some structure with the received one. Here is an example of how to do this: .. code-block:: c++ @@ -308,8 +308,8 @@ Serializing Packets The old packet serializer classes have been replaced with new classes subclassing from the :cpp:`ChunkSerializer` class. The old serializers used to not only serialize -the packet they were responsible for but they recursed into the encapsulated packet. -This is no longer the case, serializers are only responsible for the corresponding +the packet they were responsible for but they also recursed into the encapsulated packet. +This is no longer the case as serializers are only responsible for the corresponding chunk that they handle. Actually transforming a packet to a sequence of bytes doesn't involve directly @@ -323,10 +323,10 @@ a sequence of bytes is as simple as follows: packet->peekAllBytes(); // shorthand This property of the API greatly simplifies code that serializes packets into -trace files such as PCAP. Finally, the new API allows testing the protocol +trace files, such as PCAP. Finally, the new API allows testing the protocol implementations for proper emulation support. Configuring all network interfaces to send out packets (in place of the original packets) which contain a single -:cpp:`BytesChunk` only, is easy to do. At the receiver modules, there's no need to change +:cpp:`BytesChunk` only is easy to do. At the receiver modules, there's no need to change anything in the protocol implementations. The reason being that the packet API transparently handles the dual representation, and it converts the sequence of bytes to the requested chunk types as needed. @@ -337,13 +337,13 @@ Handling Checksums ~~~~~~~~~~~~~~~~~~ The old serializer classes used to compute and verify checksums on the fly. This -caused some confusion especially with the proper support of pseudo headers. With -the new API this is no longer the case. The new serializers are only responsible +caused some confusion, especially with the proper support of pseudo headers. With +the new API, this is no longer the case. The new serializers are only responsible for transforming from one representation (sequence of bytes) to another (fields), and vice versa. Computing and verifying checksums is up to the protocol implementations, and it is independent of the actual representation of the header. In general, protocols -should have parameters to declare the checksum correct/incorrect or actually -compute and verify it. Of course, for emulation one should enable computing and -verifying checksums. +should have parameters to declare the checksum correct/incorrect or to actually +compute and verify it. Of course, for emulation, one should enable computing and +verifying checksums. \ No newline at end of file diff --git a/doc/src/users-guide/ch-80211.rst b/doc/src/users-guide/ch-80211.rst index 368b7bfacb2..991f218a1f0 100644 --- a/doc/src/users-guide/ch-80211.rst +++ b/doc/src/users-guide/ch-80211.rst @@ -10,17 +10,17 @@ Overview IEEE 802.11 a.k.a. WiFi is the most widely used and universal wireless networking standard. Specifications are updated every few years, adding -more features and ever increasing bit rates. +more features and ever-increasing bit rates. -In INET, nodes become WiFi-enabled by adding a :ned:`Ieee80211Interface` +In INET, nodes become WiFi-enabled by adding an :ned:`Ieee80211Interface` to them. (As mentioned earlier, :ned:`WirelessHost` and :ned:`AdhocHost` already contain one in their default configuration.) APs are represented with the :ned:`AccessPoint` node type. WiFi networks require a matching transmission medium module to be present in the network, which is -usually a :ned:`Ieee80211ScalarRadioMedium`. +usually an :ned:`Ieee80211ScalarRadioMedium`. -Operation mode (infrastructure vs ad hoc) is determined by the -ingredients of the wireless interface. :ned:`Ieee80211Interface` has the +The operation mode (infrastructure vs ad hoc) is determined by the +ingredients of the wireless interface. The :ned:`Ieee80211Interface` has the following submodules (incomplete list): #. *management*: performs association/disassociation with access points, @@ -45,12 +45,12 @@ their role and level of detail: - :ned:`Ieee80211MgmtAp`, :ned:`Ieee80211MgmtApSimplified`: for access points -The “simplified” ones assume that stations are statically associated to +The "simplified" ones assume that stations are statically associated with an access point for the entire duration of the simulation (the scan-authenticate-associate process is not simulated), so they cannot be used e.g. in experiments involving handover. -:ned:`Ieee80211MgmtSta` is does not take any action by itself, it +The :ned:`Ieee80211MgmtSta` does not take any action by itself, it requires an agent (:ned:`Ieee80211AgentSta` or a custom one) to initiate actions. @@ -61,59 +61,84 @@ The following sections examine the above components. MAC --- -The :ned:`Ieee80211Mac` module type represents the IEEE 802.11 MAC. The structure of the -implementation closely follows the architecture described in the standard, IEEE 802.11-2012 Part -11: Wireless LAN Medium Access Control (MAC) and Physical Layer (PHY) -Specifications. +The :ned:`Ieee80211Mac` module type represents the IEEE 802.11 MAC. The +structure of the implementation closely follows the architecture described in +the standard, IEEE 802.11-2012 Part 11: Wireless LAN Medium Access Control (MAC) +and Physical Layer (PHY) Specifications. -:ned:`Ieee80211Mac` performs transmission of frames according to the +The :ned:`Ieee80211Mac` performs transmission of frames according to the CSMA/CA protocol. It receives data and management frames from the upper layers, and transmits them. The :ned:`Ieee80211Mac` was designed to be modular to facilitate -experimenting with new policies, features and algorithms within the MAC +experimenting with new policies, features, and algorithms within the MAC layer. Users can easily replace individual components with their own -implementations. Policies, which most likely to be experimented with, +implementations. Policies, which are most likely to be experimented with, are extracted into their own modules. -The new model also separates the following components in the 802.11 standard into modules: +The new model also separates the following components in the 802.11 standard +into modules: -- Coordination function: :ned:`Dcf`, :ned:`Hcf`. The coordination functions control the medium access as specified by the standard. +- Coordination function: :ned:`Dcf`, :ned:`Hcf`. The coordination functions + control the medium access as specified by the standard. - Channel access method as specified by the standard: :ned:`Edca` -- Channel access function: :ned:`Edcaf`, :ned:`Dcaf`. The channel access function controls channel ownership, etc. +- Channel access function: :ned:`Edcaf`, :ned:`Dcaf`. The channel access + function controls channel ownership, etc. -- MAC data services: :ned:`OriginatorMacDataService`, :ned:`RecipientMacDataService`, :ned:`OriginatorQosMacDataService`, :ned:`RecipientQosMacDataService`. - The MAC data services are implemented as compound modules, which combine functions related to transforming data frames (sequence numbering, duplicate removal, frame reordering, fragmentation, aggregation). +- MAC data services: :ned:`OriginatorMacDataService`, + :ned:`RecipientMacDataService`, :ned:`OriginatorQosMacDataService`, + :ned:`RecipientQosMacDataService`. The MAC data services are implemented as + compound modules, which combine functions related to transforming data frames + (sequence numbering, duplicate removal, frame reordering, fragmentation, + aggregation). -- Aggregation and deaggregation (C++ class in MAC data services): These classes implement aggregation and deaggregation according to the policy modules (see below). +- Aggregation and deaggregation (C++ class in MAC data services): These classes + implement aggregation and deaggregation according to the policy modules (see + below). -- Fragmentation and defragmentation (C++ classes in MAC data services): These classes carry out the task of fragmentation and defragmentation according to the policy modules (see below). +- Fragmentation and defragmentation (C++ classes in MAC data services): These + classes carry out the task of fragmentation and defragmentation according to + the policy modules (see below). -- Block ACK agreements and frame reordering (C++ classes): These classes carry out the task according to the policy modules (see below). +- Block ACK agreements and frame reordering (C++ classes): These classes carry + out the task according to the policy modules (see below). -- Frame exchange sequences (implemented as C++ classes in coordination functions, like :ned:`Hcf`): These classes strictly follow the standard specifying the valid frame sequences. +- Frame exchange sequences (implemented as C++ classes in coordination + functions, like :ned:`Hcf`): These classes strictly follow the standard + specifying the valid frame sequences. -- TXOP procedure (:ned:`TxopProcedure`): This module implements the transmission opportunity behavior of the standard. +- TXOP procedure (:ned:`TxopProcedure`): This module implements the + transmission opportunity behavior of the standard. -- Duplicate removal (C++ class in RecipientMacDataService): This class removes duplicate received frames based on sequence numbers. +- Duplicate removal (C++ class in RecipientMacDataService): This class removes + duplicate received frames based on sequence numbers. -- Rate selection: :ned:`QosRateSelection`. This module controls data rate for all kind of frames, including management and control frames. +- Rate selection: :ned:`QosRateSelection`. This module controls the data rate + for all kinds of frames, including management and control frames. -- Rate control: :ned:`AarfRateControl`, :ned:`OnoeRateControl`. These modules determine the optimal data rate for data frames. +- Rate control: :ned:`AarfRateControl`, :ned:`OnoeRateControl`. These modules + determine the optimal data rate for data frames. -- Protection mechanism: :ned:`OriginatorProtectionMechanism`. This module provides channel allocation for frame exchange sequences. +- Protection mechanism: :ned:`OriginatorProtectionMechanism`. This module + provides channel allocation for frame exchange sequences. -- Recovery procedure: :ned:`NonQosRecoveryProcedure`, :ned:`QosRecoveryProcedure`. These modules determine what to do in case of frame exchange failure. +- Recovery procedure: :ned:`NonQosRecoveryProcedure`, + :ned:`QosRecoveryProcedure`. These modules determine what to do in case of + frame exchange failure. -- Contention: :ned:`Contention`. The contention module implements contention-based channel access, using defer, backoff, etc. +- Contention: :ned:`Contention`. The contention module implements + contention-based channel access, using defer, backoff, etc. -- :ned:`PendingQueue`: This module is a queue containing frames received from higher layers, waiting for transmission unchanged. +- :ned:`PendingQueue`: This module is a queue containing frames received from + higher layers, waiting for transmission unchanged. -- :ned:`InProgressFrames`: This modules is a queue containing frames waiting for transmission already processed by the MAC data service. +- :ned:`InProgressFrames`: This modules is a queue containing frames waiting + for transmission already processed by the MAC data service. -- TX/RX (:ned:`Tx`, :ned:`Rx`). Responsible for simple frame transmission/reception. +- TX/RX (:ned:`Tx`, :ned:`Rx`). Responsible for simple frame + transmission/reception. The MAC model has the following replaceable built-in policy submodules by default: @@ -129,15 +154,23 @@ The MAC model has the following replaceable built-in policy submodules by defaul .. , with the default modules in parentheses: -- ACK policy (e.g. :ned:`OriginatorAckPolicy`, :ned:`RecipientAckPolicy`): controls what kind of acknowledgement is used per-frame (none, normal, block-ack) +- ACK policy (e.g. :ned:`OriginatorAckPolicy`, :ned:`RecipientAckPolicy`): + controls what kind of acknowledgment is used per-frame (none, normal, + block-ack) -- RTS/CTS policy (e.g. :ned:`RtsPolicy`, :ned:`CtsPolicy`): determines which frames are protected by the RTS/CTS mechanism +- RTS/CTS policy (e.g. :ned:`RtsPolicy`, :ned:`CtsPolicy`): determines which + frames are protected by the RTS/CTS mechanism -- Originator and recipient block ACK agreement policies (e.g. :ned:`OriginatorBlockAckAgreementPolicy`, :ned:`RecipientBlockAckAgreementPolicy`): determine when and what kind of agreements are made +- Originator and recipient block ACK agreement policies (e.g. + :ned:`OriginatorBlockAckAgreementPolicy`, + :ned:`RecipientBlockAckAgreementPolicy`): determine when and what kind of + agreements are made -- MSDU aggregation policy (e.g. :ned:`BasicMsduAggregationPolicy`): controls when and which frames are aggregated into an A-MSDU +- MSDU aggregation policy (e.g. :ned:`BasicMsduAggregationPolicy`): controls + when and which frames are aggregated into an A-MSDU -- Fragmentation policy (e.g. :ned:`BasicFragmentationPolicy`): controls when and how fragmentation happens +- Fragmentation policy (e.g. :ned:`BasicFragmentationPolicy`): controls when + and how fragmentation happens .. For example, a lot of these modules are located in the *hcf* submodule of the MAC: @@ -151,7 +184,7 @@ Physical Layer *The physical layer* modules (:ned:`Ieee80211Radio`) deal with modeling transmission and reception of frames. They model the characteristics of -the radio channel, and determine if a frame was received correctly (that +the radio channel and determine if a frame was received correctly (that is, it did not suffer bit errors due to low signal power or interference in the radio channel). Frames received correctly are passed up to the MAC. @@ -174,10 +207,10 @@ Management *The management layer* exchanges management frames via the MAC with its peer management entities in other STAs and APs. Beacon, Probe -Request/Response, Authentication, Association Request/Response etc -frames are generated and interpreted by management entities, and +Request/Response, Authentication, Association Request/Response, etc +frames are generated and interpreted by management entities and transmitted/received via the MAC layer. During scanning, it is the -management entity that periodically switches channels, and collects +management entity that periodically switches channels and collects information from received beacons and probe responses. The management layer has several implementations which differ in their @@ -194,16 +227,16 @@ Agent ----- The agent is what instructs the management layer to perform scanning, -authentication and association. The management layer itself just carries -out these commands by performing the scanning, authentication and -association procedures, and reports back the results to the agent. +authentication, and association. The management layer itself just carries +out these commands by performing the scanning, authentication, and +association procedures and reports back the results to the agent. The agent component is currently only needed with the :ned:`Ieee80211MgmtSta` module. The management entities in other NIC variants do not have as much freedom as to need an agent to control them. -:ned:`Ieee80211MgmtSta` requires a :ned:`Ieee80211AgentSta` or a custom +:ned:`Ieee80211MgmtSta` requires an :ned:`Ieee80211AgentSta` or a custom agent. By modifying or replacing the agent, one can alter the dynamic -behavior of STAs in the network, for example implement different -handover strategies. +behavior of STAs in the network, for example, implement different +handover strategies. \ No newline at end of file diff --git a/doc/src/users-guide/ch-802154.rst b/doc/src/users-guide/ch-802154.rst index 73dc0c22abf..087de29527b 100644 --- a/doc/src/users-guide/ch-802154.rst +++ b/doc/src/users-guide/ch-802154.rst @@ -8,21 +8,21 @@ The 802.15.4 Model Overview -------- -IEEE 802.15.4 is a technical standard which defines the operation of -low-rate wireless personal area networks (LR-WPANs). IEEE 802.15.4 was -designed for data rates of 250 kbit/s or lower, in order to achieve long -battery life (months or even years) and very low complexity. The -standard specifies the physical layer and media access control. - -IEEE 802.15.4 is the basis for the :protocol:`ZigBee`, -:protocol:`ISA100.11a`, :protocol:`WirelessHART`, :protocol:`MiWi`, -:protocol:`SNAP`,and the :protocol:`Thread` specifications, each of -which further extends the standard by developing the upper layers which -are not defined in IEEE 802.15.4. Alternatively, it can be used with -:protocol:`6LoWPAN`, the technology used to deliver IPv6 over WPANs, to -define the upper layers. (Thread is also 6LoWPAN-based.) - -The INET Framework contains a basic implementation of IEEE 802.15.4 +IEEE 802.15.4 is a technical standard that defines the operation of low-rate +wireless personal area networks (LR-WPANs). IEEE 802.15.4 was designed for data +rates of 250 kbit/s or lower to achieve long battery life (months or even years) +and very low complexity. The standard specifies the physical layer and media +access control. + +IEEE 802.15.4 is the basis for the :protocol:`ZigBee`, :protocol:`ISA100.11a`, +:protocol:`WirelessHART`, :protocol:`MiWi`, :protocol:`SNAP`, and the +:protocol:`Thread` specifications, each of which further extends the standard by +developing the upper layers that are not defined in IEEE 802.15.4. +Alternatively, it can be used with :protocol:`6LoWPAN`, the technology used to +deliver IPv6 over WPANs, to define the upper layers. (Thread is also +6LoWPAN-based.) + +The INET Framework contains a basic implementation of the IEEE 802.15.4 protocol. .. _ug:sec:802154:network-interfaces: @@ -32,20 +32,16 @@ Network Interfaces There are two network interfaces that differ in the type of radio: -- :ned:`Ieee802154NarrowbandInterface` is for use with narrowband - radios - -- :ned:`Ieee802154UwbIrInterface` is for use with the UWB-IR radio - -To create a wireless node with a 802.15.4 interface, use a node type -that has a wireless interface, and set the interface type to the -appropriate type. For example, :ned:`WirelessHost` is a node type which -is preconfigured to have one wireless interface, ``wlan[0]``. -``wlan[0]`` is of parametric type, so if you build the network from -:ned:`WirelessHost` nodes, you can configure all of them to use 802.15.4 -with the following line in the ini file: +- :ned:`Ieee802154NarrowbandInterface` is for use with narrowband radios +- :ned:`Ieee802154UwbIrInterface` is for use with the UWB-IR radio +To create a wireless node with an 802.15.4 interface, use a node type that has a +wireless interface and set the interface type to the appropriate type. For +example, :ned:`WirelessHost` is a node type that is preconfigured to have one +wireless interface, ``wlan[0]``. ``wlan[0]`` is of parametric type, so if you +build the network from :ned:`WirelessHost` nodes, you can configure all of them +to use 802.15.4 with the following line in the ini file: .. code-block:: ini @@ -56,20 +52,19 @@ with the following line in the ini file: Physical Layer -------------- -The IEEE 802.15.4 standard defines several alternative PHYs. There are -several narrowband radios at various frequency bands using various -modulation schemes (DSSS, O-QPSK, MPSK, GFSK BPSK, etc.), a Direct -Sequence ultra-wideband (UWB), and one using chirp spread spectrum -(CSS). +The IEEE 802.15.4 standard defines several alternative PHYs. There are several +narrowband radios at various frequency bands using various modulation schemes +(DSSS, O-QPSK, MPSK, GFSK BPSK, etc.), a Direct Sequence ultra-wideband (UWB), +and one using chirp spread spectrum (CSS). INET provides the following radios: -- :ned:`Ieee802154NarrowbandScalarRadio` is currently a partially - parameterized version of the APSK radio. Before using this radio, one - must check its parameters and make sure that they correspond to the - specification of the 802.15.4 narrowband PHY to be simulated. +- :ned:`Ieee802154NarrowbandScalarRadio` is currently a partially parameterized + version of the APSK radio. Before using this radio, one must check its + parameters and make sure that they correspond to the specification of the + 802.15.4 narrowband PHY to be simulated. -- :ned:`Ieee802154UwbIrRadio` models the 802.14.5 UWB radio. +- :ned:`Ieee802154UwbIrRadio` models the 802.14.5 UWB radio. One must choose a matching medium model, for example :ned:`Ieee802154UwbIrRadioMedium` for :ned:`Ieee802154UwbIrRadio`, and @@ -81,13 +76,12 @@ One must choose a matching medium model, for example MAC Protocol ------------ -The 802.15.4 MAC is based on collision avoidance via CSMA/CA. Important -other features include real-time suitability by reservation of -guaranteed time slots, and integrated support for secure communications. -Devices also include power management functions such as link quality and -energy detection. +The 802.15.4 MAC is based on collision avoidance via CSMA/CA. Other important +features include real-time suitability by reservation of guaranteed time slots +and integrated support for secure communications. Devices also include power +management functions such as link quality and energy detection. -The :ned:`Ieee802154Mac` type in INET is currently a parameterized -version of a generic CSMA/CA protocol model with ACK support. +The :ned:`Ieee802154Mac` type in INET is currently a parameterized version of a +generic CSMA/CA protocol model with ACK support. There is also a :ned:`Ieee802154NarrowbandMac`. diff --git a/doc/src/users-guide/ch-adhoc-routing.rst b/doc/src/users-guide/ch-adhoc-routing.rst index d60c9a54f0b..abd72eb8776 100644 --- a/doc/src/users-guide/ch-adhoc-routing.rst +++ b/doc/src/users-guide/ch-adhoc-routing.rst @@ -16,7 +16,7 @@ and may announce that it too can reach them. The difficulty of routing may be compounded by the fact that nodes may be mobile, which results in a changing topology. -Ad hoc routing protocols fall in two broad categories: proactive and +Ad hoc routing protocols fall into two broad categories: proactive and reactive. *Proactive* or *table-driven* protocols maintain fresh lists of destinations and their routes by periodically distributing routing tables throughout the network. *Reactive* or *on-demand* protocols find @@ -34,8 +34,6 @@ supported routing protocol. For example, you can configure :ned:`ManetRouter` nodes in the network to use AODV with the following ini file line: - - .. code-block:: ini **.routingApp.typename = "Aodv" # as an application @@ -81,13 +79,13 @@ set to :ned:`Dsdv`. DYMO ---- -The DYMO (Dynamic MANET On-demand) routing protocol is successor to the -AODV routing protocol. DYMO can work as both a pro-active and as a +The DYMO (Dynamic MANET On-demand) routing protocol is the successor to the +AODV routing protocol. DYMO can work as both a proactive and a reactive routing protocol, i.e. routes can be discovered just when they are needed. The :ned:`Dymo` module type implements DYMO, based on the IETF draft -*draft-ietf-manet-dymo-24*. +"draft-ietf-manet-dymo-24". :ned:`DymoRouter` is a :ned:`ManetRouter` with the routing module type set to :ned:`Dymo`. @@ -101,8 +99,8 @@ GPSR (Greedy Perimeter Stateless Routing) is a routing protocol for mobile wireless networks that uses the geographic positions of nodes to make packet forwarding decisions. -The :ned:`Gpsr` module type implements GPSR, based on the paper “GPSR: -Greedy Perimeter Stateless Routing for Wireless Networks” by Brad Karp +The :ned:`Gpsr` module type implements GPSR, based on the paper "GPSR: +Greedy Perimeter Stateless Routing for Wireless Networks" by Brad Karp and H. T. Kung, 2000. The implementation supports both GG and RNG planarization algorithms. diff --git a/doc/src/users-guide/ch-apps.rst b/doc/src/users-guide/ch-apps.rst index 881c839292e..c2e95ef5e51 100644 --- a/doc/src/users-guide/ch-apps.rst +++ b/doc/src/users-guide/ch-apps.rst @@ -22,7 +22,7 @@ In the second category, applications are more generic. They separate traffic generation from the usage of the protocol, :ned:`Udp` or :ned:`Tcp` for example. These applications are implemented as compound modules. They contain separate configurable traffic source, traffic sink, and protocol input/output submodules. -This approach allows building complex traffic patterns by composing queueing +This approach allows building complex traffic patterns by composing queuing model elements. .. _ug:sec:apps:tcp-applications: @@ -30,12 +30,12 @@ model elements. TCP applications ---------------- -This sections describes the applications using the TCP protocol. These +This section describes the applications using the TCP protocol. These applications use :msg:`GenericAppMsg` objects to represent the data sent between the client and server. The client message contains the expected reply length, the processing delay, and a flag indicating that the connection should be closed after sending the reply. This way -intelligence (behavior specific to the modelled application, e.g. HTTP, +intelligence (behavior specific to the modeled application, e.g. HTTP, SMB, database protocol) needs only to be present in the client, and the server model can be kept simple and dumb. @@ -52,7 +52,7 @@ the client opens a single TCP connection to the server, sends several requests (always waiting for the complete reply to arrive before sending a new request), and closes the connection. -The server app should be :ned:`TcpGenericServerApp`; the model sends +The server app should be :ned:`TcpGenericServerApp`; the model sends a :msg:`GenericAppMsg` messages. Example settings: @@ -84,14 +84,14 @@ download these items in parallel to the main HTML document, this module cannot serve as a realistic web client. Also, with HTTP 1.0 it is the server that closes the connection after -sending the response, while in this model it is the client. +sending the response, while in this model, it is the client. .. _ug:sec:apps:tcpsinkapp: TcpSinkApp ~~~~~~~~~~ -Accepts any number of incoming TCP connections, and discards whatever +Accepts any number of incoming TCP connections and discards whatever arrives on them. .. _ug:sec:apps:tcpgenericserverapp: @@ -102,11 +102,11 @@ TcpGenericServerApp Generic server application for modeling TCP-based request-reply style protocols or applications. -The module accepts any number of incoming TCP connections, and expects +The module accepts any number of incoming TCP connections and expects to receive messages of class :msg:`GenericAppMsg` on them. A message should contain how large the reply should be (number of bytes). :ned:`TcpGenericServerApp` will just change the length of the received -message accordingly, and send back the same message object. The reply +message accordingly and send back the same message object. The reply can be delayed by a constant time (:par:`replyDelay` parameter). .. _ug:sec:apps:tcpechoapp: @@ -115,7 +115,7 @@ TcpEchoApp ~~~~~~~~~~ The :ned:`TcpEchoApp` application accepts any number of incoming TCP -connections, and sends back the data that arrives on them, The byte +connections and sends back the data that arrives on them. The byte counts are multiplied by :par:`echoFactor` before echoing. The reply can also be delayed by a constant time (:par:`echoDelay` parameter). @@ -135,10 +135,10 @@ Opening the connection Depending on the type of opening the connection (active/passive), the application may be either a client or a server. In passive mode, the -application will listen on the given local local port, and wait for an +application will listen on the given local local port and wait for an incoming connection. In active mode, the application will bind to given -local local address and local port, and connect to the given address and -port. It is possible to use an ephemeral port as local port. +local local address and local port and connect to the given address and +port. It is possible to use an ephemeral port as a local port. Even when in server mode (passive open), the application will only serve one incoming connection. Further connect attempts will be refused by TCP @@ -175,12 +175,12 @@ TelnetApp Models Telnet sessions with a specific user behavior. The server app should be :ned:`TcpGenericServerApp`. -In this model the client repeats the following activity between +In this model, the client repeats the following activity between :par:`startTime` and :par:`stopTime`: -#. Opens a telnet connection +1. Opens a telnet connection -#. Sends :par:`numCommands` commands. The command is +2. Sends :par:`numCommands` commands. The command is :par:`commandLength` bytes long. The command is transmitted as entered by the user character by character, there is :par:`keyPressDelay` time between the characters. The server echoes @@ -189,22 +189,20 @@ In this model the client repeats the following activity between long message. The user waits :par:`thinkTime` interval between the commands. -#. Closes the connection and waits :par:`idleInterval` seconds +3. Closes the connection and waits :par:`idleInterval` seconds -#. If the connection is broken, it is noticed after - :par:`reconnectInterval` and the connection is reopened +4. If the connection is broken, it is noticed after + :par:`reconnectInterval`, and the connection is reopened Each parameter in the above description is “volatile”, so you can use distributions to emulate random behavior. - - .. note:: - This module emulates a very specific user behavior, and as such, - it should be viewed as an example rather than a generic Telnet model. + This module emulates a very specific user behavior, and as such, it + should be viewed as an example rather than a generic Telnet model. If you want to model realistic Telnet traffic, you are encouraged - to gather statistics from packet traces on a real network, and + to gather statistics from packet traces on a real network and write your model accordingly. .. _ug:sec:apps:tcpserverhostapp: @@ -230,7 +228,7 @@ complex traffic without implementing new C++ modules: - :ned:`TcpServerListener`: generic TCP server listener for accepting/rejecting TCP connections and for creating TCP server connections - :ned:`TcpRequestResponseApp`: generic request-response based TCP server application with configurable pre-composed traffic source and traffic sink -There are some applications which model the traffic of the telnet protocol: +There are some applications that model the traffic of the telnet protocol: - :ned:`TelnetClientApp`: telnet client application with configurable pre-composed telnet traffic source and traffic sink - :ned:`TelnetServerApp`: telnet server application with pre-configured TCP server listener to create telnet server connections @@ -247,7 +245,7 @@ The following UDP-based applications are implemented in INET: interval - :ned:`UdpBasicBurst` sends UDP packets to the given IP address(es) in - bursts, or acts as a packet sink. + bursts or acts as a packet sink - :ned:`UdpEchoApp` is similar to :ned:`UdpBasicApp`, but it sends back the packet after reception @@ -258,7 +256,7 @@ The following UDP-based applications are implemented in INET: - :ned:`UdpVideoStreamClient`,:ned:`UdpVideoStreamServer` simulates video streaming over UDP -The next sections describe these applications in details. +The next sections describe these applications in detail. .. _ug:sec:apps:udpbasicapp: @@ -268,7 +266,7 @@ UdpBasicApp The :ned:`UdpBasicApp` sends UDP packets to a the IP addresses given in the :par:`destAddresses` parameter. The application sends a message to one of the targets in each :par:`sendInterval` interval. The interval -between message and the message length can be given as a random +between messages and the message length can be given as a random variable. Before the packet is sent, it is emitted in the signal. The application simply prints the received UDP datagrams. The signal can @@ -279,7 +277,7 @@ be used to detect the received packets. UdpSink ~~~~~~~ -This module binds an UDP socket to a given local port, and prints the +This module binds a UDP socket to a given local port and prints the source and destination and the length of each received packet. .. _ug:sec:apps:udpechoapp: @@ -288,18 +286,18 @@ UdpEchoApp ~~~~~~~~~~ Similar to :ned:`UdpBasicApp`, but it sends back the packet after -reception. It accepts only packets with :msg:`UdpHeader`, i.e. +reception. It accepts only packets with :msg:`UdpHeader`, i.e., packets that are generated by another :ned:`UdpEchoApp`. -When an echo response received, it emits an signal. +When an echo response is received, it emits a signal. .. _ug:sec:apps:udpvideostreamclient: UdpVideoStreamClient ~~~~~~~~~~~~~~~~~~~~ -This module is a video streaming client. It send one “video streaming -request” to the server at time :par:`startTime` and receives stream from +This module is a video streaming client. It sends one "video streaming +request" to the server at time :par:`startTime` and receives a stream from :ned:`UdpVideoStreamServer`. The received packets are emitted by the signal. @@ -314,38 +312,38 @@ This is the video stream server to be used with The server will wait for incoming "video streaming requests". When a request arrives, it draws a random video stream size using the -:par:`videoSize` parameter, and starts streaming to the client. During +:par:`videoSize` parameter and starts streaming to the client. During streaming, it will send UDP packets of size :par:`packetLen` at every :par:`sendInterval`, until :par:`videoSize` is reached. The parameters :par:`packetLen` and :par:`sendInterval` can be set to constant values -to create CBR traffic, or to random values (e.g. +to create CBR traffic or to random values (e.g., ``sendInterval=uniform(1e-6, 1.01e-6)``) to accommodate jitter. -The server can serve several clients, and several streams per client. +The server can serve several clients and several streams per client. .. _ug:sec:apps:udpbasicburst: UdpBasicBurst ~~~~~~~~~~~~~ -Sends UDP packets to the given IP address(es) in bursts, or acts as a +Sends UDP packets to the given IP address(es) in bursts or acts as a packet sink. Compatible with both IPv4 and IPv6. Addressing ^^^^^^^^^^ -The :par:`destAddresses` parameter can contain zero, one or more +The :par:`destAddresses` parameter can contain zero, one, or more destination addresses, separated by spaces. If there is no destination -address given, the module will act as packet sink. If there are more +address given, the module will act as a packet sink. If there are more than one addresses, one of them is randomly chosen, either for the whole -simulation run, or for each burst, or for each packet, depending on the +simulation run or for each burst or for each packet, depending on the value of the :par:`chooseDestAddrMode` parameter. The :par:`destAddrRNG` parameter controls which (local) RNG is used for randomized address selection. The own addresses will be ignored. -An address may be given in the dotted decimal notation, or with the +An address may be given in the dotted decimal notation or with the module name. (The :cpp:`L3AddressResolver` class is used to resolve the -address.) You can use the "Broadcast" string as address for sending +address.) You can use the "Broadcast" string as an address for sending broadcast messages. INET also defines several NED functions that can be useful: @@ -378,20 +376,20 @@ Bursts The first burst starts at :par:`startTime`. Bursts start by immediately sending a packet; subsequent packets are sent at :par:`sendInterval` -intervals. The :par:`sendInterval` parameter can be a random value, e.g. +intervals. The :par:`sendInterval` parameter can be a random value, e.g., ``exponential(10ms)``. A constant interval with jitter can be specified as ``1s+uniform(-0.01s,0.01s)`` or ``uniform(0.99s,1.01s)``. The length of the burst is controlled by the :par:`burstDuration` parameter. (Note that if :par:`sendInterval` is greater than :par:`burstDuration`, the burst will consist of one packet -only.) The time between burst is the :par:`sleepDuration` parameter; -this can be zero (zero is not allowed for :par:`sendInterval`.) The zero +only.) The time between bursts is the :par:`sleepDuration` parameter; +this can be zero (zero is not allowed for :par:`sendInterval`). The zero :par:`burstDuration` is interpreted as infinity. -Operation as sink -^^^^^^^^^^^^^^^^^ +Operation as a sink +^^^^^^^^^^^^^^^^^^ -When :par:`destAddresses` parameter is empty, the module receives +When the :par:`destAddresses` parameter is empty, the module receives packets and makes statistics only. Applications composing UDP traffic @@ -415,16 +413,16 @@ IPv4/IPv6 traffic generators ---------------------------- The applications described in this section use the services of the -network layer only, they do not need transport layer protocols. They can +network layer only; they do not need transport layer protocols. They can be used with both IPv4 and IPv6. :ned:`IIpvxTrafficGenerator` (prototype) sends IP or IPv6 datagrams to the given address at the given :par:`sendInterval`. The -:par:`sendInterval` parameter can be a constant or a random value (e.g. +:par:`sendInterval` parameter can be a constant or a random value (e.g., ``exponential(1)``). If the :par:`destAddresses` parameter contains -more than one address, one of them is randomly for each packet. An +more than one address, one of them is randomly chosen for each packet. An address may be given in the dotted decimal notation (or, for IPv6, in -the usual notation with colons), or with the module name. (The +the usual notation with colons) or with the module name. (The :cpp:`L3AddressResolver` class is used to resolve the address.) To disable the model, set :par:`destAddresses` to "". @@ -438,7 +436,7 @@ signal and drops it. The ``rcvdPkBytes`` and ``endToEndDelay`` statistics are generated from this signal. The :ned:`IpvxTrafGen` can also be the peer of the traffic generators; -it handles the received packets exactly like :ned:`IpvxTrafSink`. +it handles the received packets exactly like the :ned:`IpvxTrafSink`. .. _ug:sec:apps:the-pingapp-application: @@ -446,21 +444,21 @@ The PingApp application ----------------------- The :ned:`PingApp` application generates ping requests and calculates -the packet loss and round trip parameters of the replies. +the packet loss and round-trip parameters of the replies. -Start/stop time, sendInterval etc. can be specified via parameters. An +Start/stop time, :par:`sendInterval` etc., can be specified via parameters. An address may be given in the dotted decimal notation (or, for IPv6, in -the usual notation with colons), or with the module name. (The +the usual notation with colons) or with the module name. (The :cpp:`L3AddressResolver` class is used to resolve the address.) To -disable send, specify empty destAddr. +disable sending, specify an empty destAddr. Every ping request is sent out with a sequence number, and replies are -expected to arrive in the same order. Whenever there’s a jump in the in -the received ping responses’ sequence number (e.g. 1, 2, 3, 5), then the -missing pings (number 4 in this example) is counted as lost. Then if it +expected to arrive in the same order. Whenever there is a jump in the in +the received ping responses' sequence number (e.g., 1, 2, 3, 5), then the +missing pings (number 4 in this example) are counted as lost. Then if it still arrives later (that is, a reply with a sequence number smaller -than the largest one received so far) it will be counted as -out-of-sequence arrival, and at the same time the number of losses is +than the largest one received so far), it will be counted as +an out-of-sequence arrival, and at the same time, the number of losses is decremented. (It is assumed that the packet arrived was counted earlier as a loss, which is true if there are no duplicate packets.) @@ -473,28 +471,28 @@ Ethernet applications The ``inet.applications.ethernet`` package contains modules for a simple client-server application. The :ned:`EtherAppClient` is a simple traffic generator that periodically sends :msg:`EtherAppReq` messages -whose length can be configured. destAddress, startTime,waitType, -reqLength, respLength +whose length can be configured. destAddress, startTime, waitType, +reqLength, respLength. The server component of the model (:ned:`EtherAppServer`) responds with -a :msg:`EtherAppResp` message of the requested length. If the response -does not fit into one ethernet frame, the client receives the data in +an :msg:`EtherAppResp` message of the requested length. If the response +does not fit into one Ethernet frame, the client receives the data in multiple chunks. Both applications have a :par:`registerSAP` boolean parameter. This parameter should be set to ``true`` if the application is connected -to the :ned:`Ieee8022Llc` module which requires registration of the SAP +to the :ned:`Ieee8022Llc` module, which requires the registration of the SAP before sending frames. -Both applications collects the following statistics: sentPkBytes, +Both applications collect the following statistics: sentPkBytes, rcvdPkBytes, endToEndDelay. -The client and server application works with any model that accepts -Ieee802Ctrl control info on the packets (e.g. the 802.11 model). The +The client and server application work with any model that accepts +Ieee802Ctrl control info on the packets (e.g., the 802.11 model). The applications should be connected directly to the :ned:`Ieee8022Llc` or an EthernetInterface NIC module. The model also contains a host component that groups the applications and the LLC and MAC components together (:ned:`EthernetHost`). This node -does not contain higher layer protocols, it generates Ethernet traffic -directly. By default it is configured to use half duplex MAC (CSMA/CD). +does not contain higher layer protocols; it generates Ethernet traffic +directly. By default, it is configured to use half-duplex MAC (CSMA/CD). \ No newline at end of file diff --git a/doc/src/users-guide/ch-authors-guide.rst b/doc/src/users-guide/ch-authors-guide.rst index 18e62fbcf81..1996ead5e2c 100644 --- a/doc/src/users-guide/ch-authors-guide.rst +++ b/doc/src/users-guide/ch-authors-guide.rst @@ -15,27 +15,27 @@ content is appropriate for this *Guide* and what is not. The main guiding principle is to avoid redundancy and duplication of information with other pieces of documentation, namely: -- Standards documents (RFCs, IEEE specifications, etc.) that describe - protocols that INET modules implement; +- Standards documents (RFCs, IEEE specifications, etc.) that describe + protocols that INET modules implement; -- *INET Developer’s Guide*, which is intended as a guide for anyone - wishing to understand or modify the operation of INET’s components at - C++ level; +- *INET Developer’s Guide*, which is intended as a guide for anyone + wishing to understand or modify the operation of INET’s components at + the C++ level; -- *INET Framework Reference*, directly generated from NED and MSG - comments by OMNeT++ documentation generator; +- *INET Framework Reference*, directly generated from NED and MSG + comments by OMNeT++ documentation generator; -- Showcases, tutorials and simulation examples (``showcases/``, - ``tutorials/`` and ``examples/`` folders in the INET project) +- Showcases, tutorials, and simulation examples (``showcases/``, + ``tutorials/``, and ``examples/`` folders in the INET project) Why is duplication to be avoided? Multiple reasons: -- It is a waste of our reader’s time they have to skip information they - have already seen elsewhere +- It is a waste of our readers' time if they have to skip information they + have already seen elsewhere. -- The text can easily get out of date as the INET Framework evolves +- The text can easily get out of date as the INET Framework evolves. -- It is extra effort for maintainers to keep all copies up to date +- It is extra effort for maintainers to keep all copies up to date. .. _ug:sec:authorsguide:guidelines: @@ -48,26 +48,26 @@ Do Not Repeat the Standard ~~~~~~~~~~~~~~~~~~~~~~~~~~ When describing a module that implements protocol X, do not go into -lengths explaining what protocol X does and how it works, because that -is appropriately (and usually, much better) explained in the +lengthy explanations of what protocol X does and how it works since +that is appropriately (and usually, much better) explained in the specification or books on protocol X. It is OK to summarize the -protocol’s goal and principles in short paragraph though. +protocol’s goal and principles in a short paragraph though. -In particular, do not describe the *format of the protocol messages*. It -surely looks nice and takes up a lot of space, but the same information -can probably be found in a myriad places all over the internet. +In particular, do not describe the *format of the protocol messages.* It +may look nice and take up a lot of space, but the same information +can probably be found in a myriad of places all over the internet. .. _ug:sec:authorsguide:do-not-repeat-ned: Do Not Repeat NED ~~~~~~~~~~~~~~~~~ -Things like module parameters, gate names, emitted signals and collected +Things like module parameters, gate names, emitted signals, and collected statistics are appropriately and formally part of the NED definitions, and there is no need to duplicate that information in this *Guide*. Detailed information on the module, such as *usage details* and the list -of *implemented standards* should be covered in the module’s NED +of *implemented standards,* should be covered in the module’s NED documentation, not in this *Guide*. .. _ug:sec:authorsguide:no-cplusplus: @@ -75,16 +75,16 @@ documentation, not in this *Guide*. No C++ ~~~~~~ -Any content which only makes sense on C++ level should go to the -*Developer’s Guide*, and has no place in this *Guide*. +Any content which only makes sense at the C++ level should go to the +*Developer’s Guide* and has no place in this *Guide*. .. _ug:sec:authorsguide:keep-examples-short: Keep Examples Short ~~~~~~~~~~~~~~~~~~~ -When giving examples about usage, keep them concise and to the point. -Giving ini or NED file fragments of a few lines length is preferable to +When giving examples of usage, keep them concise and to the point. +Giving ini or NED file fragments of a few lines in length is preferable to complete working examples. Complete examples should be written up as showcases. A working @@ -97,8 +97,8 @@ should be written up as a tutorial. No Reference to Simulation Examples ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Do not refer to concrete example simulations, showcases or tutorials in -the text, because they might get renamed, moved, merged or deleted, and +Do not refer to concrete example simulations, showcases, or tutorials in +the text because they might get renamed, moved, merged, or deleted, and when they do, no one will think about updating the reference in the *Users Guide*. @@ -107,10 +107,10 @@ when they do, no one will think about updating the reference in the What then? ~~~~~~~~~~ -Concentrate on giving a “big picture” of the models: what it is +Concentrate on giving a "big picture" of the models: what they are generally capable of, how the parts fit together, etc. Give just enough -information that after a quick read, users can “bootstrap” into putting +information that after a quick read, users can "bootstrap" into putting together their own simulations with the model. If they have questions afterwards, they will/should refer to the NED documentation (INET -Reference), or if that’s not enough, delve into the C++ code to find the -answers. +Reference) or, if that’s not enough, delve into the C++ code to find the +answers. \ No newline at end of file diff --git a/doc/src/users-guide/ch-clock.rst b/doc/src/users-guide/ch-clock.rst index 7d39533af04..f59e3fb7f32 100644 --- a/doc/src/users-guide/ch-clock.rst +++ b/doc/src/users-guide/ch-clock.rst @@ -14,37 +14,36 @@ Overview In most communication network simulations, time is simply modeled as a global quantity. All components of the network share the same time throughout the -simulation independently of where they are physically located or how they are -logically connected to the network. +simulation, independent of their physical location or logical connection to the network. -In contrast, in time sensitive networking, the bookkeeping of time is an essential +In contrast, in time-sensitive networking, the tracking of time is an essential part, which should be explicitly simulated independently of the underlying global -time. The reason is that the differences among the local time of the communication -network components significantly affects the simulation results. - -In such simulations, hardware clocks are simulated on their own, and communication -protocols don't rely on the global value of simulation time, which is in fact -unknown in reality, but on the value of their own clocks. With having hardware -clocks modeled, it's also often required to use various time synchronization -protocols, because clocks tend to drift over time and communication protocols +time. This is because the differences in the local time of the communication +network components significantly affect the simulation results. + +In such simulations, hardware clocks are simulated separately, and communication +protocols do not rely on the global value of simulation time, which is, in fact, +unknown in reality, but rather on the value of their own clocks. With hardware +clocks being modeled, it is also often necessary to use various time synchronization +protocols because clocks tend to drift over time and communication protocols rely on the precision of the clocks they are using. -In INET, the clock model is a completely optional feature, which has no effect +In INET, the clock model is a completely optional feature that has no effect on the simulation performance when disabled. Even if the feature is enabled, the usage of clock modules by communication protocols and applications is still -optional, and enabling the feature has negligible performance hit when not in -use. For testing that the mere usage of a clock has no effect on the simulation +optional, and enabling the feature has a negligible performance impact when not in +use. To test that the mere usage of a clock has no effect on the simulation results, INET also includes an ideal clock mechanism. Clocks ------ -Clocks are implemented as modules, and are used by other modules via direct C++ +Clocks are implemented as modules and are used by other modules via direct C++ method calls. Clock modules implement the :ned:`IClock` module interface and the corresponding :cpp:`IClock` C++ interface. -The C++ interface provides an API similar to the standard OMNeT++ simulation time -based scheduling mechanism, but it relies on the underlying clock implementation +The C++ interface provides an API similar to the standard OMNeT++ simulation time-based +scheduling mechanism, but it relies on the underlying clock implementation for (re)scheduling events according to the clock. These events are transparently scheduled for the client module, and they will be delivered to it when the clock timers expire. @@ -60,42 +59,41 @@ and the network interface levels. The following clock models are available: - :ned:`IdealClock`: clock time is identical to the simulation time. - :ned:`OscillatorBasedClock`: clock time is the number of oscillator ticks multiplied by the nominal tick length. -- :ned:`SettableClock`: a clock which can be set to a different clock time. +- :ned:`SettableClock`: a clock that can be set to a different clock time. Clock Time ---------- -In order to avoid confusing the simulation time (which is basically unknown to +To avoid confusing the simulation time (which is basically unknown to communication protocols and hardware elements) with the clock time maintained by hardware clocks, INET introduces a new C++ type called the :cpp:`ClockTime`. -This type is pretty much the same as the default :cpp:`SimTime`, but the two +This type is similar to the default :cpp:`SimTime`, but the two types cannot be implicitly converted into each other. This approach prevents accidentally using clock time where simulation time is needed, and vice versa. -Simlarly to how :cpp:`simtime_t` is an alias for :cpp:`SimTime`, INET also -introduces the :cpp:`clocktime_t` alias for :cpp:`ClockTime` type. +Similarly to how :cpp:`simtime_t` is an alias for :cpp:`SimTime`, INET also +introduces the :cpp:`clocktime_t` alias for the :cpp:`ClockTime` type. For the explicit conversion between clock time and simulation time, one can use the :cpp:`CLOCKTIME_AS_SIMTIME` and the :cpp:`SIMTIME_AS_CLOCKTIME` C++ macros. -Note that these macros don't change the numerical value, they simply convert +Note that these macros do not change the numerical value; they simply convert between the C++ types. When the actual clock time is used by a clock, the value may be rounded according -to the clock granularity and rounding mode (e.g. :ned:`OscillatorBasedClock`). For -example, when a clock with a us granularity is instructed to wait for 100 ns, +to the clock granularity and rounding mode (e.g., :ned:`OscillatorBasedClock`). For +example, when a clock with a microsecond granularity is instructed to wait for 100 nanoseconds, while its oscillator is right in the middle of its ticking period, it may actually -wait for the next tick to happen to start the timer, and wait another tick to -happen to account for the requested wait time interval. +wait for the next tick to happen to start the timer and wait another tick to +account for the requested wait time interval. Oscillators ----------- -The clock interface is quite general in the sense that it allows many different -ways to implement it. Nevertheless, the most common way is to use an oscillator -based clock model. +The clock interface is quite general in the sense that it allows for many different +ways of implementation. Nevertheless, the most common way is to use an oscillator-based clock model. An oscillator efficiently models the periodic generation of ticks that are usually -counted by a clock module. The tick period is not necessarily constant, it can +counted by a clock module. The tick period is not necessarily constant; it can change over time. Oscillators implement the :ned:`IOscillator` module interface and the corresponding :cpp:`IOscillator` C++ interface. @@ -103,7 +101,7 @@ The following oscillator models are available: - :ned:`IdealOscillator`: generates ticks periodically with a constant length (mostly useful for testing). -- :ned:`ConstantDriftOscillator`: tick length changes proportional to the elapsed +- :ned:`ConstantDriftOscillator`: tick length changes proportionally to the elapsed simulation time (clock drift). - :ned:`RandomDriftOscillator`: updates clock drift with a random walk process. @@ -112,9 +110,9 @@ Clock Users The easiest way to use a clock in applications and communication protocols is to add a `clockModule` parameter that specifies where the clock module can be -found. Then the C++ user module should be simply derived from either +found. Then the C++ user module should simply be derived from either :cpp:`ClockUserModuleBase` or the parameterizable :cpp:`ClockUserModuleMixin` -base classes. The clock can be used via the inherited clock related methods +base classes. The clock can be used via the inherited clock-related methods or through the methods of the :cpp:`IClock` C++ interface on the inherited clock field. @@ -122,22 +120,22 @@ Clock Events ------------ The clock model requires the use of a specific C++ class called :cpp:`ClockEvent` -to schedule clock timers. It's also allowed to derive new C++ classes from +to schedule clock timers. It is also allowed to derive new C++ classes from :cpp:`ClockEvent` if necessary. In any case, clock events must be scheduled and -canceled via the :cpp:`IClock` C++ interface to operate properly. +canceled via the :cpp:`IClock` C++ interface to operate correctly. Controlling Clocks According to a Scenario ------------------------------------------ -In order to support the simulation of specific scenarios, where the clock time +To support the simulation of specific scenarios, where the clock time or the oscillator drift must be changed according to a predefined script, INET provides clocks and oscillators that implement the interface required by the :ned:`ScenarioManager` module. This allows the user to update the clock and -oscillator state from the :ned:`ScenarioManager` XML script and to also mix +oscillator states from the :ned:`ScenarioManager` XML script and also to mix these operations with many other supported operations. For example, the :ned:`SettableClock` model supports setting the clock time and -also to optionally reset the oscillator at a specific moment of simulation time +optionally resetting the oscillator at a specific moment of simulation time as follows: .. code-block:: xml diff --git a/doc/src/users-guide/ch-collecting-results.rst b/doc/src/users-guide/ch-collecting-results.rst index 91546ff0fa9..e60b72025c4 100644 --- a/doc/src/users-guide/ch-collecting-results.rst +++ b/doc/src/users-guide/ch-collecting-results.rst @@ -5,7 +5,7 @@ Collecting Results The following sections introduce the INET specific concepts and features for collecting simulation results. For more information in general on collecting -statistics please refer to the OMNeT++ manual. +statistics, please refer to the OMNeT++ manual. .. _ug:sec:results:recording-statistics: @@ -19,15 +19,15 @@ as either scalars, vectors, or histograms depending on the typical usefulness of the statistic. Note that it's possible to change the default recording mode from INI files as described in the OMNeT++ manual. -If the default statistics, provided by the INET modules, are not sufficient, -then you can derive new modules using only NED files, and add new statistics +If the default statistics provided by the INET modules are not sufficient, +then you can derive new modules using only NED files and add new statistics to them based on the signals already emitted by the module. The emitted signals can also be found as @signal properties declared in the corresponding NED files. If even declaring new statistics isn't sufficient, then you can also derive new -C++ classes from the module implementations, and add new signals and/or add new +C++ classes from the module implementations and add new signals and/or add new statistic collection code to them. This is the most cumbersome way to collect -new results, but it's also the most expressive allowing to collect any kind of +new results, but it's also the most expressive, allowing to collect any kind of statistic. Measuring along Packet Flows @@ -35,7 +35,7 @@ Measuring along Packet Flows By default, INET statistics are only capable of collecting results based on the data that individual protocol modules and applications can access. Each module -collects statistics independently of the rest of the network often rendering +collects statistics independently of the rest of the network, often rendering the statistics less useful in complex scenarios. For example, a TCP protocol module that communicates with multiple other TCP modules cannot distinguish between the packets based on the path they took. To overcome this issue, INET @@ -43,28 +43,28 @@ introduces the notion of packet flows. A packet flow is a logical classification of packets, identified by its name, over the whole network and over the duration of the whole simulation. Basically, -at any given moment any packet that is present anywhere in the network can be +at any given moment, any packet that is present anywhere in the network can be part of any number of packet flows. Packets may enter a packet flow and leave it multiple times. Different packet flows can overlap both in time and also along the network topology. Note that a packet flow doesn't necessarily have a single entry and a single exit point. A packet flow is usually defined by active modules that classify certain packets -(e.g. matching a filter) to be entering the flow, and similarly other modules -that decide when packets leave the flow. Both kind of modules are inserted into -the network for this specific purpose usually at the network interface level. +(e.g., matching a filter) to be entering the flow, and similarly other modules +that decide when packets leave the flow. Both kinds of modules are inserted into +the network for this specific purpose, usually at the network interface level. While a packet is being part of any number of packet flows, certain INET modules -(e.g. queues) are going to automatically record certain events that happen with -the packets (e.g. queueing). +(e.g., queues) are going to automatically record certain events that happen with +the packets (e.g., queueing). -So far, the notion of packet flows were introduced on the packet level. That is -at any given time a packet is either completely part of a packet flow or not. +So far, the notion of packet flows was introduced on the packet level. That is, +at any given time, a packet is either completely part of a packet flow or not. In fact, this is a simplification for easier understanding. This approach is -clearly not sufficient in the general case, because packets can be fragmented +clearly not sufficient in the general case because packets can be fragmented and aggregated throughout the network, and they can traverse many different -paths. Therefore the packet flow membership is actually specified on a per bit +paths. Therefore, the packet flow membership is actually specified on a per-bit basis. The implementation takes care of efficiently representing this data, so -the coherent parts of a packet that belongs to the same packet flow is marked +the coherent parts of a packet that belong to the same packet flow are marked together. Using the packet flow mechanism, one can easily measure the timing of various @@ -72,23 +72,23 @@ things that happen to a packet (or to a part of it). The following quantities are automatically measured (if requested) along packet flows: - total elapsed time measured from entering the packet flow -- total time spent in queues (e.g. transmission queue) -- total delay spent in various non-queue modules (e.g. interframe gap) -- total time spent in various packet processing modules (e.g. packet server) +- total time spent in queues (e.g., transmission queue) +- total delay spent in various non-queue modules (e.g., interframe gap) +- total time spent in various packet processing modules (e.g., packet server) - total transmission time of transmitters - total propagation time spent on the transmission medium The collected timing data is attached to coherent regions of the packets while -the packets are in the packet flow. The actual measurement, that is collecting -the statistical results is usually done when the packets leave the packet flow. +the packets are in the packet flow. The actual measurement, that is, collecting +the statistical results, is usually done when the packets leave the packet flow. If the timing statistics are not sufficient, it's also possible to collect all -packet events that happens to packets in the packet flow. The following packet +packet events that happen to packets in the packet flow. The following packet events can be automatically collected along packet flows: -- packet is enqueued in a packet queue (e.g. transmission queue) -- packet is delayed (e.g. interframe gap) -- packet is processed (e.g. packet server) +- packet is enqueued in a packet queue (e.g., transmission queue) +- packet is delayed (e.g., interframe gap) +- packet is processed (e.g., packet server) - packet is transmitted by a wired or wireless transmitter - packet is propagated on a wired or wireless transmission medium @@ -102,7 +102,7 @@ the following modules: - :ned:`FlowMeasurementStarter`: classifies packets to enter packet flows and starts timing measurements or packet event collection. -- :ned:`FlowMeasurementRecorder`: completes timing measurements, collects statistics +- :ned:`FlowMeasurementRecorder`: completes timing measurements, collects statistics, and makes packets leave the packet flow. - :ned:`MeasurementLayer`: can be added to network nodes and network interfaces for optional packet flow measurements. @@ -114,9 +114,9 @@ Recording PCAP Traces The easiest way to understand the behavior of a communication network on the network level is to look at the actual packets that are exchanged. INET supports -recording such packet traces in the widely used PCAP and its more recent sibling +recording such packet traces in the widely used PCAP and its more recent sibling, the PCAPng file formats. These file formats allow analyzing the network traffic -using the well-known Wireshark packet analyizer. +using the well-known Wireshark packet analyzer. All network nodes and network interfaces support the recording of incoming and outgoing traffic into PCAP files via optional :ned:`PcapRecorder` modules. By @@ -129,9 +129,9 @@ PCAP file that contains all network traffic. If the traffic of more than one network interface is recorded into a single file, then the newer PCAPng file format must be used to also record the data of the corresponding network interfaces. -Recording PCAP traces also supports using packet filters, which in turn allows +Recording PCAP traces also support using packet filters, which in turn allows one to produce multiple files for the same network interface containing different -kind of traffic. +kinds of traffic. .. _ug:sec:results:recording-routing-tables: @@ -145,7 +145,7 @@ difficult thing to do. In order to ease this task, INET provides a special interface data along with all routes in all routing tables into a single log file. -The log file uses a simple text based format. It contains one line for each +The log file uses a simple text-based format. It contains one line for each network interface added, changed, or deleted, and it also contains one line for each route added, changed, or deleted in all network nodes. The resulting log file can be used, for example, to verify that certain changes don't affect diff --git a/doc/src/users-guide/ch-diffserv.rst b/doc/src/users-guide/ch-diffserv.rst index 9bc75e45193..3da50daa915 100644 --- a/doc/src/users-guide/ch-diffserv.rst +++ b/doc/src/users-guide/ch-diffserv.rst @@ -13,27 +13,27 @@ Overview -------- In the early days of the Internet, only best effort service was defined. -The Internet delivers individually each packet, and delivery time is not -guaranteed, moreover packets may even be dropped due to congestion at -the routers of the network. It was assumed that transport protocols, and +The Internet delivers each packet individually, and delivery time is not +guaranteed. Moreover, packets may even be dropped due to congestion at +the routers of the network. It was assumed that transport protocols and applications can overcome these deficiencies. This worked until FTP and -email was the main applications of the Internet, but the newer +email were the main applications of the Internet, but the newer applications such as Internet telephony and video conferencing cannot tolerate delay jitter and loss of data. -The first attempt to add QoS capabilities to the IP routing was +The first attempt to add QoS capabilities to IP routing was Integrated Services. Integrated services provide resource assurance through resource reservation for individual application flows. An application flow is identified by the source and destination addresses -and ports and the protocol id. Before data packets are sent the +and ports and the protocol ID. Before data packets are sent, the necessary resources must be allocated along the path from the source to -the destination. At the hops from the source to the destination each -router must examine the packets, and decide if it belongs to a reserved -application flow. This could cause a memory and processing demand in the -routers. Other drawback is that the reservation must be periodically -refreshed, so there is an overhead during the data transmission too. +the destination. Each router along the path must examine the packets and +decide if they belong to a reserved application flow. This could cause a +memory and processing demand on the routers. Another drawback is that +the reservation must be periodically refreshed, so there is overhead +during the data transmission as well. -Differentiated Services is a more scalable approach to offer a better +Differentiated Services is a more scalable approach that offers a better than best-effort service. Differentiated Services do not require resource reservation setup. Instead of making per-flow reservations, Differentiated Services divides the traffic into a small number of @@ -46,13 +46,13 @@ when a link is congested, the network will drop packets with the highest drop priority first. In the Differentiated Service architecture, the network is partitioned -into DiffServ domains. Within each domain the resources of the domain -are allocated to forwarding classes, taking into account the available -resources and the traffic flows. There are *service level agreements* -(SLA) between the users and service providers, and between the domains +into DiffServ domains. Within each domain, the resources are allocated +to forwarding classes, taking into account the available resources and +the traffic flows. There are *service level agreements* +(SLAs) between the users and service providers, and between the domains that describe the mapping of packets to forwarding classes and the allowed traffic profile for each class. The routers at the edge of the -network are responsible for marking the packets and protect the domain +network are responsible for marking the packets and protecting the domain from misbehaving traffic sources. Nonconforming traffic may be dropped, delayed, or marked with a different forwarding class. @@ -61,7 +61,7 @@ delayed, or marked with a different forwarding class. Implemented Standards ~~~~~~~~~~~~~~~~~~~~~ -The implementation follows these RFCs below: +The implementation follows these RFCs: - RFC 2474: Definition of the Differentiated Services Field (DS Field) in the IPv4 and IPv6 Headers @@ -100,21 +100,21 @@ Traffic Conditioners Traffic conditioners have one input and one output gate as defined in the :ned:`ITrafficConditioner` interface. They can transform the incoming traffic by dropping or delaying packets. They can also set the -DSCP field of the packet, or mark them other way, for differentiated +DSCP field of the packet or mark it in another way for differentiated handling in the queues. Traffic conditioners perform the following actions: -- classify the incoming packets +- Classify the incoming packets. -- meter the traffic in each class +- Meter the traffic in each class. -- marks/drops packets depending on the result of metering +- Mark or drop packets depending on the result of metering. -- shape the traffic by delaying packets to conform to the desired - traffic profile +- Shape the traffic by delaying packets to conform to the desired + traffic profile. -INET provides classifier, meter, and marker modules, that can be +INET provides classifier, meter, and marker modules that can be composed to build a traffic conditioner as a compound module. .. _ug:sec:diffserv:output-queues: @@ -136,48 +136,48 @@ Simple modules -------------- This section describes the primitive elements from which traffic -conditioners and output queues can be built. The next sections shows -some examples, how these queues, schedulers, droppers, classifiers, -meters, markers can be combined. +conditioners and output queues can be built. The following sections show +some examples of how these queues, schedulers, droppers, classifiers, +meters, and markers can be combined. -The type of the components are: +The types of the components are: -- ``queue``: container of packets, accessed as FIFO +- ``queue``: container of packets, accessed as FIFO. -- ``dropper``: attached to one or more queue, it can limit the queue - length below some threshold by selectively dropping packets +- ``dropper``: attached to one or more queues, it can limit the queue + length below some threshold by selectively dropping packets. -- ``scheduler``: decide which packet is transmitted first, when more - packets are available on their inputs +- ``scheduler``: decides which packet is transmitted first when more + packets are available on their inputs. -- ``classifier``: classify the received packets according to their - content (e.g. source/destination, address and port, protocol, dscp - field of IP datagrams) and forward them to the corresponding output +- ``classifier``: classifies the received packets according to their + content (e.g., source/destination address and port, protocol, DSCP + field of IP datagrams) and forwards them to the corresponding output gate. -- ``meter``: classify the received packets according to the temporal - characteristic of their traffic stream +- ``meter``: classifies the received packets according to the temporal + characteristic of their traffic stream. - ``marker``: marks packets by setting their fields to control their - further processing + further processing. .. _ug:sec:diffserv:queues: Queues ~~~~~~ -When packets arrive at higher rate, than the interface can trasmit, they -are getting queued. +When packets arrive at a higher rate than the interface can transmit, +they are queued. Queue elements store packets until they can be transmitted. They have one input and one output gate. Queues may have one or more thresholds associated with them. Received packets are enqueued and stored until the module connected to -their output asks a packet by calling the :fun:`requestPacket()` +their output requests a packet by calling the :fun:`requestPacket()` method. -They should be able to notify the module connected to its output about +They should be able to notify the module connected to their output about the arrival of new packets. .. _ug:sec:diffserv:fifo-queue: @@ -199,13 +199,13 @@ DropTailQueue The other primitive queue module is :ned:`DropTailQueue`. Its capacity can be specified by the :par:`packetCapacity` parameter. When the number -of stored packet reached the capacity of the queue, further packets are +of stored packets reaches the capacity of the queue, further packets are dropped. Because this module contains a built-in dropping strategy, it cannot be combined with algorithmic droppers as :ned:`PacketQueue` can be. -However its output can be connected to schedulers. +However, its output can be connected to schedulers. This module implements the :ned:`IPacketQueue` interface, so it can be -used as the queue component of interface card per se. +used as the queue component of an interface card. .. _ug:sec:diffserv:droppers: @@ -213,21 +213,21 @@ Droppers ~~~~~~~~ Algorithmic droppers selectively drop received packets based on some -condition. The condition can be either deterministic (e.g. to bound the -queue length), or probabilistic (e.g. RED queues). +condition. The condition can be either deterministic (e.g., to bound the +queue length) or probabilistic (e.g., RED queues). -Other kind of droppers are absolute droppers; they drop each received -packet. They can be used to discard excess traffic, i.e. packets whose -arrival rate exceeds the allowed maximum. In INET the :ned:`Sink` module +Another kind of dropper is an absolute dropper that drops each received +packet. It can be used to discard excess traffic, i.e. packets whose +arrival rate exceeds the allowed maximum. In INET, the :ned:`Sink` module can be used as an absolute dropper. The algorithmic droppers in INET are :ned:`ThresholdDropper` and -:ned:`RedDropper`. These modules has multiple input and multiple output +:ned:`RedDropper`. These modules have multiple input and multiple output gates. Packets that arrive on gate :gate:`in[i]` are forwarded to gate -:gate:`out[i]` (unless they are dropped). However the queues attached to +:gate:`out[i]` (unless they are dropped). However, the queues attached to the output gates are viewed as a whole, i.e. the queue length parameter of the dropping algorithm is the sum of the individual queue lengths. -This way we can emulate shared buffers of the queues. Note, that it is +This way, we can emulate shared buffers of the queues. Note that it is also possible to connect each output to the same queue module. .. _ug:sec:diffserv:threshold-dropper: @@ -235,12 +235,12 @@ also possible to connect each output to the same queue module. Threshold Dropper ^^^^^^^^^^^^^^^^^ -The :ned:`ThresholdDropper` module selectively drops packets, based on +The :ned:`ThresholdDropper` module selectively drops packets based on the available buffer space of the queues attached to its output. The -buffer space can be specified as the count of packets, or as the size in +buffer space can be specified as the count of packets or as the size in bytes. -The module sums the buffer lengths of its outputs and if enqueuing a +The module sums the buffer lengths of its outputs, and if enqueuing a packet would exceed the configured capacities, then the packet will be dropped instead. @@ -293,18 +293,18 @@ implement different packet drop priorities. Schedulers ~~~~~~~~~~ -Scheduler modules decide which queue can send a packet, when the +Scheduler modules decide which queue can send a packet when the interface is ready to transmit one. They have several input gates and one output gate. Modules that are connected to the inputs of a scheduler must implement -the :cpp:`IPacketQueue` C++ interface. Schedulers also implement -:cpp:`IPacketQueue`, so they can be cascaded to other schedulers, and -can be used as the output module of :ned:`IPacketQueue`’s. +the :cpp:`IPacketQueue` C++ interface. Schedulers also implement the +:cpp:`IPacketQueue` interface, so they can be cascaded to other +schedulers and used as the output module of :ned:`IPacketQueue`'s. -There are several possible scheduling discipline (first come/first +There are several possible scheduling disciplines (first come/first served, priority, weighted fair, weighted round-robin, deadline-based, -rate-based). INET contains implementation of priority and weighted +rate-based). INET contains an implementation of priority and weighted round-robin schedulers. .. _ug:sec:diffserv:priority-scheduler: @@ -313,16 +313,16 @@ Priority Scheduler ^^^^^^^^^^^^^^^^^^ The :ned:`PriorityScheduler` module implements a strict priority -scheduler. Packets that arrived on :gate:`in[0]` has the highest -priority, then packets arrived on :gate:`in[1]`, and so on. If more -packets available when one is requested, then the one with highest -priority is chosen. Packets with lower priority are transmitted only -when there are no packets on the inputs with higher priorities. +scheduler. Packets that arrive on :gate:`in[0]` have the highest +priority, then packets that arrive on :gate:`in[1]`, and so on. If +multiple packets are available when one is requested, then the one with +the highest priority is chosen. Packets with lower priority are +transmitted only when there are no packets on the inputs with higher priorities. -:ned:`PriorityScheduler` must be used with care, because a large volume -of higher packets can starve lower priority packets. Therefore it is -necessary to limit the rate of higher priority packets to a fraction of -the output datarate. +:ned:`PriorityScheduler` must be used with care because a large volume +of higher priority packets can starve lower priority packets. Therefore, +it is necessary to limit the rate of higher priority packets to a fraction of +the output data rate. :ned:`PriorityScheduler` can be used to implement the ``EF`` PHB. @@ -333,23 +333,23 @@ The :ned:`WrrScheduler` module implements a weighted round-robin scheduler. The scheduler visits the input gates in turn and selects the number of packets for transmission based on their weight. -For example if the module has three input gates, and the weights are 3, +For example, if the module has three input gates and the weights are 3, 2, and 1, then packets are transmitted in this order: :: A, A, A, B, B, C, A, A, A, B, B, C, ... -where A packets arrived on :gate:`in[0]`, B packets on :gate:`in[1]`, -and C packets on :gate:`in[2]`. If there are no packets in the current -one when a packet is requested, then the next one is chosen that has -enough tokens. +where A denotes packets that arrived on :gate:`in[0]`, B denotes packets +that arrived on :gate:`in[1]`, and C denotes packets that arrived on +:gate:`in[2]`. If there are no packets in the current one when a packet +is requested, then the next one is chosen if it has enough tokens. -If the size of the packets are equal, then :ned:`WrrScheduler` divides -the available bandwith according to the weights. In each case, it -allocates the bandwith fairly. Each flow receives a guaranteed minimum -bandwith, which is ensured even if other flows exceed their share (flow -isolation). It is also efficiently uses the channel, because if some +If the sizes of the packets are equal, then :ned:`WrrScheduler` divides +the available bandwidth according to the weights. In each case, it +allocates the bandwidth fairly. Each flow receives a guaranteed minimum +bandwidth, which is ensured even if other flows exceed their share (flow +isolation). It also efficiently uses the channel because if some traffic is smaller than its share of bandwidth, then the rest is allocated to the other flows. @@ -361,7 +361,7 @@ Classifiers ~~~~~~~~~~~ Classifier modules have one input and many output gates. They examine -the received packets, and forward them to the appropriate output gate +the received packets and forward them to the appropriate output gate based on the content of some portion of the packet header. You can read more about classifiers in RFC 2475 and RFC 3290. @@ -375,45 +375,43 @@ Multi-field Classifier The :ned:`MultiFieldClassifier` module can be used to identify micro-flows in the incoming traffic. The flow is identified by the -source and destination addresses, the protocol id, and the source and +source and destination addresses, the protocol ID, and the source and destination ports of the IP packet. The classifier can be configured by specifying a list of filters. Each -filter can specify a source/destination address mask, protocol, -source/destination port range, and bits of TypeOfService/TrafficClass +filter can specify a source/destination address mask, a protocol, +a source/destination port range, and bits of the TypeOfService/TrafficClass field to be matched. They also specify the index of the output gate -matching packet should be forwarded to. The first matching filter -determines the output gate, if there are no matching filters, then +to which matching packets should be forwarded. The first matching filter +determines the output gate; if there are no matching filters, then :gate:`defaultOut` is chosen. The configuration of the module is given as an XML document. The -document element must contain a list of ```` elements. The -filter element has a mandatory ``@gate`` attribute that gives the -index of the gate for packets matching the filter. Other attributes are -optional and specify the condition of matching: +document element must contain a list of ```` elements. Each +filter must have a mandatory ``@gate`` attribute specifying the index of +the output gate for packets matching the filter. Other attributes are +optional and specify the conditions for a match: - ``@srcAddress``, ``@srcPrefixLength``: to match the source - address of the IP + address of the IP. - ``@destAddress``, ``@destPrefixLength``: - ``@protocol``: matches the protocol field of the IP packet. Its - value can be a name (e.g. “udp”, “tcp”), or the numeric code of the + value can be a name (e.g., “udp”, “tcp”) or the numeric code of the protocol. -- ``@tos``,@tosMask: matches bits of the TypeOfService/TrafficClass +- ``@tos``, @tosMask: matches bits of the TypeOfService/TrafficClass field of the IP packet. - ``@srcPort``: matches the source port of the TCP or UDP packet. -- ``@srcPortMin``, ``@srcPortMax``: matches a range of source - ports. +- ``@srcPortMin``, ``@srcPortMax``: matches a range of source ports. - ``@destPort``: matches the destination port of the TCP or UDP packet. -- ``@destPortMin``, ``@destPortMax``: matches a range of - destination ports. +- ``@destPortMin``, ``@destPortMax``: matches a range of destination ports. The following example configuration specifies @@ -423,7 +421,7 @@ The following example configuration specifies - to transmit packets having CS7 in their DSCP field on gate 2, -- to transmit other packets on :gate:`defaultGate`. +- and to transmit other packets on :gate:`defaultGate`. @@ -439,16 +437,15 @@ Behavior Aggregate Classifier ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The :ned:`BehaviorAggregateClassifier` module can be used to read the -DSCP field from the IP datagram, and direct the packet to the +DSCP field from the IP datagram and direct the packet to the corresponding output gate. The DSCP value is the lower six bits of the TypeOfService/TrafficClass field. Core routers usually use this classifier to guide the packet to the appropriate queue. DSCP values are enumerated in the :par:`dscps` parameter. The first -value is for gate :gate:`out[0]`, the second for :gate:`out[1]`, so on. -If the received packet has a DSCP value not enumerated in the -:par:`dscps` parameter, it will be forwarded to the :gate:`defaultOut` -gate. +value is for gate :gate:`out[0]`, the second for :gate:`out[1]`, and so on. +If the received packet has a DSCP value that is not enumerated in the +:par:`dscps` parameter, it will be forwarded to the :gate:`defaultOut` gate. .. _ug:sec:diffserv:meters: @@ -457,99 +454,99 @@ Meters Meters classify the packets based on the temporal characteristics of their arrival. The arrival rate of packets is compared to an allowed -traffic profile, and packets are decided to be green (in-profile) or red -(out-of-profile). Some meters apply more than two conformance level, -e.g. in three color meters the partially conforming packets are +traffic profile, and packets are either marked as green (in-profile) or +red (out-of-profile). Some meters apply more than two conformance levels. +For example, in three-color meters, packets that partially conform are classified as yellow. The allowed traffic profile is usually specified by a token bucket. In -this model, a bucket is filled in with tokens with a specified rate, -until it reaches its maximum capacity. When a packet arrives, the bucket -is examined. If it contains at least as many tokens as the length of the -packet, then that tokens are removed, and the packet marked as -conforming to the traffic profile. If the bucket contains less tokens -than needed, it left unchanged, but the packet marked as non-conforming. - -Meters has two modes: color-blind and color-aware. In color-blind mode, -the color assigned by a previous meter does not affect the -classification of the packet in subsequent meters. In color-aware mode, -the color of the packet can not be changed to a less conforming color: -if a packet is classified as non-conforming by a meter, it also handled -as non-conforming in later meters in the data path. - - +this model, a bucket is filled with tokens at a specified rate until it +reaches its maximum capacity. When a packet arrives, the bucket is +examined. If it contains at least as many tokens as the length of the +packet, then those tokens are removed, and the packet is marked as +conforming to the traffic profile. If the bucket contains fewer tokens +than needed, it is left unchanged, but the packet is marked as +non-conforming. + +Meters have two modes: color-blind and color-aware. In color-blind mode, +the color assigned by a previous meter does not affect the classification +of the packet in subsequent meters. In color-aware mode, the color of the +packet cannot be changed to a less conforming color. If a packet is +classified as non-conforming by any meter, it is also handled as +non-conforming in subsequent meters in the data path. .. important:: - Meters take into account the length of the IP packet only, L2 headers are omitted - from the length calculation. If they receive a packet which is not + Meters take into account the length of the IP packet only; L2 headers are omitted + from the length calculation. If they receive a packet that is not an IP datagram and does not encapsulate an IP datagram, an error occurs. TokenBucketMeter ^^^^^^^^^^^^^^^^ The :ned:`TokenBucketMeter` module implements a simple token bucket -meter. The module has two output, one for green packets, and one for red +meter. The module has two outputs: one for green packets and one for red packets. When a packet arrives, the gained tokens are added to the bucket, and the number of tokens equal to the size of the packet are subtracted. -Packets are classified according to two parameters, Committed -Information Rate (:math:`cir`), Committed Burst Size (:math:`cbs`), to -be either green, or red. +Packets are classified according to two parameters: Committed +Information Rate (:math:`cir`) and Committed Burst Size (:math:`cbs`), +as either green or red. -Green traffic is guaranteed to be under :math:`cir*(t_1-t_0)+8*cbs` in +Green traffic is guaranteed to be under :math:`cir \cdot (t_1 - t_0) + 8 \cdot cbs` in every :math:`[t_0,t_1]` interval. SingleRateThreeColorMeter ^^^^^^^^^^^^^^^^^^^^^^^^^ The :ned:`SingleRateThreeColorMeter` module implements a Single Rate -Three Color Meter (RFC 2697). The module has three output for green, +Three Color Meter (RFC 2697). The module has three outputs: green, yellow, and red packets. -Packets are classified according to three parameters, Committed +Packets are classified according to three parameters: Committed Information Rate (:math:`cir`), Committed Burst Size (:math:`cbs`), and -Excess Burst Size (:math:`ebs`), to be either green, yellow or red. The -green traffic is guaranteed to be under :math:`cir*(t_1-t_0)+8*cbs`, -while the green+yellow traffic to be under -:math:`cir*(t_1-t_0)+8*(cbs+ebs)` in every :math:`[t_0,t_1]` interval. +Excess Burst Size (:math:`ebs`), as either green, yellow, or red. The +green traffic is guaranteed to be under :math:`cir \cdot (t_1 - t_0) + 8 \cdot cbs` +while the green+yellow traffic is guaranteed to be under +:math:`cir \cdot (t_1 - t_0) + 8 \cdot (cbs + ebs)` in every :math:`[t_0,t_1]` interval. TwoRateThreeColorMeter ^^^^^^^^^^^^^^^^^^^^^^ The :ned:`TwoRateThreeColorMeter` module implements a Two Rate Three -Color Meter (RFC 2698). The module has three output gates for the green, +Color Meter (RFC 2698). The module has three output gates for green, yellow, and red packets. -It classifies the packets based on two rates, Peak Information Rate -(:math:`pir`) and Committed Information Rate (:math:`cir`), and their -associated burst sizes (:math:`pbs` and :math:`cbs`) to be either green, -yellow or red. The green traffic is under :math:`pir*(t_1-t_0)+8*pbs` -and :math:`cir*(t_1-t_0)+8*cbs`, the yellow traffic is under -:math:`pir*(t_1-t_0)+8*pbs` in every :math:`[t_0,t_1]` interval. +It classifies packets based on two rates: Peak Information Rate +(:math:`pir`) and Committed Information Rate (:math:`cir`) and their +associated burst sizes (:math:`pbs` and :math:`cbs`), as either green, +yellow, or red. The green traffic is guaranteed to be under +:math:`pir \cdot (t_1 - t_0) + 8 \cdot pbs` and :math:`cir \cdot (t_1 - t_0) + 8 \cdot cbs`, +the yellow traffic is guaranteed to be under +:math:`pir \cdot (t_1 - t_0) + 8 \cdot pbs` in every :math:`[t_0,t_1]` interval. .. _ug:sec:diffserv:markers: Markers ~~~~~~~ -DSCP markers sets the codepoint of the crossing packets. The codepoint +DSCP markers set the codepoint of the crossing packets. The codepoint determines the further processing of the packet in the router or in the core of the DiffServ domain. -The :ned:`DscpMarker` module sets the DSCP field (lower six bit of +The :ned:`DscpMarker` module sets the DSCP field (lower six bits of TypeOfService/TrafficClass) of IP datagrams to the value specified by -the :par:`dscps` parameter. The :par:`dscps` parameter is a space -separated list of codepoints. You can specify a different value for each -input gate; packets arrived at the :math:`i^{th}` input gate are marked -with the :math:`i^{th}` value. If there are fewer values, than gates, -then the last one is used for extra gates. +the :par:`dscps` parameter. The :par:`dscps` parameter is a space-separated +list of codepoints. You can specify a different value for each input gate: +packets arrived at the :math:`i^{th}` input gate are marked with the +:math:`i^{th}` value. If there are fewer values than gates, the last one +is used for extra gates. The DSCP values are enumerated in the :file:`DSCP.msg` file. You can use both names and integer values in the :par:`dscps` parameter. -For example the following lines are equivalent: +For example, the following lines are equivalent: @@ -560,7 +557,7 @@ For example the following lines are equivalent: .. _ug:sec:diffserv:compound-modules: -Compound modules +Compound Modules ---------------- .. _ug:sec:diffserv:afxyqueue: @@ -568,10 +565,10 @@ Compound modules AFxyQueue ~~~~~~~~~ -The :ned:`AFxyQueue` module is an example queue, that implements one +The :ned:`AFxyQueue` module is an example queue that implements one class of the Assured Forwarding PHB group (RFC 2597). -Packets with the same AFx class, but different drop priorities arrive at +Packets with the same AFx class but different drop priorities arrive at the :gate:`afx1In`, :gate:`afx2In`, and :gate:`afx3In` gates. The received packets are stored in the same queue. Before the packet is enqueued, a RED dropping algorithm may decide to selectively drop them, @@ -584,28 +581,29 @@ equal probability than packets with higher drop priorities. .. _ug:sec:diffserv:diffservqeueue: -DiffservQeueue -~~~~~~~~~~~~~~ +DiffservQueue +~~~~~~~~~~~~~ -The :ned:`DiffservQueue` is an example queue, that can be used in -interfaces of DS core and edge nodes to support the AFxy (RFC 2597) and -EF (RFC 3246) PHB’s. +The :ned:`DiffservQueue` is an example queue that can be used in +interfaces of DiffServ core and edge nodes to support the AFxy (RFC 2597) +and EF (RFC 3246) PHBs. .. figure:: figures/DiffservQueue.* :align: center :scale: 70 % The incoming packets are first classified according to their DSCP field. -DSCP’s other than AFxy and EF are handled as BE (best effort). +DSCP values other than AFxy and EF are handled as best effort (BE). -EF packets are stored in a dedicated queue, and served first when a +EF packets are stored in a dedicated queue and served first when a packet is requested. Because they can preempt the other queues, the rate -of the EF packets should be limited to a fraction of the bandwith of the +of the EF packets should be limited to a fraction of the bandwidth of the link. This is achieved by metering the EF traffic with a token bucket -meter and dropping packets that does not conform to the traffic profile. +meter and dropping packets that do not conform to the traffic profile. There are other queues for AFx classes and BE. The AFx queues use RED to -implement 3 different drop priorities within the class. BE packets are +implement three different drop priorities within the class. BE packets are stored in a drop tail queue. Packets from AFxy and BE queues are scheduled by a WRR scheduler, which ensures that the remaining bandwidth is allocated among the classes according to the specified weights. + diff --git a/doc/src/users-guide/ch-emulation.rst b/doc/src/users-guide/ch-emulation.rst index db62f7c19c0..69a6e602c2a 100644 --- a/doc/src/users-guide/ch-emulation.rst +++ b/doc/src/users-guide/ch-emulation.rst @@ -21,10 +21,10 @@ model. relies on network communication is often less expensive, more practical, and safer using simulation than directly performing experiments in the real world. However, there are potential pitfalls: porting simulation code to the target device - may be costly and error prone, and also, a model that performs well in simulation + may be costly and error-prone, and also, a model that performs well in simulation does not necessarily work equally well when deployed in the real world. - INET helps reducing these risks by allowing the researcher to mix - simulation and real world in various ways, thereby reducing the need for porting, + INET helps reduce these risks by allowing the researcher to mix + simulation and the real world in various ways, thereby reducing the need for porting, and offering more possibilities for testing out the code. .. There are several projects that may benefit from the network emulation @@ -32,14 +32,14 @@ model. components with real networks. **todo** not just networks INET provides modules that act as bridges between the -simulated and real domains, therefore it is possible to leave one part +simulated and real domains; therefore, it is possible to leave one part of the simulation unchanged, while simply extracting the other into the real world. Several setups are possible when one can take advantage of the emulation capabilities of INET: - simulated node in a real network -- a simulated subnet in real network -- real-world node in simulated network +- a simulated subnet in a real network +- real-world node in a simulated network - simulated protocol in a real network node - real application in a simulated network node - etc. @@ -54,13 +54,13 @@ Some example scenarios: counterparts. .. Several setups are possible: simulated node in a real - network; a simulated subnet in real network; real-world node in + network; a simulated subnet in a real network; real-world node in simulated network; etc. - As a means of implementing hybrid simulation. The real network (or a single host OS) may contain several network emulator devices or simulations running in emulation mode. Such a setup provides a - relatively easy way for connecting heterogenous simulators/emulators + relatively easy way of connecting heterogeneous simulators/emulators with each other, sparing the need for HLA or a custom interoperability solution. @@ -73,7 +73,7 @@ For the simulation to act as a network emulator, two major problems need to be s On one hand, the simulation must run in real time, or the real clock must be configured according to the simulation time (synchronization). On the other hand, the simulation must be able to communicate with the real -world (communication). This is achieved in INET as the following: +world (communication). This is achieved in INET as follows: - Synchronization: @@ -81,11 +81,11 @@ world (communication). This is achieved in INET as the following: scheduler class responsible for synchronization. Using this method, the simulation is run according to real time. -- Communication: +- Communication: - The interface between the real (an interface of the OS) and the - simulated parts of the model are represented by `Ext` modules, - with names beginning with ``Ext~`` prefix in the + simulated parts of the model is represented by `Ext` modules, + with names beginning with the ``Ext~`` prefix in the simulation (``ExtLowerUdp``, ``ExtUpperEthernetInterface``, etc.). @@ -144,7 +144,7 @@ changed in the *Project \| Project Features...* dialog in the IDE.) (type ``SOCK_RAW``), which, on many systems, is only allowed for processes that have root (administrator) privileges. -Also, in order to be able to send packets through raw sockets +Also, in order to be able to send packets through raw sockets, applications require special permissions. There are two ways to achieve this under Linux. @@ -159,7 +159,7 @@ permissions: This solution makes running the examples from the IDE possible. Alternatively, the application can be started with root privileges from -command line: +the command line: .. code:: @@ -168,7 +168,7 @@ command line: .. note:: In any case, it's generally a bad idea to start the IDE as superuser. Doing so may silently change the file ownership for certain IDE - configuration files, and it may prevent the IDE to start up for the + configuration files, and it may prevent the IDE from starting up for the normal user afterwards. .. _ug:sec:emulation:configuring: @@ -199,14 +199,14 @@ following way: **.host1.numEthInterfaces = 1 **.host1.eth[0].typename = "ExtLowerEthernetInterface" -Also, the simulation must be configured to run under control the of the +Also, the simulation must be configured to run under the control of the appropriate real-time scheduler class: .. code-block:: ini scheduler-class = "inet::RealTimeScheduler" -:ned:`ExtLowerEthernetInterface` has two important parameters which need +:ned:`ExtLowerEthernetInterface` has two important parameters that need to be configured. The :par:`device` parameter should be set to the name of the real (or virtual) interface on the host OS. The :par:`namespace` parameter can be set to utilize the network namespace functionality of @@ -223,7 +223,7 @@ An example configuration: .. .. note:: -Let us examine the paths outgoing and incoming packets take, and the +Let us examine the paths outgoing and incoming packets take and the necessary configuration requirements to make them work. We assume IPv4 as network layer protocol, but the picture does not change much with other protocols. We assume the external interface is named @@ -237,7 +237,7 @@ The network layer of the simulated node routes datagrams to its For that to happen, the routing table needs to contain an entry where the interface is set to ``eth[0]``. Such entries are not created -automatically, one needs to add them to the routing table explicitly, +automatically; one needs to add them to the routing table explicitly, e.g. by using an :ned:`Ipv4NetworkConfigurator` and an appropriate XML file. @@ -266,12 +266,13 @@ Incoming path First of all, packets intended to be received by the simulation need to find their way to the correct interface of the host that runs the simulation. For that, IP addresses of simulated hosts must be routable -in the real network, and routed to the selected interface of the host +in the real network and routed to the selected interface of the host OS. (On Linux, for example, this can be achieved by adding static routes with the command.) As packets are received by the interface of the host OS, they are handed over to the simulation. The packets are received from the raw socket with a -``recv`` system call. After deserialization they pop out of ``eth[0]`` and +``recv`` system call. After deserialization, they pop out of ``eth[0]`` and they are sent up to the network layer. The packets are routed to the simulated destination host in the normal way. + diff --git a/doc/src/users-guide/ch-environment.rst b/doc/src/users-guide/ch-environment.rst index dc68a7be2b1..17159432129 100644 --- a/doc/src/users-guide/ch-environment.rst +++ b/doc/src/users-guide/ch-environment.rst @@ -42,7 +42,7 @@ PhysicalEnvironment In INET, the physical environment is modeled by the :ned:`PhysicalEnvironment` compound module. This module normally has one -instance in the network, and acts as a database that other parts of the +instance in the network and acts as a database that other parts of the simulation can query at runtime. It contains the following information: - geometry and properties of *physical objects* (usually referred to @@ -58,7 +58,7 @@ an associated C++ class that contains the data structures and implements an API that allows other modules to query the data. Part of :ned:`PhysicalEnvironment`’s functionality is implemented in -submodules for easy replacement. They are currently the ground model, +submodules for easy replacement. They are currently the ground model and an object cache (for efficient queries): @@ -74,12 +74,12 @@ Physical Objects ---------------- The most important aspect of the physical environment is the objects -which are present in it. For example, simulating an indoor Wifi scenario +that are present in it. For example, simulating an indoor Wifi scenario may need to model walls, floors, ceilings, doors, windows, furniture, -and similar objects, because they all affect signal propagation +and similar objects because they all affect signal propagation (obstacle modeling). -Objects are located in space, and have shapes and materials. The +Objects are located in space and have shapes and materials. The physical environment model supports basic shapes and homogeneous materials, which is a simplified description but still allows for a reasonable approximation of reality. Physical objects in INET have the @@ -93,7 +93,7 @@ following properties: - *orientation* determines how the object is rotated relative to its default orientation. -- *material* describes material specific physical properties. +- *material* describes material-specific physical properties. - *graphical properties* provide parameters for better visualization. @@ -109,7 +109,7 @@ Graphical properties include: - *tags*: allows filtering objects on the graphical user interface -Physical objects in INET are stationary, they cannot change their +Physical objects in INET are stationary; they cannot change their position or orientation over time. Since the shape of the physical objects might be quite diverse, the model is designed to be extensible with new shapes. INET provides the following shapes: @@ -148,21 +148,21 @@ be used: Ground Models ------------- -In inter-vehicle simulations the terrain has profound effects on signal +In inter-vehicle simulations, the terrain has profound effects on signal propagation. For example, vehicles on the opposite sides of a mountain cannot directly communicate with each other. A ground model describes the 3D surface of the terrain. Its main purpose -is to compute a position on the surface underneath an particular +is to compute a position on the surface underneath a particular position. INET contains the following built-in ground models implemented as OMNeT++ simple modules: -- :ned:`FlatGround` is a trivial model which provides a flat surface +- :ned:`FlatGround` is a trivial model that provides a flat surface parallel to the XY plane at a certain height. -- :ned:`OsgEarthGround` is a more realistic model (based on ) which +- :ned:`OsgEarthGround` is a more realistic model (based on ) that provides a terrain surface. .. _ug:sec:environment:geographic-coordinate-system-models: @@ -170,8 +170,8 @@ OMNeT++ simple modules: Geographic Coordinate System Models ----------------------------------- -In order to run high fidelity simulations, it is often required to embed -the communication network into a real world map. With the new OMNeT++ 5 +In order to run high-fidelity simulations, it is often required to embed +the communication network into a real-world map. With the new OMNeT++ 5 version, INET already provides support for 3D maps using for visualization and as the map provider. @@ -184,7 +184,7 @@ resolved. A geographic coordinate system model maps scene coordinates to geographic coordinates, and vice versa. Such a model allows positioning physical objects and describing network node mobility using geographical -coordinates (e.g longitude, latitude, altitude). +coordinates (e.g., longitude, latitude, altitude). In INET, a geographic coordinate system model is implemented as an OMNeT++ simple module: @@ -221,7 +221,7 @@ propagation may become computationally very expensive. The reason is that the transmission medium model must check each line of sight path between all transmitter and receiver pairs against all physical objects. -An object cache organizes physical objects into a data structure which +An object cache organizes physical objects into a data structure that provides efficient geometric queries. Its main purpose is to iterate all physical objects penetrated by a 3D line segment. diff --git a/doc/src/users-guide/ch-ethernet.rst b/doc/src/users-guide/ch-ethernet.rst index d7cf2c8f900..f34f7907639 100644 --- a/doc/src/users-guide/ch-ethernet.rst +++ b/doc/src/users-guide/ch-ethernet.rst @@ -11,7 +11,7 @@ Overview Ethernet is the most popular wired LAN technology nowadays, and its use is also growing in metropolitan area and wide area networks. Since its introduction in 1980, Ethernet data transfer rates have increased from -the original 10Mb/s to the latest 400Gb/s. Originally, The technology +the original 10Mb/s to the latest 400Gb/s. Originally, the technology has changed from using coaxial cables and repeaters to using unshielded twisted-pair cables with hubs and switches. Today, switched Ethernet is prevalent, and most links operate in full duplex mode. The INET @@ -19,7 +19,7 @@ Framework contains support for all major Ethernet technologies and device types. In Ethernet networks containing multiple switches, broadcast storms are -prevented by use of a spanning tree protocol (STP, RSTP) that disables +prevented by the use of a spanning tree protocol (STP, RSTP) that disables selected links to eliminate cycles from the topology. Ethernet switch models in INET contain support for STP and RSTP. @@ -31,16 +31,15 @@ Nodes There are several node models that can be used in an Ethernet network: - Node models such as :ned:`StandardHost` and :ned:`Router` are - Ethernet-capable + Ethernet-capable. - :ned:`EthernetSwitch` models an Ethernet switch, i.e. a multiport - bridging device + bridging device. -- :ned:`WireJunction` can models the coaxial cable (10BASE2 or 10BASE5 network - segments) on legacy Ethernet networks, or an Ethernet hub/multiport repeater +- :ned:`WireJunction` can model the coaxial cable (10BASE2 or 10BASE5 network segments) on legacy Ethernet networks, or an Ethernet hub/multiport repeater. -- :ned:`EthernetHost` is a sample node which can be used to generate “raw” - Ethernet traffic +- :ned:`EthernetHost` is a sample node which can be used to generate "raw" + Ethernet traffic. .. _ug:sec:ethernet:etherswitch: @@ -58,15 +57,15 @@ CSMA/CD is not needed and the channel utilization can be high. The :par:`duplexMode` parameters of the MACs must be set according to the medium connected to the port; if collisions are possible (it’s a bus -or hub) it must be set to false, otherwise it can be set to true. By -default it uses half-duplex MAC with CSMA/CD. +or hub) it must be set to false, otherwise, it can be set to true. By +default, it uses a half-duplex MAC with CSMA/CD. .. _ug:sec:ethernet:etherhub: Ethernet Hub ~~~~~~~~~~~~ -The :ned:`WireJunction` can model an Ethernet hub. Ethernet hubs are a simple +The :ned:`WireJunction` can model an Ethernet hub. Ethernet hubs are simple broadcast devices. Messages arriving on a port are regenerated and broadcast to every other port. @@ -93,8 +92,8 @@ all connected channels must have the same speed. The Physical Layer ------------------ -Stations on an Ethernet networks are connected by coaxial, twisted pair -or fibre cables. (Coaxial only has historical importance, but is +Stations on Ethernet networks are connected by coaxial, twisted pair +or fiber cables. (Coaxial only has historical importance, but is supported by INET anyway.) There are several cable types specified in the standard. @@ -122,6 +121,7 @@ There is currently no support for 200Gbps and 400Gbps Ethernet. :ned:`Eth10M`, :ned:`Eth100M`, :ned:`Eth1G`, :ned:`Eth10G`, :ned:`Eth40G`, :ned:`Eth100G` + .. _ug:sec:ethernet:ethernet-interface: Ethernet Interface @@ -135,12 +135,12 @@ similarly to the :ned:`PppInterface` module. The Ethernet MAC (Media Access Control) layer transmits the Ethernet frames on the physical media. This is a sublayer within the data link -layer. Because encapsulation/decapsulation is not always needed (e.g. -switches does not do encapsulation/decapsulation), it is implemented in -a separate modules (e.g. :ned:`EthernetEncapsulation`) that are part +layer. Because encapsulation/decapsulation is not always needed (e.g., +switches do not do encapsulation/decapsulation), it is implemented in +separate modules (e.g., :ned:`EthernetEncapsulation`) that are part of the LLC layer. -Nowadays almost all Ethernet networks operate using full-duplex +Nowadays, almost all Ethernet networks operate using full-duplex point-to-point connections between hosts and switches. This means that there are no collisions, and the behavior of the MAC component is much simpler than in classic Ethernet that used coaxial cables and hubs. The @@ -148,7 +148,7 @@ INET framework contains two MAC modules for Ethernet: the :ned:`EthernetMac` is simpler to understand and easier to extend, because it supports only full-duplex connections. The :ned:`EthernetCsmaMac` module implements the full MAC functionality including CSMA/CD, it can -operate both half-duplex and full-duplex mode. +operate in both half-duplex and full-duplex mode. .. _ug:sec:ethernet:components: @@ -174,11 +174,11 @@ The following components are present in the model: EthernetMac ~~~~~~~~~~~ -From the two MAC implementation :ned:`EthernetMac` is the simpler +From the two MAC implementations, :ned:`EthernetMac` is the simpler one, it operates only in full-duplex mode (its :par:`duplexEnabled` parameter fixed to ``true`` in its NED definition). This module does not need to implement CSMA/CD, so there is no collision detection, -retransmission with exponential backoff, carrier extension and frame +retransmission with exponential backoff, carrier extension, and frame bursting. .. _ug:sec:ethernet:ethermac: @@ -187,10 +187,10 @@ EthernetCsmaMac ~~~~~~~~~~~~~~~ Ethernet MAC layer implementing CSMA/CD. It supports both half-duplex -and full-duplex operations; in full-duplex mode it behaves as -:ned:`EthernetMac`. In half-duplex mode it detects collisions, -sends jam messages and retransmit frames upon collisions using the -exponential backoff algorithm. In Gigabit Ethernet networks it supports +and full-duplex operations; in full-duplex mode, it behaves as +:ned:`EthernetMac`. In half-duplex mode, it detects collisions, +sends jam messages, and retransmits frames upon collisions using the +exponential backoff algorithm. In Gigabit Ethernet networks, it supports carrier extension and frame bursting. Carrier extension can be turned off by setting the :par:`carrierExtension` parameter to ``false``. @@ -207,20 +207,20 @@ encapsulation/decapsulation. MacRelayUnit ~~~~~~~~~~~~ -INET framework ethernet switches are built from :ned:`IMacRelayUnit` +INET framework Ethernet switches are built from :ned:`IMacRelayUnit` components. Each relay unit has N input and output gates for sending/receiving Ethernet frames. They should be connected to :ned:`EthernetInterface` modules. The relay unit holds a table for the destination address -> output port mapping in a :ned:`MacForwardingTable` module. When the relay unit receives -a data frame, it updates the table with the source address->input port. +a data frame, it updates the table with the source address -> input port. If the destination address is not found in the table, the frame is -broadcast. The frame is not sent to the same port it was received from, +broadcasted. The frame is not sent to the same port it was received from, because then the target should already have received the original frame. -A simple scheme for sending PAUSE frames is built in (although users +A simple scheme for sending PAUSE frames is built-in (although users will probably change it). When the buffer level goes above a high watermark, PAUSE frames are sent on all ports. The watermark and the pause time is configurable; use zero values to disable the PAUSE @@ -235,11 +235,11 @@ The :ned:`MacForwardingTable` module stores the mapping between ports and MAC addresses. Entries are deleted if their age exceeds a certain limit. If needed, address tables can be pre-loaded from text files at the -beginning of the simulation; this controlled by the +beginning of the simulation; this is controlled by the :par:`forwardingTableFile` module parameter. In the file, each line contains a literal 0 (reserved for VLAN id), a hexadecimal MAC address and a decimal port number, separated by tabs. Comment lines beginning -with ’#’ are also allowed: +with "#" are also allowed: :: @@ -256,7 +256,7 @@ Ieee8021dRelay ~~~~~~~~~~~~~~ :ned:`Ieee8021dRelay` is a MAC relay unit that should be used instead of -:ned:`MacRelayUnit` that when STP or RSTP is needed. +:ned:`MacRelayUnit` when STP or RSTP is needed. .. _ug:sec:ethernet:stp: @@ -269,7 +269,7 @@ Ethernet networks. The basic function of STP is to prevent bridge loops and the broadcast radiation that results from them. STP creates a spanning tree within a network of connected layer-2 -bridges, and disables those links that are not part of the spanning +bridges and disables those links that are not part of the spanning tree, leaving a single active path between any two network nodes. .. _ug:sec:ethernet:rstp: diff --git a/doc/src/users-guide/ch-history.rst b/doc/src/users-guide/ch-history.rst index c7b7f709311..ee84b44db3b 100644 --- a/doc/src/users-guide/ch-history.rst +++ b/doc/src/users-guide/ch-history.rst @@ -10,46 +10,46 @@ IPSuite to INET Framework (2000-2006) The predecessor of the INET framework was written by Klaus Wehrle, Jochen Reber, Dirk Holzhausen, Volker Boehm, Verena Kahmann, Ulrich -Kaage and others at the University of Karlsruhe during 2000-2001, under +Kaage, and others at the University of Karlsruhe during 2000-2001, under the name IPSuite. -The MPLS, LDP and RSVP-TE models were built as an add-on to IPSuite +The MPLS, LDP, and RSVP-TE models were built as an add-on to IPSuite during 2003 by Xuan Thang Nguyen (Xuan.T.Nguyen@uts.edu.au) and other -students at the University of Technology, Sydney under supervision of Dr -Robin Brown. The package consisted of around 10,000 LOCs, and was -published at http://charlie.it.uts.edu.au/ tkaphan/xtn/capstone (now +students at the University of Technology, Sydney under the supervision of Dr. +Robin Brown. The package consisted of around 10,000 LOCs and was +published at http://charlie.it.uts.edu.au/tkaphan/xtn/capstone (now unavailable). After a period of IPSuite being unmaintained, Andras Varga took over the development in July 2003. Through a series of snapshot releases in -2003-2004, modules got completely reorganized, documented, and many of -them rewritten from scratch. The MPLS models (including RSVP-TE, LDP, -etc) also got refactored and merged into the codebase. +2003-2004, modules were completely reorganized, documented, and many of +them were rewritten from scratch. The MPLS models (including RSVP-TE, LDP, +etc.) were also refactored and merged into the codebase. During 2004, Andras added a new, modular and extensible TCP -implementation, application models, Ethernet implementation and an +implementation, application models, Ethernet implementation, and an all-in-one IP model to replace the earlier, modularized one. The package was renamed INET Framework in October 2004. -Support for wireless and mobile networks got added during summer 2005 by +Support for wireless and mobile networks was added during the summer of 2005 by using code from the Mobility Framework. -The MPLS models (including LDP and RSVP-TE) got revised and mostly +The MPLS models (including LDP and RSVP-TE) were revised and mostly rewritten from scratch by Vojta Janota in the first half of 2005 for his -diploma thesis. After further refinements by Vojta, the new code got -merged into the INET CVS in fall 2005, and got eventually released in +diploma thesis. After further refinements by Vojta, the new code was +merged into the INET CVS in fall 2005 and eventually released in the March 2006 INET snapshot. The OSPFv2 model was created by Andras Babos during 2004 for his diploma -thesis which was submitted early 2005. This work was sponsored by Andras +thesis, which was submitted early 2005. This work was sponsored by Andras Varga, using revenues from commercial OMNEST licenses. After several -refinements and fixes, the code got merged into the INET Framework in -2005, and became part of the March 2006 INET snapshot. +refinements and fixes, the code was merged into the INET Framework in +2005 and became part of the March 2006 INET snapshot. The Quagga routing daemon was ported into the INET Framework also by -Vojta Janota. This work was also sponsored by Andras Varga. During fall -2005 and the months after, ripd and ospfd were ported, and the +Vojta Janota. This work was also sponsored by Andras Varga. During the fall +of 2005 and the months after, ripd and ospfd were ported, and the methodology of porting was refined. Further Quagga daemons still remain to be ported. @@ -58,19 +58,19 @@ at CTIE, Monash University, Melbourne) and IPv6SuiteWithINET (Andras’s effort to refactor IPv6Suite and merge it with INET early 2005), Wei Yang Ng (Monash Uni) implemented a new IPv6 model from scratch for the INET Framework in 2005 for his diploma thesis, under guidance from -Andras who was visiting Monash between February and June 2005. This IPv6 -model got first included in the July 2005 INET snapshot, and gradually +Andras, who was visiting Monash between February and June 2005. This IPv6 +model was first included in the July 2005 INET snapshot and gradually refined afterwards. The SCTP implementation was contributed by Michael Tuexen, Irene -Ruengeler and Thomas Dreibholz +Ruengeler, and Thomas Dreibholz. Support for Sam Jensen’s Network Simulation Cradle, which makes -real-world TCP stacks available in simulations was added by Zoltan +real-world TCP stacks available in simulations, was added by Zoltan Bojthe in 2010. -TCP SACK and New Reno implementation was contributed by Thomas Reschka. +TCP SACK and New Reno implementation were contributed by Thomas Reschka. Several other people have contributed to the INET Framework by providing -feedback, reporting bugs, suggesting features and contributing patches; -I’d like to acknowledge their help here as well. +feedback, reporting bugs, suggesting features, and contributing patches; +I’d like to acknowledge their help here as well. \ No newline at end of file diff --git a/doc/src/users-guide/ch-instrument-figures.rst b/doc/src/users-guide/ch-instrument-figures.rst index 1995759c930..9ddd9f26f9b 100644 --- a/doc/src/users-guide/ch-instrument-figures.rst +++ b/doc/src/users-guide/ch-instrument-figures.rst @@ -11,7 +11,7 @@ Overview In complex simulations, there are usually several statistics that are vital for understanding what is happening inside the network. Although statistics can also be found and read in Qtenv's object inspector panel, it is often more -convenient to directly display them on the top-level canvas in a graphical form. +convenient to display them directly on the top-level canvas in a graphical form. INET supports such visualization in the form of inspector figures that display various gauges and meters. This chapter covers the usage of instrument figures. @@ -19,7 +19,7 @@ of instrument figures. Instrument Types ---------------- -Some of the instrument figure types available in INET are the following: +Some of the instrument figure types available in INET are as follows: - *gauge:* A circular gauge similar to a speedometer or pressure indicator. @@ -55,7 +55,7 @@ Some of the instrument figure types available in INET are the following: :width: 40% :align: center -- *plot:* An XY chart that plots a statistic in the function of time. +- *plot:* An XY chart that plots a statistic as a function of time. .. figure:: figures/instr_plot.png :align: center @@ -68,16 +68,16 @@ Instrument figures visualize statistics derived from signals emitted by modules in the network. This statistic is declared in the NED file, with the ``@statistic`` property. The property's ``source`` attribute is an expression that specifies which signals to use from which modules, and -the mathematical operations on it, to derive the statistic. The -``record`` attribute specifies where the values of the statistic is -recorded into. In the case of instrument figures, this is set to -``figure``, i.e. ``record=figure``. The ``targetFigure`` attribute +the mathematical operations on them, to derive the statistic. The +``record`` attribute specifies where the values of the statistic are +recorded. In the case of instrument figures, this is set to +``figure``, i.e., ``record=figure``. The ``targetFigure`` attribute selects which figure should display the statistic. The instrument figure itself is specified in the NED file with the ``@figure`` property. The property's ``type`` attribute selects -the type of the instrument figure (``gauge``, ``thermometer``, etc.), -and the property's index (i.e. the figure name) should match the +the type of instrument figure (``gauge``, ``thermometer``, etc.), +and the property's index (i.e., the figure name) should match the name given in the statistic's ``targetFigure`` attribute. Here is an example NED file: @@ -117,4 +117,4 @@ INET with the ``-h figures`` command-line option): ``progressMeter``: ``type``, ``visible``, ``zIndex``, ``tooltip``, ``tags``, ``transform``, ``backgroundColor``, ``stripColor``, ``cornerRadius``, ``borderWidth``, ``minValue``, ``maxValue``, ``text``, ``textFont``, ``textColor``, ``label``, ``labelOffset``, ``labelFont``, ``labelColor``, ``initialValue``, ``pos``, ``size``, ``anchor``, ``bounds`` ``thermometer``: - ``type``, ``visible``, ``zIndex``, ``tooltip``, ``tags``, ``transform``, ``mercuryColor``, ``label``, ``labelFont``, ``labelColor``, ``minValue``, ``maxValue``, ``tickSize``, ``initialValue``, ``pos``, ``size``, ``anchor``, ``bounds``, ``labelOffset`` + ``type``, ``visible``, ``zIndex``, ``tooltip``, ``tags``, ``transform``, ``mercuryColor``, ``label``, ``labelFont``, ``labelColor``, ``minValue``, ``maxValue``, ``tickSize``, ``initialValue``, ``pos``, ``size``, ``anchor``, ``bounds``, ``labelOffset`` \ No newline at end of file diff --git a/doc/src/users-guide/ch-introduction.rst b/doc/src/users-guide/ch-introduction.rst index 9ac838c816d..ad9dff77b02 100644 --- a/doc/src/users-guide/ch-introduction.rst +++ b/doc/src/users-guide/ch-introduction.rst @@ -8,23 +8,23 @@ Introduction What is INET Framework ---------------------- -INET Framework is an open-source model library for the OMNeT++ -simulation environment. It provides protocols, agents and other models +The INET Framework is an open-source model library for the OMNeT++ +simulation environment. It provides protocols, agents, and other models for researchers and students working with communication networks. INET -is especially useful when designing and validating new protocols, or +is especially useful when designing and validating new protocols or exploring new or exotic scenarios. INET supports a wide class of communication networks, including wired, -wireless, mobile, ad hoc and sensor networks. It contains models for the +wireless, mobile, ad hoc, and sensor networks. It contains models for the Internet stack (TCP, UDP, IPv4, IPv6, OSPF, BGP, etc.), link layer protocols (Ethernet, PPP, IEEE 802.11, various sensor MAC protocols, -etc), refined support for the wireless physical layer, MANET routing -protocols, DiffServ, MPLS with LDP and RSVP-TE signalling, several +etc.), refined support for the wireless physical layer, MANET routing +protocols, DiffServ, MPLS with LDP and RSVP-TE signaling, several application models, and many other protocols and components. It also provides support for node mobility, advanced visualization, network -emulation and more. +emulation, and more. -Several other simulation frameworks take INET as a base, and extend it +Several other simulation frameworks take INET as a base and extend it into specific directions, such as vehicular networks, overlay/peer-to-peer networks, or LTE. @@ -33,19 +33,19 @@ overlay/peer-to-peer networks, or LTE. Designed for Experimentation ---------------------------- -INET is built around the concept of modules that communicate by message +INET is built around the concept of modules that communicate through message passing. Agents and network protocols are represented by components, which can be freely combined to form hosts, routers, switches, and other networking devices. New components can be programmed by the user, and existing components have been written so that they are easy to understand and modify. -INET benefits from the infrastructure provided by OMNeT++. Beyond making +INET benefits from the infrastructure provided by OMNeT++. Besides making use of the services provided by the OMNeT++ simulation kernel and library (component model, parameterization, result recording, etc.), this also means that models may be developed, assembled, parameterized, run, and their results evaluated from the comfort of the OMNeT++ -Simulation IDE, or from the command line. +Simulation IDE or from the command line. INET Framework is maintained by the OMNeT++ team for the community, utilizing patches and new models contributed by members of the @@ -63,8 +63,8 @@ extend INET with new protocols or other components using C++, we recommend the *INET Developers Guide*.) This manual does not attempt to be a reference for INET. It concentrates -on conveying the big picture, and does not attempt to cover all -components, or try to document the parameters, gates, statistics or +on conveying the big picture and does not attempt to cover all +components or try to document the parameters, gates, statistics, or precise operation of individual components. For such information, users should refer to the *INET Reference*, a web-based cross-referenced documentation generated from NED and MSG files. diff --git a/doc/src/users-guide/ch-ipv4.rst b/doc/src/users-guide/ch-ipv4.rst index 71b17f20fc6..73f07431989 100644 --- a/doc/src/users-guide/ch-ipv4.rst +++ b/doc/src/users-guide/ch-ipv4.rst @@ -9,30 +9,30 @@ Overview -------- The IP protocol is the workhorse protocol of the TCP/IP protocol suite. -All UDP, TCP, ICMP packets are encapsulated into IP datagrams and -transported by the IP layer. While higher layer protocols transfer data -among two communication end-point, the IP layer provides an hop-by-hop, -unreliable and connectionless delivery service. IP does not maintain any -state information about the individual datagrams, each datagram handled +All UDP, TCP, and ICMP packets are encapsulated into IP datagrams and +transported by the IP layer. While higher-layer protocols transfer data +between two communication end-points, the IP layer provides a hop-by-hop, +unreliable, and connectionless delivery service. IP does not maintain any +state information about the individual datagrams; each datagram is handled independently. The nodes that are connected to the Internet can be either a host or a router. The hosts can send and receive IP datagrams, and their operating -system implements the full TCP/IP stack including the transport layer. -On the other hand, routers have more than one interface cards and -perform packet routing between the connected networks. Routers does not -need the transport layer, they work on the IP level only. The division -between routers and hosts is not strict, because if a host have several +system implements the full TCP/IP stack, including the transport layer. +On the other hand, routers have more than one interface card and +perform packet routing between the connected networks. Routers do not +need the transport layer; they work at the IP level only. The division +between routers and hosts is not strict because if a host has several interfaces, they can usually be configured to operate as a router too. Each node on the Internet has a unique IP address. IP datagrams contain the IP address of the destination. The task of the routers is to find -out the IP address of the next hop on the local network, and forward the -packet to it. Sometimes the datagram is larger, than the maximum -datagram that can be sent on the link (e.g. Ethernet has an 1500 bytes -limit.). In this case the datagram is split into fragments and each +out the IP address of the next hop on the local network and forward the +packet to it. Sometimes the datagram is larger than the maximum +datagram that can be sent on the link (e.g., Ethernet has a 1500-byte +limit). In this case, the datagram is split into fragments and each fragment is transmitted independently. The destination host must collect -all fragments, and assemble the datagram, before sending up the data to +all fragments and assemble the datagram before sending up the data to the transport layer. The INET framework contains several modules to build the IPv4 network @@ -44,7 +44,7 @@ layer of hosts and routers: - The :ned:`Ipv4RoutingTable` is a helper module that manages the routing table of the node. It is queried by the :ned:`Ipv4` module - for best routes, and updated by the routing daemons implementing RIP, + for best routes and updated by the routing daemons implementing RIP, OSPF, Manet, etc. protocols. - The :ned:`Icmp` module can be used to generate ICMP error packets. It @@ -53,12 +53,12 @@ layer of hosts and routers: - The :ned:`Arp` module performs the dynamic translation of IP addresses to MAC addresses. -- The :ned:`Igmpv2` module to generate and process multicast group +- The :ned:`Igmpv2` module generates and processes multicast group membership reports. These modules are assembled into a complete network layer module called :ned:`Ipv4NetworkLayer`. The :ned:`Ipv4NetworkLayer` module is present -e.g. in :ned:`StandardHost` and :ned:`Router`. +in :ned:`StandardHost` and :ned:`Router`. The subsequent sections describe the IPv4 modules in detail. @@ -84,7 +84,7 @@ Its parameters include: in the fragment buffer. - :par:`limitedBroadcast` if ``true``, then link-local broadcast - datagrams are sent out through each interface, if the higher layer + datagrams are sent out through each interface if the higher layer did not specify the outgoing interface. - :par:`useProxyARP` TODO: default(true); @@ -129,12 +129,12 @@ Icmp The :ned:`Icmp` module implements the Internet Control Message Protocol (ICMP). ICMP is the error reporting and diagnostic mechanism of the Internet. It uses the services of IP, so it is a transport layer -protocol, but unlike TCP or UDP it is not used to transfer user data. It -cannot be separated from IP, because the routing errors are reported by +protocol, but unlike TCP or UDP, it is not used to transfer user data. It +cannot be separated from IP because the routing errors are reported by ICMP. The :ned:`Icmp` module can be used to send error messages and ping -request. It can also respond to incoming ICMP messages. +requests. It can also respond to incoming ICMP messages. Each ICMP message is encapsulated within an IP datagram, so its delivery is unreliable. @@ -147,7 +147,7 @@ Arp The :ned:`Arp` module implements the Address Resolution Protocol (ARP). The ARP protocol is designed to translate a local protocol address to a hardware address. Although the ARP protocol can be used with several -network protocol and hardware addressing schemes, in practice they are +network protocols and hardware addressing schemes, in practice, they are almost always IPv4 and 802.3 addresses. The :ned:`Arp` module only supports IPv4-to-MAC address translation, but not the opposite direction, Reverse ARP (RARP). @@ -158,11 +158,11 @@ broadcast and multicast addresses (RFC 1122, 6.4); unicast addresses are resolved using the ARP protocol. If the MAC address is found in the ARP cache, then the packet is -transmitted to the addressed interface immediately. Otherwise the packet +transmitted to the addressed interface immediately. Otherwise, the packet is queued and an address resolution takes place. For address resolution, ARP broadcasts a request frame on the network. -In the request it publishes its own IP and MAC addresses, so each node +In the request, it publishes its own IP and MAC addresses so each node in the local subnet can update their mapping. The node whose MAC address was requested will respond with an ARP frame containing its own MAC address directly to the node that sent the request. When the original @@ -197,33 +197,33 @@ routers on IPv4 networks to establish multicast group memberships. IGMP is an integral part of IP multicast. IGMP is responsible for distributing the information of multicast group -memberships from hosts to routers. When an interface of a host joins to -a multicast group, it will send an IGMP report on that interface to +memberships from hosts to routers. When an interface of a host joins a +multicast group, it will send an IGMP report on that interface to routers. It can also send reports when the interface leaves the multicast group, so it does not want to receive those multicast datagrams. The IGMP module of multicast routers processes these IGMP -reports: it updates the list of groups, that has members on the link of +reports: it updates the list of groups that have members on the link of the incoming message. The :ned:`IIgmp` module interface defines the connections of IGMP modules. IGMP reports are transmitted by IP, so the module contains gates to be connected to the IP module (:gate:`ipIn/ipOut`). The IP module delivers packets with protocol number 2 to the IGMP module. -However some multicast routing protocols (like DVMRP) also exchange +However, some multicast routing protocols (like DVMRP) also exchange routing information by sending IGMP messages, so they should be connected to the :gate:`routerIn/routerOut` gates of the IGMP module. The IGMP module delivers the IGMP messages not processed by itself to the connected routing module. The :ned:`Igmpv2` module implements version 2 of the IGMP protocol (RFC -2236). Next we describe its behavior in host and routers in details. -Note that multicast routers behaves as hosts too, i.e. they are sending +2236). Next, we describe its behavior in hosts and routers in detail. +Note that multicast routers behave as hosts too, i.e. they are sending reports to other routers when joining or leaving a multicast group. Host behavior ~~~~~~~~~~~~~~ -When an interface joins to a multicast group, the host will send a +When an interface joins a multicast group, the host will send a Membership Report immediately to the group address. This report is repeated after :par:`unsolicitedReportInterval` to cover the possibility of the first report being lost. @@ -235,7 +235,7 @@ Group message to the all-routers multicast group (224.0.0.2). This module also responds to IGMP Queries. When the host receives a Group-Specific Query on an interface that belongs to that group, then it will set a timer to a random value between 0 and Max Response Time of -the Query. If the timer expires before the host observe a Membership +the Query. If the timer expires before the host observes a Membership Report sent by other hosts, then the host sends an IGMPv2 Membership Report. When the host receives a General Query on an interface, a timer is initialized and a report is sent for each group membership of the @@ -244,7 +244,7 @@ interface. Router behavior ~~~~~~~~~~~~~~~~ -Multicast routers maintains a list for each interface containing the +Multicast routers maintain a list for each interface containing the multicast groups that have listeners on that interface. This list is updated when IGMP Membership Reports and Leave Group messages arrive, or when a timer expires since the last Query. @@ -253,29 +253,29 @@ When multiple routers are connected to the same link, the one with the smallest IP address will be the Querier. When other routers observe that they are Non-Queriers (by receiving an IGMP Query with a lower source address), they stop sending IGMP Queries until -:par:`otherQuerierPresentInterval` elapsed since the last received +:par:`otherQuerierPresentInterval` has elapsed since the last received query. Routers periodically (:par:`queryInterval`) send a General Query on each -attached network for which this router is a Querier. On startup the +attached network for which this router is a Querier. On startup, the router sends :par:`startupQueryCount` queries separated by -:par:`startupQueryInterval`. A General Query has unspecified Group +:par:`startupQueryInterval`. A General Query has an unspecified Group Address field, a Max Response Time field set to :par:`queryResponseInterval`, and is sent to the all-systems multicast address (224.0.0.1). When a router receives a Membership Report, it will add the reported -group to the list of multicast group memberships. At the same time it +group to the list of multicast group memberships. At the same time, it will set a timer for the membership to :par:`groupMembershipInterval`. Repeated reports restart the timer. If the timer expires, the router assumes that the group has no local members, and multicast traffic is no -more forwarded to that interface. +longer forwarded to that interface. When a Querier receives a Leave Group message for a group, it sends a Group-Specific Query to the group being left. It repeats the Query -:par:`lastMemberQueryCount` times in separated by +:par:`lastMemberQueryCount` times separated by :par:`lastMemberQueryInterval` until a Membership Report is received. If -no Report received, then the router assumes that the group has no local +no Report is received, then the router assumes that the group has no local members. Parameters @@ -283,24 +283,24 @@ Parameters The following parameters have effects in both hosts and routers: -- :par:`enabled` if ``false`` then the IGMP module never sends any - message and discards incoming messages. Default is ``true``. +- :par:`enabled` if ``false``, then the IGMP module never sends any + messages and discards incoming messages. The default is ``true``. The following parameters are only used in hosts: - :par:`unsolicitedReportInterval` the time between repetitions of a - host’s initial report of membership in a group. Default is 10s. + host’s initial report of membership in a group. The default is 10s. Router timeouts are configured by these parameters: - :par:`robustnessVariable` the IGMP is robust to - :par:`robustnessVariable`-1 packet losses. Default is 2. + :par:`robustnessVariable`-1 packet losses. The default is 2. - :par:`queryInterval` the interval between General Queries sent by a - Querier. Default is 125s. + Querier. The default is 125s. - :par:`queryResponseInterval` the Max Response Time inserted into - General Queries + General Queries. - :par:`groupMembershipInterval` the amount of time that must pass before a multicast router decides there are no more members of a @@ -314,17 +314,18 @@ Router timeouts are configured by these parameters: :par:`queryResponseInterval` / 2. - :par:`startupQueryInterval` the interval between General Queries sent - by a Querier on startup. Default is :par:`queryInterval` / 4. + by a Querier on startup. The default is :par:`queryInterval` / 4. - :par:`startupQueryCount` the number of Queries sent out on startup, - separated by the :par:`startupQueryInterval`. Default is + separated by the :par:`startupQueryInterval`. The default is :par:`robustnessVariable`. - :par:`lastMemberQueryInterval` the Max Response Time inserted into Group-Specific Queries sent in response to Leave Group messages, and is also the amount of time between Group-Specific Query messages. - Default is 1s. + The default is 1s. - :par:`lastMemberQueryCount` the number of Group-Specific Queries sent - before the router assumes there are no local members. Default is + before the router assumes there are no local members. The default is :par:`robustnessVariable`. + diff --git a/doc/src/users-guide/ch-ipv6.rst b/doc/src/users-guide/ch-ipv6.rst index f3c1e51af6a..9338f012c18 100644 --- a/doc/src/users-guide/ch-ipv6.rst +++ b/doc/src/users-guide/ch-ipv6.rst @@ -17,12 +17,12 @@ configuration (address, state, timeouts, etc.) is held in the node’s The :ned:`Ipv6NeighbourDiscovery` module implements all tasks associated with neighbor discovery and stateless address autoconfiguration. The data structures themselves (destination cache, neighbor cache, prefix -list) are kept in :ned:`Ipv6RoutingTable`. The rest of ICMPv6’s -functionality, such as error messages, echo request/reply, etc.) is +list) are kept in the :ned:`Ipv6RoutingTable`. The rest of ICMPv6’s +functionality, such as error messages, echo request/reply, etc., is implemented in :ned:`Icmpv6`. Mobile IPv6 support has been contributed to INET by the xMIPv6 project. The main module is :ned:`xMIPv6`, which implements Fast MIPv6, -Hierarchical MIPv6 and Fast Hierarchical MIPv6 (thus, -:math:`x \in {F, H, FH}`). The binding cache and related data structures -are kept in the :ned:`BindingCache` module. +Hierarchical MIPv6, and Fast Hierarchical MIPv6 (thus, +:math:`x \in \{F, H, FH\}`). The binding cache and related data structures +are kept in the :ned:`BindingCache` module. \ No newline at end of file diff --git a/doc/src/users-guide/ch-lifecycle.rst b/doc/src/users-guide/ch-lifecycle.rst index 2052b290d63..7e3cd655c90 100644 --- a/doc/src/users-guide/ch-lifecycle.rst +++ b/doc/src/users-guide/ch-lifecycle.rst @@ -24,7 +24,7 @@ INET supports the following lifecycle operations: - *Crash* represents the process of crashing a network node. The difference between *crash* and *shutdown* is that for a crash, the network node will not do a graceful shutdown (e.g. routing protocols - will not have a chance of notifying peers about broken routes). + will not have a chance to notify peers about broken routes). In a real-life router or other network node, a crash or shutdown and subsequent restart affects all parts of the system. All non-persistent @@ -32,47 +32,47 @@ information is lost. Protocol states are reset, various tables are cleared, connections are broken or torn down, applications restart, and so on. -Mimicking this behavior in simulation does not come for free, it needs +Mimicking this behavior in simulation does not come for free; it needs to be explicitly programmed into each affected component. Here are some -examples how INET components react to a *crash* lifecycle event: +examples of how INET components react to a *crash* lifecycle event: -- :ned:`Tcp` forgets all open connections and sockets +- :ned:`Tcp` forgets all open connections and sockets. - :ned:`Ipv4` clears the fragmentation reassembly buffers and pending - packets + packets. -- :ned:`Ipv4RoutingTable` clears the route table +- :ned:`Ipv4RoutingTable` clears the route table. - :ned:`EthernetCsmaMac` and other MAC protocols clear their queues and reset - their state associated with the current transmission(s) + their state associated with the current transmission(s). -- :ned:`Ospfv2` clears its full state +- :ned:`Ospfv2` clears its full state. -- :ned:`UdpBasicApp`, :ned:`TcpSessionApp` and other applications reset - their state and stop/restart their timers +- :ned:`UdpBasicApp`, :ned:`TcpSessionApp`, and other applications reset + their state and stop/restart their timers. - :ned:`EthernetSwitch`, :ned:`AccessPoint`, and other L2 bridging devices - clear their MAC address tables + clear their MAC address tables. While down, network interfaces, and components in general, ignore (discard) messages sent to them. -Lifecycle operations are currently instantaneous, i.e. they complete in +Lifecycle operations are currently instantaneous; they complete in zero simulation time. The underlying framework would allow for modeling them as processes that take place in some finite (nonzero) simulation time, but this possibility is currently not in use. -It also is possible to simulate a crash or shutdown of part of a node +It is also possible to simulate a crash or shutdown of part of a node (certain protocols or interfaces only). Such scenarios would correspond -to e.g. the crash of an OSPF daemon on a real OS. +to, for example, the crash of an OSPF daemon on a real OS. Some energy-related INET components trigger node shutdown or crash under certain conditions. For example, a node will crash when it runs out of power (e.g. its battery depletes); see the chapter on power consumption modeling :doc:`ch-power` for details. -In the following sections we outline the INET components that -participate in lifecycle modeling, and show a usage example. +In the following sections, we outline the INET components that +participate in lifecycle modeling and show a usage example. .. _ug:sec:lifecycle:nodestatus: @@ -84,14 +84,14 @@ status of the node (up, down, etc.) for other modules, and also displays it in the GUI as a small overlay icon. The :ned:`NodeStatus` module is declared conditionally (so that it is -only created in simulations that need it), like this: +only created in simulations that need it) like this: .. code-block:: ned status: NodeStatus if hasStatus; If lifecycle modeling is required, the following line must be added to -the ini file to ensure that nodes have status modules: +the INI file to ensure that nodes have status modules: .. code-block:: ini @@ -102,11 +102,11 @@ the ini file to ensure that nodes have status modules: Scripting --------- -Lifecycle operations can be triggered from C++ code, or from scripts. +Lifecycle operations can be triggered from C++ code or from scripts. INET supports scripting via the :ned:`ScenarioManager` NED type, described in chapter :doc:`ch-scenario-scripting`. Here is an -example script that shuts down a router at simulation time 2s, and -starts it up a again at time 8s: +example script that shuts down a router at simulation time 2s and +starts it up again at time 8s: .. code-block:: xml @@ -121,8 +121,8 @@ network interface, protocol, etc.) to be operated on. The ``"shutdown"``, ``"crash"``, or ``"startup"``. ``t`` is the simulation time the operation should be initiated at. -An alternative, shorter form is to use ```` / -```` / ```` elements instead of the +An alternative, shorter form is to use ````, ````, or +```` elements instead of the ``operation`` attribute: .. code-block:: xml diff --git a/doc/src/users-guide/ch-mobility.rst b/doc/src/users-guide/ch-mobility.rst index f3064b45fe8..0cc3770e307 100644 --- a/doc/src/users-guide/ch-mobility.rst +++ b/doc/src/users-guide/ch-mobility.rst @@ -28,9 +28,9 @@ In INET, a mobility model is most often an OMNeT++ simple module implementing the motion as a C++ algorithm. Although most models have a few common parameters (e.g. for initial positioning), they always come with their own set of parameters. Some models support geographic -positioning to ease the configuration of map based scenarios. +positioning to ease the configuration of map-based scenarios. -Mobility models be *single* or *group* mobility models. Single mobility +Mobility models can be *single* or *group* mobility models. Single mobility models describe the motion of entities independent of each other. Group mobility models provide such a motion where group members are dependent on each other. @@ -54,28 +54,28 @@ The Scene ~~~~~~~~~ Many mobility models allow the user to define a cubic volume that the -node can not leave. The volume is configured by setting the +node cannot leave. The volume is configured by setting the :par:`constraintAreaX`, :par:`constraintAreaY`, :par:`constraintAreaZ`, -:par:`constraintAreaWidth`, :par:`constraintAreaHeight` and +:par:`constraintAreaWidth`, :par:`constraintAreaHeight`, and :par:`constraintAreaDepth` parameters. -If the :par:`initFromDisplayString` parameter, the initial position is +If the :par:`initFromDisplayString` parameter is set, the initial position is taken from the display string. Otherwise, the position can be given in -the :par:`initialX`, :par:`initialY` and :par:`initialZ` parameters. If -neither of these parameters are given, a random initial position is -choosen within the contraint area. +the :par:`initialX`, :par:`initialY`, and :par:`initialZ` parameters. If +neither of these parameters is given, a random initial position is +chosen within the constraint area. When the node reaches the boundary of the constraint area, the mobility -component has to prevent the node to exit. Many mobility models offer +component has to prevent the node from exiting. Many mobility models offer the following policies: -- reflect of the wall +- reflection off the wall -- reappear at the opposite edge (torus area) +- reappearance at the opposite edge (torus area) -- placed at a randomly chosen position of the area +- placement at a randomly chosen position in the area -- stop the simulation with an error +- stopping the simulation with an error .. _ug:sec:mobility:built-in-mobility-models: @@ -87,9 +87,9 @@ Built-In Mobility Models List of Mobility Models ~~~~~~~~~~~~~~~~~~~~~~~ -The following, potentially list contains the mobility models available -in INET. Nearly all of these models als single mobility models; group -mobility can be implemented e.g. with combining other mobility models. +The following potentially list contains the mobility models available +in INET. Nearly all of these models are single mobility models; group +mobility can be implemented, for example, by combining other mobility models. Stationary ^^^^^^^^^^ @@ -108,8 +108,8 @@ Stationary models only define position (and orientation), but no motion. Deterministic ^^^^^^^^^^^^^ -Deterministic mobility models use non-random mathematical models for -describing motion. +Deterministic mobility models use non-random mathematical models to +describe motion. - :ned:`LinearMobility` moves linearly with a constant speed or constant acceleration. @@ -123,7 +123,7 @@ describing motion. - :ned:`TractorMobility` moves similarly to a tractor on a field with a number of rows. -- :ned:`VehicleMobility` moves similarly to a vehicle along a path +- :ned:`VehicleMobility` moves similarly to a vehicle along a path, especially turning around corners. - :ned:`TurtleMobility` moves according to an XML script written in a @@ -138,13 +138,13 @@ Trace-Based Trace-based mobility models replay recorded motion as observed in real life. -- :ned:`BonnMotionMobility` replays trace files of the BonnMotion +- :ned:`BonnMotionMobility` replays trace files from the BonnMotion scenario generator. -- :ned:`Ns2MotionMobility` replays files of the CMU’s scenario +- :ned:`Ns2MotionMobility` replays files from the CMU's scenario generator used in ns2. -- :ned:`AnsimMobility` replays XML trace files of the ANSim (Ad-Hoc +- :ned:`AnsimMobility` replays XML trace files from the ANSim (Ad-Hoc Network Simulation) tool. Stochastic @@ -153,7 +153,7 @@ Stochastic Stochastic or random mobility models use mathematical models involving random numbers. -- :ned:`RandomWaypointMobility` moves to random destination with random +- :ned:`RandomWaypointMobility` moves to random destinations with random speed. - :ned:`GaussMarkovMobility` uses one parameter to vary the degree of @@ -169,7 +169,7 @@ Combining ^^^^^^^^^ Combining mobility models are not mobility models per se, but instead, -they allow more complex motions to be formed from simpler ones via +they allow for more complex motions to be formed from simpler ones via superposition and other ways. - :ned:`SuperpositioningMobility` model combines several other mobility @@ -178,9 +178,9 @@ superposition and other ways. positioning from positioning during the simulation, and separating positioning from orientation. -- :ned:`AttachedMobility` models a mobility that is attached to another - one at a given offset. Position, velocity and acceleration are all - affected by the respective quantites and also the orientation of the +- :ned:`AttachedMobility` models mobility that is attached to another + one at a given offset. Position, velocity, and acceleration are all + affected by the respective quantities and also the orientation of the referenced mobility. .. _ug:sec:mobility:more-information-on-some-mobility-models: @@ -191,10 +191,10 @@ More Information on Some Mobility Models TractorMobility ^^^^^^^^^^^^^^^ -Moves a tractor through a field with a certain amount of rows. The +Moves a tractor through a field with a certain number of rows. The following figure illustrates the movement of the tractor when the :par:`rowCount` parameter is 2. The trajectory follows the segments in -``1,2,3,4,5,6,7,8,1,2,3...`` order. The area is configured by the +the ``1,2,3,4,5,6,7,8,1,2,3...`` order. The area is configured by the :par:`x1`, :par:`y1`, :par:`x2`, :par:`y2` parameters. .. PDF version f image: @@ -214,54 +214,58 @@ following figure illustrates the movement of the tractor when the RandomWaypointMobility ^^^^^^^^^^^^^^^^^^^^^^ -In the Random Waypoint mobility model the nodes move in line segments. +In the Random Waypoint mobility model, the nodes move in line segments. For each line segment, a random destination position (distributed -uniformly over the scene) and a random speed is chosen. You can +uniformly over the scene) and a random speed are chosen. You can define a speed as a variate from which a new value will be drawn for each line segment; it is customary to specify it as ``uniform(minSpeed, maxSpeed)``. When the node reaches the target -position, it waits for the time :par:`waitTime` which can also be -defined as a variate. After this time the the algorithm calculates a new +position, it waits for the time :par:`waitTime`, which can also be +defined as a variate. After this time, the algorithm calculates a new random position, etc. GaussMarkovMobility ^^^^^^^^^^^^^^^^^^^ -The Gauss-Markov model contains a tuning parameter that control the +The Gauss-Markov model contains a tuning parameter that controls the randomness in the movement of the node. Let the magnitude and direction -of speed of the node at the :math:`n`\ th time step be :math:`s_n` and +of the speed of the node at the :math:`n`\ th time step be :math:`s_n` and :math:`d_n`. The next speed and direction are computed as -.. math:: s_{n+1} = \alpha s_n + (1 - \alpha) \bar{s} + \sqrt{(1-\alpha^2)} s_{x_n} +.. math:: + + s_{n+1} = \alpha s_n + (1 - \alpha) \bar{s} + \sqrt{(1-\alpha^2)} s_{x_n} + +.. math:: -.. math:: d_{n+1} = \alpha s_n + (1 - \alpha) \bar{d} + \sqrt{(1-\alpha^2)} d_{x_n} + d_{n+1} = \alpha s_n + (1 - \alpha) \bar{d} + \sqrt{(1-\alpha^2)} d_{x_n} where :math:`\bar{s}` and :math:`\bar{d}` are constants representing the mean value of speed and direction as :math:`n \to \infty`; and -:math:`s_{x_n}` and :math:`d_{x_n}` are random variables with Gaussian +:math:`s_{x_n}` and :math:`d_{x_n}` are random variables with a Gaussian distribution. Totally random walk (Brownian motion) is obtained by setting -:math:`\alpha=0`, while :math:`\alpha=1` results a linear motion. +:math:`\alpha=0`, while :math:`\alpha=1` results in linear motion. To ensure that the node does not remain at the boundary of the constraint area for a long time, the mean value of the direction -(:math:`\bar{d}`) modified as the node enters the margin area. For -example at the right edge of the area it is set to 180 degrees, so the +(:math:`\bar{d}`) is modified as the node enters the margin area. For +example, at the right edge of the area it is set to 180 degrees, so the new direction is away from the edge. MassMobility ^^^^^^^^^^^^ -This is a random mobility model for a mobile host with a mass. It is the +This is a random mobility model for a mobile host with mass. It is the one used in :raw-latex:`\cite{Perkins99optimizedsmooth}`. "An MH moves within the room according to the following pattern. It moves along a straight line for a certain period of time before it makes a turn. This moving period is a random number, normally - distributed with average of 5 seconds and standard deviation of 0.1 - second. When it makes a turn, the new direction (angle) in which it - will move is a normally distributed random number with average equal + distributed with the average of 5 seconds and standard deviation of 0.1 + seconds. When it makes a turn, the new direction (angle) in which it + will move is a normally distributed random number with an average equal to the previous direction and standard deviation of 30 degrees. Its speed is also a normally distributed random number, with a controlled average, ranging from 0.1 to 0.45 (unit/sec), and standard deviation @@ -273,7 +277,7 @@ one used in :raw-latex:`\cite{Perkins99optimizedsmooth}`. other choice." This implementation can be parameterized a bit more, via the -:par:`changeInterval`, :par:`changeAngleBy` and :par:`changeSpeedBy` +:par:`changeInterval`, :par:`changeAngleBy`, and :par:`changeSpeedBy` parameters. The parameters described above correspond to the following settings: @@ -286,7 +290,7 @@ settings: ChiangMobility ^^^^^^^^^^^^^^ -Implements Chiang’s random walk movement model +Implements Chiang's random walk movement model (:raw-latex:`\cite{Chiang98wirelessnetwork}`). In this model, the state of the mobile node in each direction (x and y) can be: @@ -311,7 +315,7 @@ probability that the state changes from :math:`i` to :math:`j`: .. _ug:sec:mobility:replaying-trace-files: -Replaying trace files +Replaying Trace Files ~~~~~~~~~~~~~~~~~~~~~ BonnMotionMobility @@ -355,7 +359,7 @@ The :ned:`Ns2MotionMobility` module has the following parameters: - :par:`traceFile` the Ns2 trace file - :par:`nodeId` node identifier in the trace file; -1 gets substituted - by parent module’s index + by the parent module's index - :par:`scrollX`, :par:`scrollY` user specified translation of the coordinates @@ -363,7 +367,7 @@ The :ned:`Ns2MotionMobility` module has the following parameters: ANSimMobility ^^^^^^^^^^^^^ -It reads trace files of the `ANSim `__ Tool. The +It reads XML trace files from the `ANSim `__ Tool. The nodes are moving along linear segments described by an XML trace file conforming to this DTD: @@ -384,15 +388,15 @@ Parameters of the module: - :par:`ansimTrace` the trace file -- :par:`nodeId` the ``node_id`` of this node, -1 gets substituted to - parent module’s index +- :par:`nodeId` the ``node_id`` of this node, -1 gets substituted + by the parent module's index .. note:: The :ned:`AnsimMobility` module processes only the ``position_change`` - elements and it ignores the ``start_time`` attribute. It starts the move + elements, and it ignores the ``start_time`` attribute. It starts the move on the next segment immediately. .. _ug:sec:mobility:turtlemobility: @@ -400,14 +404,14 @@ Parameters of the module: TurtleMobility ~~~~~~~~~~~~~~ -The :ned:`TurtleMobility` module can be parametrized by a script file +The :ned:`TurtleMobility` module can be parameterized by a script file containing LOGO-style movement commands in XML format. The content of the XML file should conform to the DTD in the :file:`TurtleMobility.dtd` file in the source tree. The file contains ``movement`` elements, each describing a trajectory. The ``id`` attribute of the ``movement`` element can -be used to refer the movement from the ini file using the syntax: +be used to refer to the movement from the ini file using the syntax: @@ -416,7 +420,7 @@ be used to refer the movement from the ini file using the syntax: **.mobility.turtleScript = xmldoc("turtle.xml", "movements//movement[@id='1']") The motion of the node is composed of uniform linear segments. The -``movement`` elements may contain the the following commands as +``movement`` elements may contain the following commands as elements (names in parens are recognized attribute names): - ``repeat(n)`` repeats its content n times, or indefinitely if the @@ -424,13 +428,13 @@ elements (names in parens are recognized attribute names): - ``set(x,y,speed,angle,borderPolicy)`` modifies the state of the node. ``borderPolicy`` can be ``reflect``, ``wrap``, - ``placerandomly`` or ``error``. + ``placerandomly``, or ``error``. - ``forward(d,t)`` moves the node for ``t`` time or to the ``d`` distance with the current speed. If both ``d`` and - ``t`` is given, then the current speed is ignored. + ``t`` are given, then the current speed is ignored. -- ``turn(angle)`` increase the angle of the node by ``angle`` +- ``turn(angle)`` increases the angle of the node by ``angle`` degrees. - ``moveto(x,y,t)`` moves to point ``(x,y)`` in the given time. @@ -442,8 +446,8 @@ elements (names in parens are recognized attribute names): - ``wait(t)`` waits for the specified amount of time. Attribute values must be given without physical units, distances are -assumed to be given as meters, time intervals in seconds and speeds in -meter per seconds. Attibutes can contain expressions that are evaluated +assumed to be given as meters, time intervals in seconds, and speeds in +meters per seconds. Attributes can contain expressions that are evaluated each time the command is executed. The limits of the constraint area can be referenced as ``$MINX``, ``$MAXX``, ``$MINY``, and ``$MAXY``. Random number distributions generate a new random number when evaluated, so the @@ -480,7 +484,7 @@ Random Waypoint: - + diff --git a/doc/src/users-guide/ch-mpls.rst b/doc/src/users-guide/ch-mpls.rst index 0b6e033de19..89fc47a72fa 100644 --- a/doc/src/users-guide/ch-mpls.rst +++ b/doc/src/users-guide/ch-mpls.rst @@ -8,27 +8,11 @@ The MPLS Models Overview -------- -Multi-Protocol Label Switching (MPLS) is a “layer 2.5” protocol for -high-performance telecommunications networks. MPLS directs data from one -network node to the next based on numeric labels instead of network -addresses, avoiding complex lookups in a routing table and allowing -traffic engineering. The labels identify virtual links (label-switched -paths or LSPs, also called MPLS tunnels) between distant nodes rather -than endpoints. The routers that make up a label-switched network are -called label-switching routers (LSRs) inside the network (“transit -nodes”), and label edge routers (LER) on the edges of the network -(“ingress” or “egress” nodes). - -A fundamental MPLS concept is that two LSRs must agree on the meaning of -the labels used to forward traffic between and through them. This common -understanding is achieved by using signaling protocols by which one LSR -informs another of label bindings it has made. Such signaling protocols -are also called label distribution protocols. The two main label -distribution protocols used with MPLS are LDP and RSVP-TE. - -INET provides basic support for building MPLS simulations. It provides -models for the MPLS, LDP and RSVP-TE protocols and their associated data -structures, and preassembled MPLS-capable router models. +Multi-Protocol Label Switching (MPLS) is a "layer 2.5" protocol for high-performance telecommunications networks. MPLS directs data from one network node to the next based on numeric labels instead of network addresses, avoiding complex lookups in a routing table and allowing traffic engineering. The labels identify virtual links (label-switched paths or LSPs, also called MPLS tunnels) between distant nodes rather than endpoints. The routers that make up a label-switched network are called label-switching routers (LSRs) inside the network ("transit nodes"), and label edge routers (LER) on the edges of the network ("ingress" or "egress" nodes). + +A fundamental MPLS concept is that two LSRs must agree on the meaning of the labels used to forward traffic between and through them. This common understanding is achieved by using signaling protocols through which one LSR informs another of label bindings it has made. Such signaling protocols are also called label distribution protocols. The two main label distribution protocols used with MPLS are LDP and RSVP-TE. + +INET provides basic support for building MPLS simulations. It provides models for the MPLS, LDP, and RSVP-TE protocols and their associated data structures, and preassembled MPLS-capable router models. .. _ug:sec:mpls:core-modules: @@ -37,75 +21,53 @@ Core Modules The core modules are: -- :ned:`Mpls` implements the MPLS protocol +- :ned:`Mpls` implements the MPLS protocol -- :ned:`LibTable` holds the LIB (Label Information Base) +- :ned:`LibTable` holds the LIB (Label Information Base) -- :ned:`Ldp` implements the LDP signaling protocol for MPLS +- :ned:`Ldp` implements the LDP signaling protocol for MPLS -- :ned:`RsvpTe` implements the RSVP-TE signaling protocol for MPLS +- :ned:`RsvpTe` implements the RSVP-TE signaling protocol for MPLS -- :ned:`Ted` contains the Traffic Engineering Database +- :ned:`Ted` contains the Traffic Engineering Database -- :ned:`LinkStateRouting` is a simple link-state routing protocol +- :ned:`LinkStateRouting` is a simple link-state routing protocol -- :ned:`RsvpClassifier` is a configurable ingress classifier for MPLS +- :ned:`RsvpClassifier` is a configurable ingress classifier for MPLS .. _ug:sec:mpls:mpls: Mpls ~~~~ -The :ned:`Mpls` module implements the MPLS protocol. MPLS is situated -between layer 2 and 3, and its main function is to switch packets based -on their labels. For that, it relies on the data structure called LIB -(Label Information Base). LIB is fundamentally a table with the -following columns: *input-interface*, *input-label*, *output-interface*, -*label-operation(s)*. +The :ned:`Mpls` module implements the MPLS protocol. MPLS is situated between layer 2 and 3, and its main function is to switch packets based on their labels. For that, it relies on the data structure called LIB (Label Information Base). LIB is fundamentally a table with the following columns: *input-interface*, *input-label*, *output-interface*, *label-operation(s)*. -Upon receiving a labelled packet from another LSR, MPLS first extracts -the incoming interface and incoming label pair, and then looks it up in -local LIB. If a matching entry is found, it applies the prescribed label -operations, and forwards the packet to the output interface. +Upon receiving a labeled packet from another LSR, MPLS first extracts the incoming interface and incoming label pair, and then looks it up in the local LIB. If a matching entry is found, it applies the prescribed label operations and forwards the packet to the output interface. -Label operations can be the following: +The label operations can be the following: -- *Push* adds a new MPLS label to a packet. (A packet may contain - multiple labels, acting as a stack.) When a normal IP packet enters - an LSP, the new label will be the first label on the packet. +- *Push* adds a new MPLS label to a packet. (A packet may contain multiple labels, acting as a stack.) When a normal IP packet enters an LSP, the new label will be the first label on the packet. -- *Pop* removes the topmost MPLS label from a packet. This is typically - done at either the penultimate or the egress router. +- *Pop* removes the topmost MPLS label from a packet. This is typically done at either the penultimate or the egress router. -- *Swap*: Replaces the topmost label with a new label. +- *Swap* replaces the topmost label with a new label. -In INET, the local LIB is stored in a :ned:`LibTable` module in the -router. +In INET, the local LIB is stored in a :ned:`LibTable` module in the router. -Upon receiving an unlabelled (e.g. plain IPv4) packet, MPLS first -determines the forwarding equivalence class (FEC) for the packet using -an ingress classifier, and then inserts one or more labels in the -packet’s newly created MPLS header. The packet is then passed on to the -next hop router for the LSP. +Upon receiving an unlabeled (e.g., plain IPv4) packet, MPLS first determines the forwarding equivalence class (FEC) for the packet using an ingress classifier, and then inserts one or more labels in the packet's newly created MPLS header. The packet is then passed on to the next hop router for the LSP. -The ingress classifier is also a separate module; it is selected -depending on the choice of the signaling protocol. +The ingress classifier is also a separate module; it is selected depending on the choice of the signaling protocol. .. _ug:sec:mpls:libtable: LibTable ~~~~~~~~ -:ned:`LibTable` stores the LIB (Label Information Base), as described in -the previous section. :ned:`LibTable` is expected to have one instance -in the router. +:ned:`LibTable` stores the LIB (Label Information Base), as described in the previous section. :ned:`LibTable` is expected to have one instance in the router. -LIB is normally filled and maintained by label distribution protocols -(RSVP-TE, LDP), but in INET it is possible to preload it with initial -contents. +LIB is normally filled and maintained by label distribution protocols (RSVP-TE, LDP), but in INET, it is possible to preload it with initial contents. -The :ned:`LibTable` module accepts an XML config file whose structure -follows the contents of the LIB table. An example configuration: +The :ned:`LibTable` module accepts an XML config file whose structure follows the contents of the LIB table. An example configuration: .. code-block:: xml @@ -123,80 +85,45 @@ follows the contents of the LIB table. An example configuration: -There can be multiple ```` elements, each describing a row -in the table. Colums are given as child elements: ````, -````, etc. The ```` element is optional, and -it only exists to be able to color LSPs on the GUI. It is not used by -the protocols. +There can be multiple ```` elements, each describing a row in the table. Columns are given as child elements: ````, ````, etc. The ```` element is optional, and it only exists to be able to color LSPs on the GUI. It is not used by the protocols. .. _ug:sec:mpls:ldp: Ldp ~~~ -The :ned:`Ldp` module implements the Label Distribution Protocol (LDP). -LDP is used to establish LSPs in an MPLS network when traffic -engineering is not required. It establishes LSPs that follow the -existing IP routing table, and is particularly well suited for -establishing a full mesh of LSPs between all of the routers on the -network. +The :ned:`Ldp` module implements the Label Distribution Protocol (LDP). LDP is used to establish LSPs in an MPLS network when traffic engineering is not required. It establishes LSPs that follow the existing IP routing table, and is particularly well suited for establishing a full mesh of LSPs between all of the routers on the network. -LDP relies on the underlying routing information provided by a routing -protocol in order to forward label packets. The router’s forwarding -information base, or FIB, is responsible for determining the hop-by-hop -path through the network. +LDP relies on the underlying routing information provided by a routing protocol to forward label packets. The router's forwarding information base, or FIB, is responsible for determining the hop-by-hop path through the network. -In INET, the :ned:`Ldp` module takes routing information from :ned:`Ted` -module. The :ned:`Ted` instance in the network is filled and maintained -by a :ned:`LinkStateRouting` module. Unfortunately, it is currently not -possible to use other routing protocol implementations such as -:ned:`Ospfv2` in conjunction with :ned:`Ldp`. +In INET, the :ned:`Ldp` module takes routing information from the :ned:`Ted` module. The :ned:`Ted` instance in the network is filled and maintained by a :ned:`LinkStateRouting` module. Unfortunately, it is currently not possible to use other routing protocol implementations such as :ned:`Ospfv2` in conjunction with :ned:`Ldp`. -When :ned:`Ldp` is used as signaling protocol, it also serves as ingress -classifier for :ned:`Mpls`. +When :ned:`Ldp` is used as the signaling protocol, it also serves as the ingress classifier for :ned:`Mpls`. -.. _ug:sec:mpls:ted: +.. _ug:sec:mpls:lening: Ted ~~~ -The :ned:`Ted` module contains the Traffic Engineering Database (TED). -In INET, :ned:`Ted` contains a link state database, including -reservations for each link by RSVP-TE. +The :ned:`Ted` module contains the Traffic Engineering Database (TED). In INET, :ned:`Ted` contains a link-state database, including reservations for each link by RSVP-TE. .. _ug:sec:mpls:linkstaterouting: LinkStateRouting ~~~~~~~~~~~~~~~~ -The :ned:`LinkStateRouting` module provides a simple link state routing -protocol. It uses :ned:`Ted` as its link state database. Unfortunately, -the :ned:`LinkStateRouting` module cannot operate independently, it can -only be used inside an MPLS router. +The :ned:`LinkStateRouting` module provides a simple link-state routing protocol. It uses :ned:`Ted` as its link-state database. Unfortunately, the :ned:`LinkStateRouting` module cannot operate independently; it can only be used inside an MPLS router. .. _ug:sec:mpls:rsvpte: RsvpTe ~~~~~~ -The :ned:`RsvpTe` module implements RSVP-TE (Resource Reservation -Protocol – Traffic Engineering), as signaling protocol for MPLS. RSVP-TE -handles bandwidth allocation and allows traffic engineering across an -MPLS network. Like LDP, RSVP uses discovery messages and advertisements -to exchange LSP path information between all hosts. However, whereas LDP -is restricted to using the configured IGP’s shortest path as the transit -path through the network, RSVP can take taking into consideration -network constraint parameters such as available bandwidth and explicit -hops. RSVP uses a combination of the Constrained Shortest Path First -(CSPF) algorithm and Explicit Route Objects (EROs) to determine how -traffic is routed through the network. - -When :ned:`RsvpTe` is used as signaling protocol, :ned:`Mpls` needs a -separate ingress classifier module, which is usually a -:ned:`RsvpClassifier`. - -The :ned:`RsvpTe` module allows LSPs to be specified statically in an -XML config file. An example ``traffic.xml`` file: +The :ned:`RsvpTe` module implements RSVP-TE (Resource Reservation Protocol – Traffic Engineering), as the signaling protocol for MPLS. RSVP-TE handles bandwidth allocation and allows traffic engineering across an MPLS network. Like LDP, RSVP uses discovery messages and advertisements to exchange LSP path information between all hosts. However, whereas LDP is restricted to using the configured IGP's shortest path as the transit path through the network, RSVP can take into consideration network constraint parameters such as available bandwidth and explicit hops. RSVP uses a combination of the Constrained Shortest Path First (CSPF) algorithm and Explicit Route Objects (EROs) to determine how traffic is routed through the network. + +When :ned:`RsvpTe` is used as the signaling protocol, :ned:`Mpls` needs a separate ingress classifier module, which is usually a :ned:`RsvpClassifier`. + +The :ned:`RsvpTe` module allows LSPs to be specified statically in an XML config file. An example ``traffic.xml`` file: .. code-block:: xml @@ -221,17 +148,9 @@ XML config file. An example ``traffic.xml`` file: -In the route, ```` stands for strict hop, and ```` -for loose hop. +In the route, ```` stands for strict hop, and ```` for loose hop. -Paths can also be set up and torn down dynamically with -:ned:`ScenarioManager` commands (see chapter :doc:`ch-scenario-scripting`). -:ned:`RsvpTe` understands the ```` and ```` -:ned:`ScenarioManager` commands. The contents of the -```` element can be the same as the ```` -element for the ``traffic.xml`` above. The ```` -element syntax is also similar, but only ````, -```` and ```` need to be specified. +Paths can also be set up and torn down dynamically with :ned:`ScenarioManager` commands (see chapter :doc:`ch-scenario-scripting`). :ned:`RsvpTe` understands the ```` and ```` :ned:`ScenarioManager` commands. The contents of the ```` element can be the same as the ```` element for the ``traffic.xml`` above. The ```` element syntax is also similar, but only ````, ````, and ```` need to be specified. The following is an example ``scenario.xml`` file: @@ -265,9 +184,7 @@ The following is an example ``scenario.xml`` file: Classifier ---------- -The :ned:`RsvpClassifier` module implements an ingress classifier for -:ned:`Mpls` when using :ned:`RsvpTe` for signaling. The classifier can -be configured with an XML config file. +The :ned:`RsvpClassifier` module implements an ingress classifier for :ned:`Mpls` when using :ned:`RsvpTe` for signaling. The classifier can be configured with an XML config file. .. code-block:: ini @@ -294,8 +211,7 @@ MPLS-Enabled Router Models INET provides the following pre-assembled MPLS routers: -- :ned:`LdpMplsRouter` is an MPLS router with the LDP signaling - protocol +- :ned:`LdpMplsRouter` is an MPLS router with the LDP signaling protocol + +- :ned:`RsvpMplsRouter` is an MPLS router with the RSVP-TE signaling protocol -- :ned:`RsvpMplsRouter` is an MPLS router with the RSVP-TE signaling - protocol diff --git a/doc/src/users-guide/ch-network-autoconfig.rst b/doc/src/users-guide/ch-network-autoconfig.rst index b37a1fe1e65..e519ae47c26 100644 --- a/doc/src/users-guide/ch-network-autoconfig.rst +++ b/doc/src/users-guide/ch-network-autoconfig.rst @@ -17,21 +17,21 @@ Configuring IPv4 Networks An IPv4 network is composed of several nodes like hosts, routers, switches, hubs, Ethernet buses, or wireless access points. The nodes -having a IPv4 network layer (hosts and routers) should be configured at +having an IPv4 network layer (hosts and routers) should be configured at the beginning of the simulation. The configuration assigns IP addresses -to the nodes, and fills their routing tables. If multicast forwarding is +to the nodes and fills their routing tables. If multicast forwarding is simulated, then the multicast routing tables also must be filled in. The configuration can be manual (each address and route is fully -specified by the user), or automatic (addresses and routes are generated +specified by the user) or automatic (addresses and routes are generated by a configurator module at startup). -Before version 1.99.4 INET offered :ned:`Ipv4FlatNetworkConfigurator` +Before version 1.99.4, INET offered :ned:`Ipv4FlatNetworkConfigurator` for automatic and routing files for manual configuration. Both had serious limitations, so a new configurator has been added in version 1.99.4: :ned:`Ipv4NetworkConfigurator`. This configurator supports both fully manual and fully automatic configuration. It can also be used with -partially specified manual configurations, the configurator fills in the +partially specified manual configurations; the configurator fills in the gaps automatically. The next section describes the usage of :ned:`Ipv4NetworkConfigurator`. @@ -56,32 +56,32 @@ also does routing table optimization that significantly decreases the size of routing tables in large networks. The configuration is performed in stage 2 of the initialization. At this -point interface modules (e.g. PPP) has already registered their -interface in the interface table. If an interface is named +point, interface modules (e.g. PPP) have already registered their +interfaces in the interface table. If an interface is named ``ppp[0]``, then the corresponding interface entry is named ``ppp0``. This name can be used in the config file to refer to the interface. The configurator goes through the following steps: -#. Builds a graph representing the network topology. The graph will have +1. Builds a graph representing the network topology. The graph will have a vertex for every module that has a ``@node`` property (this includes hosts, routers, and L2 devices like switches, access points, - Ethernet hubs, etc.) It also assigns weights to vertices and edges + Ethernet hubs, etc.). It also assigns weights to vertices and edges that will be used by the shortest path algorithm when setting up routes. Weights will be infinite for IP nodes that have IP forwarding - disabled (to prevent routes from transiting them), and zero for all - other nodes (routers and and L2 devices). Edge weights are chosen to - be inversely proportional to the bitrate of the link, so that the + disabled (to prevent routes from transiting them) and zero for all + other nodes (routers and L2 devices). Edge weights are chosen to be + inversely proportional to the bitrate of the link so that the configurator prefers connections with higher bandwidth. For internal purposes, the configurator also builds a table of all "links" (the link data structure consists of the set of network interfaces that - are on the same point-to-point link or LAN) + are on the same point-to-point link or LAN). -#. Assigns IP addresses to all interfaces of all nodes. The assignment +2. Assigns IP addresses to all interfaces of all nodes. The assignment process takes into consideration the addresses and netmasks already - present on the interfaces (possibly set in earlier initialize - stages), and the configuration provided in the XML format (described + present on the interfaces (possibly set in earlier initialization + stages) and the configuration provided in the XML format (described below). The configuration can specify "templates" for the address and netmask, with parts that are fixed and parts that can be chosen by the configurator (e.g. "10.0.x.x"). In the most general case, the @@ -92,60 +92,60 @@ The configurator goes through the following steps: to manual address assignment). There are many possible configuration options between these two extremes. The configurator assigns addresses in a way that maximizes the number of nodes per subnet. - Once it figures out the nodes that belong to a single subnet it, will + Once it figures out the nodes that belong to a single subnet, it will optimize for allocating the longest possible netmask. The configurator might fail to assign netmasks and addresses according to the given configuration parameters; if that happens, the assignment - process stops and an error is signalled. + process stops, and an error is signaled. -#. Adds the manual routes that are specified in the configuration. +3. Adds the manual routes that are specified in the configuration. -#. Adds static routes to all routing tables in the network. The +4. Adds static routes to all routing tables in the network. The configurator uses Dijkstra’s weighted shortest path algorithm to find the desired routes between all possible node pairs. The resulting routing tables will have one entry for all destination interfaces in the network. The configurator can be safely instructed to add default routes where applicable, significantly reducing the size of the host routing tables. It can also add subnet routes instead of interface - routes further reducing the size of routing tables. Turning on this + routes, further reducing the size of routing tables. Turning on this option requires careful design to avoid having IP addresses from the same subnet on different links. CAVEAT: Using manual routes and - static route generation together may have unwanted side effects, + static route generation together may have unwanted side effects because route generation ignores manual routes. -#. Then it optimizes the routing tables for size. This optimization - allows configuring larger networks with smaller memory footprint and +5. Then it optimizes the routing tables for size. This optimization + allows configuring larger networks with a smaller memory footprint and makes the routing table lookup faster. The resulting routing table might be different in that it will route packets that the original - routing table did not. Nevertheless the following invariant holds: + routing table did not. Nevertheless, the following invariant holds: any packet routed by the original routing table (has matching route) will still be routed the same way by the optimized routing table. -#. Finally it dumps the requested results of the configuration. It can - dump network topology, assigned IP addresses, routing tables and its - own configuration format. +6. Finally, it dumps the requested results of the configuration. It can + dump the network topology, assigned IP addresses, routing tables, and + its own configuration format. -The module can dump the result of the configuration in the XML format -which it can read. This is useful to save the result of a time consuming -configuration (large network with optimized routes), and use it as the +The module can dump the result of the configuration in the XML format, +which it can read. This is useful to save the result of a time-consuming +configuration (large network with optimized routes) and use it as the config file of subsequent runs. Network topology graph ^^^^^^^^^^^^^^^^^^^^^^ The network topology graph is constructed from the nodes of the network. -The node is a module having a ``@node`` property (this includes -hosts, routers, and L2 devices like switches, access points, Ethernet -hubs, etc.). An IP node is a node that contains an :ned:`InterfaceTable` -and a :ned:`Ipv4RoutingTable`. A router is an IP node that has multiple +The node is a module having a ``@node`` property (this includes hosts, +routers, and L2 devices like switches, access points, Ethernet hubs, +etc.). An IP node is a node that contains an :ned:`InterfaceTable` +and an :ned:`Ipv4RoutingTable`. A router is an IP node that has multiple network interfaces, and IP forwarding is enabled in its routing table -module. In multicast routers the :par:`forwardMulticast` parameter is +module. In multicast routers, the :par:`forwardMulticast` parameter is also set to ``true``. A link is a set of interfaces that can send datagrams to each other without intervening routers. Each interface belongs to exactly one link. -For example two interface connected by a point-to-point connection forms -a link. Ethernet interfaces connected via buses, hubs or switches. The +For example, two interfaces connected by a point-to-point connection form +a link. Ethernet interfaces connected via buses, hubs, or switches. The configurator identifies links by discovering the connections between the IP nodes, buses, hubs, and switches. @@ -160,10 +160,10 @@ configured in the configuration file of :ned:`Ipv4NetworkConfigurator`: .. code-block:: xml - + -puts wlan interfaces of the specified hosts into the same wireless link. +This puts WLAN interfaces of the specified hosts into the same wireless link. If a link contains only one router, it is marked as the gateway of the link. Each datagram whose destination is outside the link must go @@ -175,16 +175,16 @@ Address assignment Addresses can be set up manually by giving the address and netmask for each IP node. If some part of the address or netmask is unspecified, then the configurator can fill them automatically. Unspecified fields -are given as an “x” character in the dotted notation of the address. For +are given as an "x" character in the dotted notation of the address. For example, if the address is specified as 192.168.1.1 and the netmask is -255.255.255.0, then the node address will be 192.168.1.1 and its subnet +255.255.255.0, then the node address will be 192.168.1.1, and its subnet is 192.168.1.0. If it is given as 192.168.x.x and 255.255.x.x, then the configurator chooses a subnet address in the range of 192.168.0.0 - -192.168.255.252, and an IP address within the chosen subnet. (The -maximum subnet mask is 255.255.255.252 allows 2 nodes in the subnet.) +192.168.255.252 and an IP address within the chosen subnet. (The +maximum subnet mask is 255.255.255.252, which allows 2 nodes in the subnet.) The following configuration generates network addresses below the -10.0.0.0 address for each link, and assign unique IP addresses to each +10.0.0.0 address for each link and assigns unique IP addresses to each host: @@ -196,11 +196,11 @@ host: The configurator tries to put nodes on the same link into the same -subnet, so its enough to configure the address of only one node on each +subnet, so it's enough to configure the address of only one node on each link. The following example configures a hierarchical network in a way that -keeps routing tables small. +keeps routing tables small: @@ -216,7 +216,7 @@ keeps routing tables small. The XML configuration must contain exactly one ```` element. -Under the root element there can be multiple of the following elements: +Under the root element, there can be multiple of the following elements: The interface element provides configuration parameters for one or more interfaces in the network. The selector attributes limit the scope where @@ -224,71 +224,71 @@ the interface element has effects. The parameter attributes limit the range of assignable addresses and netmasks. The ```` element may contain the following attributes: -- ``@hosts`` Optional selector attribute that specifies a list of +- ``@hosts`` is an optional selector attribute that specifies a list of host name patterns. Only interfaces in the specified hosts are affected. The pattern might be a full path starting from the network, or a module name anywhere in the hierarchy, and other patterns - similar to ini file keys. The default value is "*" that matches all - hosts. e.g. "subnet.client*" or "host\* router[0..3]" or - "area*.*.host[0]" + similar to ini file keys. The default value is "*", which matches all + hosts. For example, "subnet.client*" or "host\* router[0..3]" or + "area*.*.host[0]". -- ``@names`` Optional selector attribute that specifies a list of +- ``@names`` is an optional selector attribute that specifies a list of interface name patterns. Only interfaces with the specified names are - affected. The default value is "*" that matches all interfaces. e.g. - "eth\* ppp0" or "*" + affected. The default value is "*", which matches all interfaces. For + example, "eth\* ppp0" or "*". -- ``@towards`` Optional selector attribute that specifies a list of +- ``@towards`` is an optional selector attribute that specifies a list of host name patterns. Only interfaces connected towards the specified hosts are affected. The specified name will be matched against the - names of hosts that are on the same LAN with the one that is being - configured. This works even if there’s a switch between the - configured host and the one specified here. For wired networks it + names of hosts that are on the same LAN as the one that is being + configured. This works even if there's a switch between the + configured host and the one specified here. For wired networks, it might be easier to specify this parameter instead of specifying the - interface names. The default value is "*". e.g. "ap" or "server" or - "client*" + interface names. The default value is "*". For example, "ap" or + "server" or "client*". -- ``@among`` Optional selector attribute that specifies a list of +- ``@among`` is an optional selector attribute that specifies a list of host name patterns. Only interfaces in the specified hosts connected - towards the specified hosts are affected. The ’among="X Y Z"’ is same - as ’hosts="X Y Z" towards="X Y Z"’. + towards the specified hosts are affected. The 'among="X Y Z"’ is the same + as 'hosts="X Y Z" towards="X Y Z"’. -- ``@address`` Optional parameter attribute that limits the range of - assignable addresses. Wildcards are allowed with using ’x’ as part of +- ``@address`` is an optional parameter attribute that limits the range of + assignable addresses. Wildcards are allowed using the 'x' character as part of the address in place of a byte. Unspecified parts will be filled - automatically by the configurator. The default value "" means that - the address will not be configured. Unconfigured interfaces still - have allocated addresses in their subnets allowing them to become - configured later very easily. e.g. "192.168.1.1" or "10.0.x.x" + automatically by the configurator. The default value is "", which means + that the address will not be configured. Unconfigured interfaces still + have allocated addresses in their subnets, allowing them to become + configured later very easily. For example, "192.168.1.1" or "10.0.x.x". -- ``@netmask`` Optional parameter attribute that limits the range of - assignable netmasks. Wildcards are allowed with using ’x’ as part of +- ``@netmask`` is an optional parameter attribute that limits the range of + assignable netmasks. Wildcards are allowed using the 'x' character as part of the netmask in place of a byte. Unspecified parts will be filled - automatically be the configurator. The default value "" means that - any netmask can be configured. e.g. "255.255.255.0" or "255.255.x.x" - or "255.255.x.0" + automatically by the configurator. The default value is "", which means + that any netmask can be configured. For example, "255.255.255.0" or "255.255.x.x" + or "255.255.x.0". -- ``@mtu`` number Optional parameter attribute to set the MTU - parameter in the interface. When unspecified the interface parameter +- ``@mtu`` is a number optional parameter attribute to set the MTU + parameter in the interface. When unspecified, the interface parameter is left unchanged. -- ``@metric`` number Optional parameter attribute to set the Metric - parameter in the interface. When unspecified the interface parameter +- ``@metric`` is a number optional parameter attribute to set the Metric + parameter in the interface. When unspecified, the interface parameter is left unchanged. Wireless interfaces can similarly be configured by adding ```` elements to the configuration. Each ```` element with a different id defines a separate subnet. -- ``@id`` (optional) identifies wireless network, unique value used - if missed +- ``@id`` (optional) identifies a wireless network, a unique value used + if missed. -- ``@hosts`` Optional selector attribute that specifies a list of +- ``@hosts`` is an optional selector attribute that specifies a list of host name patterns. Only interfaces in the specified hosts are - affected. The default value is "*" that matches all hosts. + affected. The default value is "*", which matches all hosts. -- ``@interfaces`` Optional selector attribute that specifies a list +- ``@interfaces`` is an optional selector attribute that specifies a list of interface name patterns. Only interfaces with the specified names - are affected. The default value is "*" that matches all interfaces. + are affected. The default value is "*", which matches all interfaces. .. _ug:sec:autoconfig:multicast-groups: @@ -296,10 +296,10 @@ Multicast groups ^^^^^^^^^^^^^^^^ Multicast groups can be configured by adding ```` -elements to the configuration file. Interfaces belongs to a multicast -group will join to the group automatically. +elements to the configuration file. Interfaces that belong to a multicast +group will join the group automatically. -For example, +For example: @@ -309,32 +309,32 @@ For example, -adds all Ethernet interfaces of nodes whose name starts with “router” to +This adds all Ethernet interfaces of nodes whose name starts with "router" to the 224.0.0.5 multicast group. The ```` element has the following attributes: -- ``@hosts`` Optional selector attribute that specifies a list of +- ``@hosts`` is an optional selector attribute that specifies a list of host name patterns. Only interfaces in the specified hosts are - affected. The default value is "*" that matches all hosts. + affected. The default value is "*", which matches all hosts. -- ``@interfaces`` Optional selector attribute that specifies a list +- ``@interfaces`` is an optional selector attribute that specifies a list of interface name patterns. Only interfaces with the specified names - are affected. The default value is "*" that matches all interfaces. + are affected. The default value is "*", which matches all interfaces. -- ``@towards`` Optional selector attribute that specifies a list of +- ``@towards`` is an optional selector attribute that specifies a list of host name patterns. Only interfaces connected towards the specified hosts are affected. The default value is "*". -- ``@among`` Optional selector attribute that specifies a list of +- ``@among`` is an optional selector attribute that specifies a list of host name patterns. Only interfaces in the specified hosts connected - towards the specified hosts are affected. The ’among="X Y Z"’ is same - as ’hosts="X Y Z" towards="X Y Z"’. + towards the specified hosts are affected. The 'among="X Y Z"’ is the same + as 'hosts="X Y Z" towards="X Y Z"’. -- ``@address`` Mandatory parameter attribute that specifies a list +- ``@address`` is a mandatory parameter attribute that specifies a list of multicast group addresses to be assigned. Values must be selected - from the valid range of multicast addresses. e.g. "224.0.0.1 - 224.0.1.33" + from the valid range of multicast addresses. For example, "224.0.0.1 + 224.0.1.33". Manual route configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -346,75 +346,77 @@ simulation. The ```` elements of the configuration add a route to the routing tables of selected nodes. The element has the following attributes: -- ``@hosts`` Optional selector attribute that specifies a list of +- ``@hosts`` is an optional selector attribute that specifies a list of host name patterns. Only routing tables in the specified hosts are - affected. The default value "" means all hosts will be affected. e.g. - "host\* router[0..3]" + affected. The default value is "", which means all hosts will be affected. For + example, "host\* router[0..3]". -- ``@destination`` Optional parameter attribute that specifies the +- ``@destination`` is an optional parameter attribute that specifies the destination address in the route (L3AddressResolver syntax). The - default value is "*". e.g. "192.168.1.1" or "subnet.client[3]" or - "subnet.server(ipv4)" or "*" + default value is "*", which means all destinations. For + example, "192.168.1.1" or "subnet.client[3]" or + "subnet.server(ipv4)" or "*". -- ``@netmask`` Optional parameter attribute that specifies the - netmask in the route. The default value is "*". e.g. "255.255.255.0" - or "/29" or "*" +- ``@netmask`` is an optional parameter attribute that specifies the + netmask in the route. The default value is "*", which means all netmasks. For + example, "255.255.255.0" or "/29" or "*". -- ``@gateway`` Optional parameter attribute that specifies the +- ``@gateway`` is an optional parameter attribute that specifies the gateway (next-hop) address in the route (L3AddressResolver syntax). - When unspecified the interface parameter must be specified. The - default value is "*". e.g. "192.168.1.254" or "subnet.router" or "*" + When unspecified, the interface parameter must be specified. The + default value is "*", which means all gateways. For example, + "192.168.1.254" or "subnet.router" or "*". -- ``@interface`` Optional parameter attribute that specifies the - output interface name in the route. When unspecified the gateway - parameter must be specified. This parameter has no default value. - e.g. "eth0" +- ``@interface`` is an optional parameter attribute that specifies the + output interface name in the route. When unspecified, the gateway + parameter must be specified. This parameter has no default value. For + example, "eth0". -- ``@metric`` Optional parameter attribute that specifies the metric +- ``@metric`` is an optional parameter attribute that specifies the metric in the route. The default value is 0. Multicast routing tables can similarly be configured by adding ```` elements to the configuration. -- ``@hosts`` Optional selector attribute that specifies a list of +- ``@hosts`` is an optional selector attribute that specifies a list of host name patterns. Only routing tables in the specified hosts are - affected. e.g. "host\* router[0..3]" + affected. For example, "host\* router[0..3]". -- ``@source`` Optional parameter attribute that specifies the - address of the source network. The default value is "*" that matches +- ``@source`` is an optional parameter attribute that specifies the + address of the source network. The default value is "*", which matches all sources. -- ``@netmask`` Optional parameter attribute that specifies the - netmask of the source network. The default value is "*" that matches +- ``@netmask`` is an optional parameter attribute that specifies the + netmask of the source network. The default value is "*", which matches all sources. -- ``@groups`` Optional List of IPv4 multicast addresses specifying - the groups this entry applies to. The default value is "*" that - matches all multicast groups. e.g. "225.0.0.1 225.0.1.2". +- ``@groups`` is an optional list of IPv4 multicast addresses specifying + the groups this entry applies to. The default value is "*", which + matches all multicast groups. For example, "225.0.0.1 225.0.1.2". -- ``@metric`` Optional parameter attribute that specifies the metric +- ``@metric`` is an optional parameter attribute that specifies the metric in the route. -- ``@parent`` Optional parameter attribute that specifies the name +- ``@parent`` is an optional parameter attribute that specifies the name of the interface the multicast datagrams are expected to arrive. When a datagram arrives on the parent interface, it will be forwarded - towards the child interfaces; otherwise it will be dropped. The + towards the child interfaces; otherwise, it will be dropped. The default value is the interface on the shortest path towards the source of the datagram. -- ``@children`` Mandatory parameter attribute that specifies a list +- ``@children`` is a mandatory parameter attribute that specifies a list of interface name patterns: - - a name pattern (e.g. "ppp*") matches the name of the interface + - a name pattern (e.g. "ppp*") matches the name of the interface. - - a ’towards’ pattern (starting with ">", e.g. ">router*") matches + - a 'towards' pattern (starting with ">", e.g. ">router*") matches the interface by naming one of the neighbor nodes on its link. Incoming multicast datagrams are forwarded to each child interface except the one they arrived in. The following example adds an entry to the multicast routing table of -``router1``, that instructs the routing algorithm to forward +``router1`` that instructs the routing algorithm to forward multicast datagrams whose source is in the 10.0.1.0 network and whose destination address is 225.0.0.1 to send on the ``eth1`` and ``eth2`` interfaces assuming it arrived on the ``eth0`` interface: @@ -440,20 +442,19 @@ network. The configurator can be safely instructed to add default routes where applicable, significantly reducing the size of the host routing tables. -It can also add subnet routes instead of interface routes further -reducing the size of routing tables. Turning on this option requires -careful design to avoid having IP addresses from the same subnet on -different links. +It can also add subnet routes instead of destination interface routes, +further reducing the size of routing tables. Turning on this option +requires careful design to avoid having IP addresses from the same subnet +on different links. .. caution:: - Using manual routes and static route generation - together may have unwanted side effects, because route generation ignores - manual routes. Therefore if the configuration file contains - manual routes, then the :par:`addStaticRoutes` parameter should be set - to ``false``. + Using manual routes and static route generation together may have unwanted + side effects because route generation ignores manual routes. Therefore, + if the configuration file contains manual routes, then the :par:`addStaticRoutes` + parameter should be set to ``false``. Route optimization ^^^^^^^^^^^^^^^^^^ @@ -467,7 +468,7 @@ The optimization is performed by merging routes whose gateway and outgoing interface is the same by finding a common prefix that matches only those routes. The resulting routing table might be different in that it will route packets that the original routing table did not. -Nevertheless the following invariant holds: any packet routed by the +Nevertheless, the following invariant holds: any packet routed by the original routing table (has matching route) will still be routed the same way by the optimized routing table. @@ -520,44 +521,41 @@ This list summarize the parameters of the :ned:`Ipv4NetworkConfigurator`: Ipv4FlatNetworkConfigurator (Legacy) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :ned:`Ipv4FlatNetworkConfigurator` module configures IP addresses -and routes of IP nodes of a network. All assigned addresses share a -common subnet prefix, the network topology will be ignored. Shortest -path routes are also generated from any node to any other node of the -network. The Gateway (next hop) field of the routes is not filled in by -these configurator, so it relies on proxy ARP if the network spans -several LANs. It does not perform routing table optimization (i.e. -merging similar routes into a single, more general route.) - - +The :ned:`Ipv4FlatNetworkConfigurator` module configures IP addresses and routes +of IP nodes of a network. All assigned addresses share a common subnet +prefix, and the network topology will be ignored. Shortest path routes +are also generated from any node to any other node of the network. The +Gateway (next hop) field of the routes is not filled in by these +configurators, so it relies on proxy ARP if the network spans several LANs. +It does not perform routing table optimization (i.e. merging similar routes +into a single, more general route). .. warning:: - :ned:`Ipv4FlatNetworkConfigurator` is considered - legacy, do not use it for new projects. + The :ned:`Ipv4FlatNetworkConfigurator` is considered legacy and should not + be used for new projects. -The :ned:`Ipv4FlatNetworkConfigurator` module configures the network -when it is initialized. The configuration is performed in stage 2, after -interface tables are filled in. Do not use a -:ned:`Ipv4FlatNetworkConfigurator` module together with static routing -files, because they can iterfere with the configurator. +The :ned:`Ipv4FlatNetworkConfigurator` module configures the network when it +is initialized. The configuration is performed in stage 2, after interface +tables are filled in. Do not use an :ned:`Ipv4FlatNetworkConfigurator` module +together with static routing files because they can interfere with the +configurator. -The :ned:`Ipv4FlatNetworkConfigurator` searches each IP nodes of the -network. (IP nodes are those modules that have the @node NED property -and has a :ned:`Ipv4RoutingTable` submodule named “routingTable”). The -configurator then assigns IP addresses to the IP nodes, controlled by -the following module parameters: +The :ned:`Ipv4FlatNetworkConfigurator` searches each IP node of the network +(modules that have the @node NED property and have an :ned:`Ipv4RoutingTable` +submodule named "routingTable"). The configurator then assigns IP addresses +to the IP nodes, controlled by the following module parameters: -- :par:`netmask` common netmask of the addresses (default is - 255.255.0.0) +- :par:`netmask` - the common netmask of the addresses (default is + 255.255.0.0). -- :par:`networkAddress` higher bits are the network part of the - addresses, lower bits should be 0. (default is 192.168.0.0) +- :par:`networkAddress` - higher bits are the network part of the + addresses, lower bits should be 0 (default is 192.168.0.0). -With the default parameters the assigned addresses are in the range -192.168.0.1 - 192.168.255.254, so there can be maximum 65534 nodes in -the network. The same IP address will be assigned to each interface of -the node, except the loopback interface which always has address +With the default parameters, the assigned addresses are in the range +192.168.0.1 - 192.168.255.254, so there can be a maximum of 65,534 nodes +in the network. The same IP address will be assigned to each interface of +the node, except the loopback interface, which always has address 127.0.0.1 (with 255.0.0.0 mask). After assigning the IP addresses, the configurator fills in the routing @@ -705,26 +703,24 @@ is also accepted with the meaning ``0.0.0.0``. .. important:: - The meaning of the routes where the destination is a multicast address - has been changed in version 1.99.4. Earlier these entries was used - both to select the outgoing interfaces of multicast datagrams - sent by the higher layer (if multicast interface was otherwise unspecified) - and to select the outgoing interfaces of datagrams that are received from - the network and forwarded by the node. - - From version 1.99.4 multicast routing applies reverse path forwarding. - This requires a separate routing table, that can not be populated from - the old routing table entries. Therefore simulations that use multicast - forwarding can not use the old configuration files, they should be - migrated to use an :ned:`Ipv4NetworkConfigurator` instead. - - Some change is needed in models that use link-local multicast too. - Earlier if the IP module received a datagram from the higher layer - and multiple routes was given for the multicast group, - then IP sent a copy of the datagram on each interface of that routes. - From version 1.99.4, only the first matching interface is used (considering - longest match). If the application wants to send the multicast datagram - on each interface, then it must explicitly loop and specify the multicast + The meaning of the routes where the destination is a multicast address has been + changed in version 1.99.4. Earlier, these entries were used both to select the + outgoing interfaces of multicast datagrams sent by the higher layer (if multicast + interface was otherwise unspecified) and to select the outgoing interfaces of + datagrams that are received from the network and forwarded by the node. + + From version 1.99.4, multicast routing applies reverse path forwarding. This + requires a separate routing table, which cannot be populated from the old routing + table entries. Therefore, simulations that use multicast forwarding cannot use + the old configuration files; they should be migrated to use an + :ned:`Ipv4NetworkConfigurator` instead. + + Some change is needed in models that use link-local multicast too. Earlier, if the + IP module received a datagram from the higher layer and multiple routes were given + for the multicast group, then IP sent a copy of the datagram on each interface of + that route. From version 1.99.4, only the first matching interface is used + (considering the longest match). If the application wants to send the multicast + datagram on each interface, then it must explicitly loop and specify the multicast interface. .. _ug:sec:autoconfig:configuring-layer-2: @@ -753,5 +749,6 @@ and sets cost=19 and priority=32768: -For more information about the usage of the selector attributes see +For more information about the usage of the selector attributes, see :ned:`Ipv4NetworkConfigurator`. + diff --git a/doc/src/users-guide/ch-network-interfaces.rst b/doc/src/users-guide/ch-network-interfaces.rst index aadea4d2e07..248f7e30983 100644 --- a/doc/src/users-guide/ch-network-interfaces.rst +++ b/doc/src/users-guide/ch-network-interfaces.rst @@ -32,11 +32,11 @@ list gives the most commonly used network interfaces. - :ned:`PppInterface` is for wired links using :protocol:`PPP` -- :ned:`Ieee80211Interface` represents a Wifi (:protocol:`IEEE 802.11`) +- :ned:`Ieee80211Interface` represents a Wi-Fi (:protocol:`IEEE 802.11`) interface - :ned:`Ieee802154NarrowbandInterface` and :ned:`Ieee802154UwbIrInterface` - represent a :protocol:`IEEE 802.15.4` interface + represent an :protocol:`IEEE 802.15.4` interface - :ned:`BMacInterface`, :ned:`LMacInterface`, :ned:`XMacInterface` provide low-power wireless sensor MAC protocols along with a simple @@ -65,7 +65,7 @@ Typical ingredients are: - *Layer 2 protocol implementation*. For some interfaces such as :ned:`PppInterface` this is a single module; for others like Ethernet - and Wifi it consists of separate modules for MAC, LLC, and possibly + and Wi-Fi it consists of separate modules for MAC, LLC, and possibly other subcomponents. - *PHY model*. Some interfaces also contain separate module(s) that @@ -103,8 +103,8 @@ a hard limit for the queue length in a module parameter – if this is exceeded, the simulation stops with an error. When the :par:`typename` parameter of the queue module is not empty, it must -name a NED type that implements the :ned:`IPacketQueue` interface. The -queue module model allows modeling a finite buffer, or implement various +name an NED type that implements the :ned:`IPacketQueue` interface. The +queue module model allows modeling a finite buffer, or implementing various queueing policies for QoS and/or RED. The most frequently used module type for the queue module is @@ -143,7 +143,7 @@ defined with parametric types, like this: Traffic conditioners allow one to implement the policing and shaping actions of a Diffserv router. They are added to the input or output -packets paths in the network interface. (On the output path they are +packets paths in the network interface. (On the output path, they are added before the queue module.) Traffic conditioners must implement the :ned:`ITrafficConditioner` @@ -152,7 +152,7 @@ components (see chapter :doc:`ch-diffserv`). There is no preassembled traffic conditioner in INET, but you can find some in the example simulations. -An example configuration with fictituous types: +An example configuration with fictitious types: .. code-block:: ini @@ -166,9 +166,9 @@ The Interface Table Network nodes normally contain an :ned:`InterfaceTable` module. The interface table is a sort of registry of all the network interfaces in -the host. It does not send or receive messages, other modules access it +the host. It does not send or receive messages; other modules access it via C++ function calls. Contents of the interface table can also be -inspected e.g. in Qtenv. +inspected, e.g., in Qtenv. Network interfaces register themselves in the interface table at the beginning of the simulation. Registration is usually the task of the MAC @@ -179,13 +179,13 @@ beginning of the simulation. Registration is usually the task of the MAC Wired Network Interfaces ------------------------ -Wired interfaces have a pair of special purpose OMNeT++ gates which +Wired interfaces have a pair of special-purpose OMNeT++ gates which represent the capability of having an external physical connection to -another network node (e.g. Ethernet port). In order to make wired +another network node (e.g., Ethernet port). In order to make wired communication work, these gates must be connected with special connections which represent the physical cable between the physical -ports. The connections must use special OMNeT++ channels (e.g. -:ned:`DatarateChannel`) which determine datarate and delay parameters. +ports. The connections must use special OMNeT++ channels (e.g., +:ned:`DatarateChannel`) which determine data rate and delay parameters. Wired network interfaces are compound modules that implement the :ned:`IWiredInterface` interface. INET has the following wired network @@ -227,7 +227,7 @@ modeling of the physical layer, a PHY module is an indispensable part of a wireless interface. Wireless network interfaces are compound modules that implement the -:ned:`IWirelessInterface` interface. In the following sections we give +:ned:`IWirelessInterface` interface. In the following sections, we give an overview of the wireless interfaces available in INET. .. _ug:sec:interfaces:generic-wireless-interface: @@ -254,7 +254,7 @@ and the radio modules are fixed to a particular value. One example is IEEE 802.11 ~~~~~~~~~~~ -IEEE 802.11 or Wifi network interfaces (:ned:`Ieee80211Interface`), +IEEE 802.11 or Wi-Fi network interfaces (:ned:`Ieee80211Interface`), alongside with models of devices acting as access points (AP), are covered in chapter :doc:`ch-80211`. @@ -324,7 +324,7 @@ optional out-of-band acknowledgement mechanism (using C++ function calls, not actual wirelessly sent frames), which is turned on by default. There is no retransmission: if the acknowledgement does not arrive after the first transmission, the MAC gives up and counts the -packet as failed transmission. +packet as a failed transmission. .. _ug:sec:interfaces:shortcut: @@ -354,8 +354,8 @@ Tunnelling :ned:`TunInterface` is a virtual network interface that can be used for creating tunnels, but it is more powerful than that. It lets an application-layer module capture packets sent to the TUN interface and -do whatever it pleases with it (including sending it to a peer entity in -an UDP or plain IPv4 packet.) +do whatever it pleases with them (including sending them to a peer entity in +a UDP or plain IPv4 packet.) To set up a tunnel, add an instance of :ned:`TunnelApp` to the node, and specify the protocol (IPv4 or UDP) and the remote endpoint of the tunnel @@ -383,7 +383,7 @@ chapter :doc:`ch-emulation`. Custom Network Interfaces ------------------------- -It’s also possible to build custom network interfaces, the following +It is also possible to build custom network interfaces. The following example shows how to build a custom wireless interface. .. literalinclude:: lib/Snippets.ned @@ -395,9 +395,10 @@ example shows how to build a custom wireless interface. The above network interface contains very simple hypothetical MAC and PHY protocols. The MAC protocol only provides acknowledgment without other services (e.g., carrier sense, collision avoidance, collision -detection), the PHY protocol uses one of the predefined APSK modulations +detection), and the PHY protocol uses one of the predefined APSK modulations for the whole signal (preamble, header, and data) without other services (e.g., scrambling, interleaving, forward error correction). .. [1] OMNeT++ ``sendDirect()`` calls + diff --git a/doc/src/users-guide/ch-network-nodes.rst b/doc/src/users-guide/ch-network-nodes.rst index bb7d5bbcf77..a7b17b99b90 100644 --- a/doc/src/users-guide/ch-network-nodes.rst +++ b/doc/src/users-guide/ch-network-nodes.rst @@ -53,7 +53,7 @@ modules fall into the following broad categories: :ned:`Ipv4NetworkLayer` for :protocol:`IPv4`, and :ned:`Ipv6NetworkLayer` for :protocol:`IPv6`. The :ned:`Ipv4NetworkLayer` module contains several protocol modules: - :ned:`Ipv4`, :ned:`Arp`, :ned:`Icmp` and :ned:`Icmpv6`. + :ned:`Ipv4`, :ned:`Arp`, :ned:`Icmp`, and :ned:`Icmpv6`. - *Network interfaces* are represented by compound modules which are connected to the network layer protocols and other network interfaces @@ -115,7 +115,7 @@ fashion, and ensure that messages and packets sent from one component end up being delivered to the correct component. Dispatchers need no manual configuration, as they use discovery and peek into packets. -In there pre-assembled node models, dispatchers allow arbitrary protocol +In their pre-assembled node models, dispatchers allow arbitrary protocol components to talk directly to each other, i.e. not only to ones in neighboring layers. @@ -186,7 +186,7 @@ following line to the ini file: **.host*.tcp.typename = "TcpLwip" # use lwIP's TCP implementation Submodule vectors with parametric types are defined without the use of a -module parameter to allow elements have different types. An example is +module parameter to allow elements to have different types. An example is how applications are defined in hosts: .. code-block:: ned @@ -204,13 +204,12 @@ And applications can be added in the following way: Inheritance ~~~~~~~~~~~ -Inheritance can be use to derive new, specialized node types from +Inheritance can be used to derive new, specialized node types from existing ones. A derived NED type may add new parameters, gates, -submodules or connections, and may set inherited unassigned parameters +submodules, or connections, and may set inherited unassigned parameters to specific values. -For example, :ned:`WirelessHost` is derived from :ned:`StandardHost` in -the following way: +For example, :ned:`WirelessHost` is derived from :ned:`StandardHost` in the following way: .. code-block:: ned diff --git a/doc/src/users-guide/ch-networks.rst b/doc/src/users-guide/ch-networks.rst index 5fdb2d9c722..1fd65aa05fe 100644 --- a/doc/src/users-guide/ch-networks.rst +++ b/doc/src/users-guide/ch-networks.rst @@ -9,29 +9,29 @@ Overview -------- INET heavily builds upon the modular architecture of OMNeT++. It -provides numerous domain specific and highly parameterizable components -which can be combined in many ways. The primary means of building large +provides numerous domain-specific and highly parameterizable components +that can be combined in many ways. The primary means of building large custom network simulations in INET is the composition of existing models with custom models, starting from small components and gradually forming ever larger ones up until the composition of the network. Users are not required to have programming experience to create simulations unless they also want to implement their own protocols, for example. -Assembling an INET simulation starts with defining a module representing -the network. Networks are compound modules which contain network nodes, -automatic network configurators, and sometimes additionally transmission -medium, physical environment, various visualizer, and other -infrastructure related modules. Networks also contain connections +Assembling an INET simulation starts with defining a module that represents +the network. Networks are compound modules that contain network nodes, +automatic network configurators, and sometimes additionally a transmission +medium, physical environment, various visualizers, and other +infrastructure-related modules. Networks also contain connections between network nodes representing cables. Large hierarchical networks may be further organized into compound modules to directly express the hierarchy. -There are no predefined networks in INET, because it is very easy to -create one, and because of the vast possibilities. However, the OMNeT++ +There are no predefined networks in INET because it is very easy to +create one and because of the vast possibilities. However, the OMNeT++ IDE provides several topology generator wizards for advanced scenarios. As INET is an OMNeT++-based framework, users mainly use NED to describe -the model topology, and ini files to provide configuration. +the model topology and ini files to provide configuration. .. _ug:sec:networks:built-in-network-nodes-and-other-top-level-modules: @@ -49,7 +49,7 @@ taste of the built-in network nodes. :protocol:`UDP`, :protocol:`TCP`, :protocol:`IPv4`, :protocol:`IPv6`, :protocol:`Ethernet`, :protocol:`IEEE 802.11`. It also supports an optional mobility model, optional energy models, and any number of - applications which are entirely configurable from INI files. + applications that are entirely configurable from INI files. - :ned:`EthernetSwitch` models an :protocol:`Ethernet` switch containing a relay unit and one MAC unit per port. @@ -63,54 +63,54 @@ taste of the built-in network nodes. - :ned:`WirelessHost` provides a network node with one (default) :protocol:`IEEE 802.11` network interface in infrastructure mode, - suitable for using with an :ned:`AccessPoint`. + suitable for use with an :ned:`AccessPoint`. - :ned:`AdhocHost` is a :ned:`WirelessHost` with the network interface configured in ad-hoc mode and forwarding enabled. Network nodes communicate at the network level by exchanging OMNeT++ -messages which are the abstract representations of physical signals on +messages, which are the abstract representations of physical signals on the transmission medium. Signals are either sent through OMNeT++ -connections in the wired case, or sent directly to the gate of the +connections in the wired case or sent directly to the gate of the receiving network node in the wireless case. Signals encapsulate INET-specific packets that represent the transmitted digital data. Packets are further divided into chunks that provide alternative -representations for smaller pieces of data (e.g. protocol headers, +representations for smaller pieces of data (e.g., protocol headers, application data). -Additionally, there are components that occur on network level, but they +Additionally, there are components that occur on the network level, but they are not models of physical network nodes. They are necessary to model other aspects. Some of them are: - A *radio medium* module such as :ned:`Ieee80211RadioMedium`, - :ned:`ScalarRadioMedium` and :ned:`UnitDiskRadioMedium` (there + :ned:`ScalarRadioMedium`, and :ned:`UnitDiskRadioMedium` (there are a few of them) are a required component of wireless networks. - :ned:`PhysicalEnvironment` models the effect of the physical - environment (i.e. obstacles) on radio signal propagation. It is an + environment (i.e., obstacles) on radio signal propagation. It is an optional component. -- *Configurators* such as :ned:`Ipv4NetworkConfigurator`, - :ned:`L2NetworkConfigurator` and :ned:`NextHopNetworkConfigurator` +- *Configurators*, such as :ned:`Ipv4NetworkConfigurator`, + :ned:`L2NetworkConfigurator`, and :ned:`NextHopNetworkConfigurator`, configure various aspects of the network. For example, :ned:`Ipv4NetworkConfigurator` assigns IP addresses to hosts and - routers, and sets up static routing. It is used when modeling dynamic - IP address assignment (e.g. via DHCP) or dynamic routing is not of + routers and sets up static routing. It is used when modeling dynamic + IP address assignment (e.g., via DHCP) or when dynamic routing is not of importance. :ned:`L2NetworkConfigurator` allows one to configure 802.1 LANs and provide STP/RSTP-related parameters such as link cost, - port priority and the “is-edge” flag. + port priority, and the “is-edge” flag. - :ned:`ScenarioManager` allows scripted scenarios, such as timed failure and recovery of network nodes. - *Group coordinators* are needed for the operation of some group - mobility mdels. For example, :ned:`MoBanCoordinator` is the + mobility models. For example, :ned:`MoBanCoordinator` is the coordinator module for the MoBAN mobility model. -- *Visualizers* like :ned:`PacketDropOsgVisualizer` provide graphical - rendering of some aspect of the simulation either in 2D (canvas) or +- *Visualizers*, like :ned:`PacketDropOsgVisualizer`, provide graphical + rendering of some aspect of the simulation, either in 2D (canvas) or 3D (using OSG or osgEarth). The usual choice is - :ned:`IntegratedVisualizer` which bundles together an instance of + :ned:`IntegratedVisualizer`, which bundles together an instance of each specific visualizer type in a compound module. .. _ug:sec:networks:typical-networks: @@ -123,19 +123,19 @@ Typical Networks Wired Networks ~~~~~~~~~~~~~~ -Wired network connections, for example :protocol:`Ethernet` cables, are +Wired network connections, for example, :protocol:`Ethernet` cables, are represented with standard OMNeT++ connections using the :ned:`DatarateChannel` NED type. The channel’s :par:`datarate` and :par:`delay` parameters must be provided for all wired connections. The number of wired interfaces in a host (or router) usually does -not need to be manually configured, because it can be automatically +not need to be manually configured because it can be automatically inferred from the actual number of links to neighbor nodes. The following example shows how straightforward it is to create a model for a simple wired network. This network contains a server connected to a router using :protocol:`PPP`, which in turn is connected to a switch using :protocol:`Ethernet`. The network also contains a parameterizable -number of clients, all connected to the switch forming a star topology. +number of clients, all connected to the switch, forming a star topology. The utilized network nodes are all predefined modules in INET. To avoid the manual configuration of IP addresses and routing tables, an automatic network configurator is also included. @@ -150,7 +150,7 @@ In order to run a simulation using the above network, an OMNeT++ INI file must be created. The INI file selects the network, sets its number of clients parameter, and configures a simple :protocol:`TCP` application for each client. The server is configured to have a -:protocol:`TCP` application which echos back all data received from the +:protocol:`TCP` application that echos back all data received from the clients individually. .. literalinclude:: lib/Snippets.ini @@ -171,7 +171,7 @@ Wireless Networks ~~~~~~~~~~~~~~~~~ Wireless network connections are not modeled with OMNeT++ connections -due the dynamically changing nature of connectivity. For wireless +due to the dynamically changing nature of connectivity. For wireless networks, an additional module, one that represents the transmission medium, is required to maintain connectivity information. @@ -216,15 +216,15 @@ Mobile Ad hoc Networks Frequent Tasks (How To...) -------------------------- -This section contains quick and somewhat superficial advice to many practical tasks. +This section contains quick and somewhat superficial advice on many practical tasks. .. _ug:sec:networks:automatic-wired-interfaces: Automatic Wired Interfaces ~~~~~~~~~~~~~~~~~~~~~~~~~~ -In many wired network simulations, the number of wired interfaces need -not be manually configured, because it can be automatically inferred +In many wired network simulations, the number of wired interfaces does +not need to be manually configured because it can be automatically inferred from the actual number of connections between network nodes. .. literalinclude:: lib/Snippets.ned @@ -283,13 +283,13 @@ Node Failure and Recovery Enabling Dual IP Stack ~~~~~~~~~~~~~~~~~~~~~~ -All built-in network nodes support dual Internet protocol stacks, that -is both :protocol:`IPv4` and :protocol:`IPv6` are available. They are +All built-in network nodes support dual Internet protocol stacks, that is, +both :protocol:`IPv4` and :protocol:`IPv6` are available. They are also supported by transport layer protocols, link layer protocols, and most applications. Only :protocol:`IPv4` is enabled by default, so in order to use :protocol:`IPv6`, it must be enabled first, and an -application supporting :protocol:`IPv6` (e.g., :ned:`PingApp` must be -used). The following example shows how to configure two ping +application supporting :protocol:`IPv6` (e.g., :ned:`PingApp`) must be +used. The following example shows how to configure two ping applications in a single node where one is using an :protocol:`IPv4` and the other is using an :protocol:`IPv6` destination address. diff --git a/doc/src/users-guide/ch-other-network-protocols.rst b/doc/src/users-guide/ch-other-network-protocols.rst index 2f7d8548472..89f8c858afd 100644 --- a/doc/src/users-guide/ch-other-network-protocols.rst +++ b/doc/src/users-guide/ch-other-network-protocols.rst @@ -10,7 +10,7 @@ Overview Network layer protocols in INET are not restricted to IPv4 and IPv6. INET nodes such as :ned:`Router` and :ned:`StandardHost` can be -configured to use an alternative network layer protocols instead of, or +configured to use alternative network layer protocols instead of, or in addition to, IPv4 and IPv6. Node models contain three optional network layers that can be @@ -43,7 +43,7 @@ The list of alternative network layers includes: concrete protocol type is a parameter - :ned:`NextHopNetworkLayer` is a network layer specialized for the - “Next-Hop Forwarding Protocol”, an abstract implementation of the + "Next-Hop Forwarding Protocol", an abstract implementation of the next-hop routing concept - :ned:`WiseRouteNetworkLayer` is specialized for the Wise Route @@ -69,8 +69,8 @@ instance of :ned:`EchoProtocol`, a module type that implements a simple *ping*-like protocol. All the above network protocols can work with IPv4 addresses, IPv6 -addresses, use MAC address as network address (this is sometimes useful -in WSNs), or use sythetic addresses that only make sense within the +addresses, use MAC address as a network address (this is sometimes useful +in WSNs), or use synthetic addresses that only make sense within the simulation. [1]_ In apps, you need to specify which network layer protocol you want to @@ -93,7 +93,7 @@ Flooding ~~~~~~~~ :ned:`Flooding` is a simple flooding protocol for network-level -broadcast. It remembers already broadcast messages, and does not +broadcast. It remembers already broadcast messages and does not rebroadcast them if it gets another copy of that message. .. _ug:sec:networkprotocols:probabilisticbroadcast: @@ -128,14 +128,14 @@ WiseRoute :ned:`WiseRoute` implements Wise Route, a simple loop-free routing algorithm that builds a routing tree from a central network point, -designed for sensor networks and convergecast traffic (WIreless SEnsor +designed for sensor networks and convergecast traffic (Wireless Sensor routing). The sink (the device at the center of the network) broadcasts a route building message. Each network node that receives it selects the sink as -parent in the routing tree, and rebroadcasts the route building message. +a parent in the routing tree and rebroadcasts the route building message. This procedure maximizes the probability that all network nodes can join -the network, and avoids loops. +the network and avoids loops. The :par:`sinkAddress` parameter specifies the sink network address, :par:`rssiThreshold` is a threshold to avoid using bad links (with too @@ -154,7 +154,7 @@ The :ned:`NextHopForwarding` module is an implementation of the next-hop forwarding concept. (It can be thought of as an abstracted version of IP.) -The protocol needs an additional module, a :ned:`NextHopRoutingTable` +The protocol needs an additional module, a :ned:`NextHopRoutingTable`, for its operation. The routing table module is included in the :ned:`NextHopNetworkLayer` compound module. @@ -175,7 +175,7 @@ The following address types are available: - module path -Protocols described in this chapter work with “generic” L3 addresses, +Protocols described in this chapter work with "generic" L3 addresses; they can use any address type. When choosing IPv4 addresses, an :ned:`Ipv4NetworkConfigurator` global @@ -193,5 +193,5 @@ IPv4, :ned:`Arp` can be used instead of :ned:`GlobalArp`. .. [1] This is possible because the implementation of these modules simply - use the :cpp:`L3Address` C++ class, which is a variant type capable - of holding several types of L3 addresses. + uses the :cpp:`L3Address` C++ class, which is a variant type capable + of holding several types of L3 addresses. \ No newline at end of file diff --git a/doc/src/users-guide/ch-packetfilter.rst b/doc/src/users-guide/ch-packetfilter.rst index 837b84ca3b8..f84cd733c24 100644 --- a/doc/src/users-guide/ch-packetfilter.rst +++ b/doc/src/users-guide/ch-packetfilter.rst @@ -6,26 +6,26 @@ Packet Filter Expressions A packet filter expression takes a packet as input and returns a boolean value as output. It is used in many modules such as packet filters, packet classifiers, packet schedulers, various visualizers, and so on. The filter expression can be -either a simple string literal or a full blown NED expression. +either a simple string literal or a full-blown NED expression. The string variant is basically a pattern that is matched against the name of -the packet. It can still contain boolean operators such as and/or/not but it +the packet. It can still contain boolean operators such as and/or/not, but it cannot refer to any part of the packet other than its name. For example, the following pattern matches all packets having a name that starts -with 'ping' and that doesn't end with 'reply': +with ``"ping"`` and that don't end with ``"reply"``: :ini:`"ping* and not *reply"` The expression variant is evaluated by the module for each packet as needed. The -expression can contain all NED expression syntax in addition to several implicitly +expression can contain all NED expression syntax, in addition to several implicitly defined variables as shown below. The implicitly defined variables can refer to -the packet itself, to a protocol specific chunk, to a chunk with a specific chunk -type, or to a packet tag with a specific type. +the packet itself, a protocol-specific chunk, a chunk with a specific chunk +type, or a packet tag with a specific type. The following list gives a few examples: -:ini:`expr(hasBitError)` matches packets with bit error +:ini:`expr(hasBitError)` matches packets with a bit error :ini:`expr(name == 'P1')` matches packets having 'P1' as their name @@ -33,7 +33,8 @@ The following list gives a few examples: :ini:`expr(totalLength >= 100B)` matches packets longer than 100 bytes -Implicitly defined variables can be used to check the presence of a chunk of a specific protocol or of a chunk of a specific type: +Implicitly defined variables can be used to check the presence of a chunk of a +specific protocol or of a chunk of a specific type: :ini:`expr(udp != null)` matches packets that have at least one UDP protocol chunk @@ -41,15 +42,15 @@ Implicitly defined variables can be used to check the presence of a chunk of a s :ini:`expr(has(udp[0]))` same as above using indexing -:ini:`expr(has(UdpHeader))` matches packets that have at least one chunk with UdpHeader type +:ini:`expr(has(UdpHeader))` matches packets that have at least one chunk with the UdpHeader type :ini:`expr(has(UdpHeader[0]))` same as above using indexing :ini:`expr(has(ipv4))` matches packets that have at least one IPv4 protocol chunk -:ini:`expr(has(ipv4[0]))` a packet may contain multiple protocol headers, they can be indexed +:ini:`expr(has(ipv4[0]))` a packet may contain multiple protocol headers; they can be indexed -:ini:`expr(has(Ipv4Header))` matches packets that have at least one chunk with Ipv4Header type +:ini:`expr(has(Ipv4Header))` matches packets that have at least one chunk with the Ipv4Header type :ini:`expr(has(Ipv4Header[0]))` same as above using indexing @@ -59,7 +60,7 @@ Implicitly defined variables can be used to check the presence of a chunk of a s :ini:`expr(has(ethernetmac[1]))` this would most likely match the Ethernet FCS chunk -:ini:`expr(has(EthernetMacHeader))` matches packets that have at least one chunk with EthernetMacHeader type +:ini:`expr(has(EthernetMacHeader))` matches packets that have at least one chunk with the EthernetMacHeader type :ini:`expr(has(EthernetMacHeader[0]))` same as above using indexing @@ -69,11 +70,10 @@ The expression can also refer to fields of chunks: :ini:`expr(ipv4.destAddress.str() == '10.0.0.1')` same as above using strings -:ini:`expr(ipv4.destAddress.str() =~ '10.0.0.*')` matches packets that have an IPv4 destination address starting with '10.0.0.' +:ini:`expr(ipv4.destAddress.str() =~ '10.0.0.*')` matches packets that have an IPv4 destination address starting with 10.0.0. -:ini:`expr(udp.destPort == 42)` matches packets if the UDP destination port number equals to 42 +:ini:`expr(udp.destPort == 42)` matches packets if the UDP destination port number equals 42 -It's also possible to combine expressions using boolean operators: +It is also possible to combine expressions using boolean operators: :ini:`expr(name == 'P1' && totalLength == 128B && ipv4.destAddress.str() == '10.0.0.1' && udp.destPort == 42)` - diff --git a/doc/src/users-guide/ch-physicallayer.rst b/doc/src/users-guide/ch-physicallayer.rst index a0e5283fbc7..9c3491dc566 100644 --- a/doc/src/users-guide/ch-physicallayer.rst +++ b/doc/src/users-guide/ch-physicallayer.rst @@ -41,7 +41,7 @@ generic, often used implementation of :ned:`IRadio` is the :ned:`Radio` NED type. :ned:`Radio` is an active compound module, that is, it has an associated C++ class that encapsulates the computations. -:ned:`Radio` contains its antenna, transmitter, receiver and energy +:ned:`Radio` contains its antenna, transmitter, receiver, and energy consumer models as submodules with parametric types: .. code-block:: ned @@ -64,11 +64,11 @@ Components of a Radio Antenna Models ~~~~~~~~~~~~~~ -The antenna model describes the effects of the physical device which +The antenna model describes the effects of the physical device that converts electric signals into radio waves, and vice versa. This model captures the antenna characteristics that heavily affect the quality of the communication channel. For example, various antenna shapes, antenna -size and geometry, antenna arrays, and antenna orientation causes +size and geometry, antenna arrays, and antenna orientation cause different directional or frequency selectivity. The antenna model provides a position and an orientation using a @@ -95,10 +95,10 @@ provides some examples: Transmitter Models ~~~~~~~~~~~~~~~~~~ -The transmitter model describes the physical process which converts +The transmitter model describes the physical process that converts packets into electric signals. In other words, this model converts an L2 frame into a signal that is transmitted on the medium. The conversion -process and the representation of the signal depends on the level of +process and the representation of the signal depend on the level of detail and the physical characteristics of the implemented protocol. There are two main levels of detail (or modeling depths): @@ -131,13 +131,13 @@ Some of the transmitter types available in INET: Receiver Models ~~~~~~~~~~~~~~~ -The receiver model describes the physical process which converts +The receiver model describes the physical process that converts electric signals into packets. In other words, this model converts a reception, along with an interference computed by the medium model, into a MAC packet and a reception indication. For a packet to be received successfully, reception must be *possible* -(based on reception power, bandwidth, modulation scheme and other +(based on reception power, bandwidth, modulation scheme, and other characteristics), it must be *attempted* (i.e. the receiver must synchronize itself on the preamble and start receiving), and it must be *successful* (as determined by the error model and the simulated part of @@ -171,21 +171,20 @@ Some of the receiver types available in INET: Error Models ~~~~~~~~~~~~ -Determining reception errors is a crucial part of the reception process. -There are often several different statistical error models in the -literature even for a particular physical layer. In order to support -this diversity, the error model is a separate replaceable component of -the receiver. +Determining reception errors is a crucial part of the reception process. There +are often several different statistical error models in the literature even for +a particular physical layer. To support this diversity, the error model is a +separate replaceable component of the receiver. -The error model describes how the signal to noise ratio affects the +The error model describes how the signal-to-noise ratio affects the amount of errors at the receiver. The main purpose of this model is to determine whether the received packet has errors or not. It also -computes various physical layer indications for higher layers such as +computes various physical layer indications for higher layers, such as packet error rate, bit error rate, and symbol error rate. For the -layered reception model it needs to compute the erroneous bits, symbols, +layered reception model, it needs to compute the erroneous bits, symbols, or samples depending on the lowest simulated physical domain where the real decoding starts. The error model is optional (if omitted, all -receptions are considered successful.) +receptions are considered successful). The following list provides some examples: @@ -206,18 +205,18 @@ Power Consumption Models A substantial part of the energy consumption of communication devices comes from transmitting and receiving signals. The energy consumer model describes how the radio consumes energy depending on its activity. This -model is optional (if omitted, energy consumption is ignored.) +model is optional (if omitted, energy consumption is ignored). The following list provides some examples: - :ned:`StateBasedEpEnergyConsumer`: power consumption is determined by - the radio state (a combination of radio mode, transmitter state and + the radio state (a combination of radio mode, transmitter state, and receiver state), and specified in parameters like :par:`receiverIdlePowerConsumption` and :par:`receiverReceivingDataPowerConsumption`, in watts. - :ned:`StateBasedCcEnergyConsumer`: similar to the previous one, but - consumption is given in ampères. + consumption is given in amperes. .. _ug:sec:phy:layered-radio-models: @@ -225,7 +224,7 @@ Layered Radio Models -------------------- In layered radio models, the transmitter and receiver models are split -to several stages to allow more fine-grained modeling. +into several stages to allow more fine-grained modeling. For transmission, processing steps such as packet serialization, forward error correction (FEC) encoding, scrambling, interleaving, and @@ -322,19 +321,19 @@ APSK Radio ~~~~~~~~~~ APSK radio models provide a hypothetical radio that simulates one of the -well-known ASP, PSK and QAM modulations. (APSK stands for Amplitude and +well-known APSK, PSK, and QAM modulations. (APSK stands for Amplitude and Phase-Shift Keying.) -APSK radio has scalar/dimensional, and flat/layered variants. The flat -variants, :ned:`ApskScalarRadio` and :ned:`ApskDimensionalRadio` model -frame transmissons in the selected modulation scheme but without +APSK radio has scalar/dimensional and flat/layered variants. The flat +variants, :ned:`ApskScalarRadio` and :ned:`ApskDimensionalRadio`, model +frame transmissions in the selected modulation scheme but without utilizing other techniques such as forward error correction (FEC), interleaving, spreading, etc. These radios require matching medium models, :ned:`ScalarRadioMedium` and :ned:`DimensionalRadioMedium`. -The layered version, :ned:`ApskLayeredRadio` can not only model the processing -steps missing from their simpler counterparts, they also feature +The layered version, :ned:`ApskLayeredRadio`, can not only model the processing +steps missing from their simpler counterparts, but they also feature a configurable level of detail: the transmitter and receiver modules have :par:`levelOfDetail` parameters that control which domains are actually simulated. These radio models must be used in conjunction with diff --git a/doc/src/users-guide/ch-power.rst b/doc/src/users-guide/ch-power.rst index a518e49748b..4b203932e32 100644 --- a/doc/src/users-guide/ch-power.rst +++ b/doc/src/users-guide/ch-power.rst @@ -10,12 +10,12 @@ Overview Modeling power consumption becomes more and more important with the increasing number of embedded devices and the upcoming Internet of -Things. Mobile personal medical devices, large scale wireless +Things. Mobile personal medical devices, large-scale wireless environment monitoring devices, electric vehicles, solar panels, -low-power wireless sensors, etc. require paying special attention to +low-power wireless sensors, etc., require paying special attention to power consumption. High-fidelity simulation of power consumption allows designing power-sensitive routing protocols, MAC protocols with -power management features, etc., which in turn results in more energy efficient +power management features, etc., which in turn results in more energy-efficient devices. In order to help the modeling process, the INET power model is separated @@ -35,7 +35,7 @@ The power model elements fall into two categories, abbreviated with - ``Ep`` models are simpler, and deal with energy and power quantities. -- ``Cc`` models are more realistic, and deal with charge, current, +- ``Cc`` models are more realistic and deal with charge, current, and voltage quantities. The following sections provide a brief overview of the power model. @@ -53,13 +53,13 @@ a packet, and a display consumes energy when it is turned on. In INET, an energy consumer model is an OMNeT++ simple module that implements the energy consumption of software processes or hardware devices over time. Its main purpose is to provide the power or current -consumption for the current simulation time. Most often energy consumers +consumption for the current simulation time. Most often, energy consumers are included as submodules in the compound module of the hardware devices or software components. INET provides only a few built-in energy consumer models: -- :ned:`AlternatingEpEnergyGenerator` is a trivial energy/power based +- :ned:`AlternatingEpEnergyGenerator` is a trivial energy/power-based statistical energy consumer model example. - :ned:`StateBasedEpEnergyConsumer` is a transceiver energy consumer @@ -85,17 +85,17 @@ Energy Generator Models Energy generator models describe the energy generation of devices over time. A solar panel, for example, produces energy based on time, the -panel’s location on the globe, its orientation towards the sun and the +panel’s location on the globe, its orientation towards the sun, and the actual weather conditions. Energy generators connect to an energy storage that absorbs the generated energy. In INET, an energy generator model is an OMNeT++ simple module implementing the energy generation of a hardware device using a physical -phenomena over time. Its main purpose is to provide the power or current -generation for the current simulation time. Most often energy generation +phenomenon over time. Its main purpose is to provide the power or current +generation for the current simulation time. Most often, energy generation models are included as submodules in network nodes. -INET provides only one trivial energy/power based statistical energy +INET provides only one trivial energy/power-based statistical energy generator model called :ned:`AlternatingEpEnergyGenerator`. The following example shows how to configure its power generation parameters: @@ -113,11 +113,11 @@ parameters: Energy Storage Models --------------------- -Electronic devices which are not connected to external power source must +Electronic devices which are not connected to an external power source must contain some component to store energy. For example, an electrochemical battery in a mobile phone provides energy for its display, its CPU, and its communication devices. It might also absorb energy produced by a -solar installed on its display, or by a portable charger plugged into +solar panel installed on its display or by a portable charger plugged into the wall socket. In INET, an energy storage model is an OMNeT++ simple module which @@ -125,7 +125,7 @@ models the physical phenomena that is used to store energy produced by generators and provide energy for consumers. Its main purpose is to compute the amount of available energy or charge at the current simulation time. It maintains a set of connected energy consumers and -energy generators, their respective total power consumption and total +energy generators, their respective total power consumption, and total power generation. INET contains a few built-in energy storage models: @@ -137,7 +137,7 @@ INET contains a few built-in energy storage models: difference between the total consumed power and the total generated power over time. -- :ned:`SimpleCcBattery` is a more realistic charge/current based +- :ned:`SimpleCcBattery` is a more realistic charge/current-based battery model using a charge independent ideal voltage source and internal resistance. diff --git a/doc/src/users-guide/ch-ppp.rst b/doc/src/users-guide/ch-ppp.rst index a439c573403..ff6f541d1b2 100644 --- a/doc/src/users-guide/ch-ppp.rst +++ b/doc/src/users-guide/ch-ppp.rst @@ -32,9 +32,9 @@ connection (LCP) and for configuring different network-layer protocols The INET implementation only covers encapsulation and decapsulation of data into PPP frames. Control protocols, which do not have a significant -effect on the links’ capacity and latency during normal link operation, +effect on the link's capacity and latency during normal link operation, are not simulated. In addition, header field compressions (PFC and ACFC) -are also bot supported, so a simulated PPP frame always contains 1-byte +are also not supported, so a simulated PPP frame always contains 1-byte Address and Control fields and a 2-byte Protocol field. .. _ug:sec:ppp:the-ppp-module: @@ -43,7 +43,7 @@ The PPP module -------------- The PPP module receives packets from the upper layer in the -:gate:`netwIn` gate, adds a :msg:`PppHeader`, and send +:gate:`netwIn` gate, adds a :msg:`PppHeader`, and sends it to the physical layer through the :gate:`phys` gate. The packet with :msg:`PppHeader` is received from the :gate:`phys` and sent to the upper layer immediately through the :gate:`netwOut` gate. @@ -63,8 +63,8 @@ this is exceeded, the simulation stops with an error. The module can be used in simulations where the nodes are connected and disconnected dynamically. If the channel between the PPP modules is down, the messages received from the upper layer are dropped (including -the messages waiting in the queue). When the connection is restored it -will poll the queue and transmits the messages again. +the messages waiting in the queue). When the connection is restored, it +will poll the queue and transmit the messages again. The PPP module registers itself in the interface table of the node. The :var:`mtu` of the entry can be specified by the :par:`mtu` module @@ -85,11 +85,11 @@ submodule. It can be set to ``PacketQueue`` or to a module type implementing the :ned:`IPacketQueue` interface. There are implementations with QoS and RED support. -In typical use of the :ned:`Ppp` module it is augmented with other nodes +In typical use of the :ned:`Ppp` module, it is augmented with other nodes that monitor the traffic or simulate package loss and duplication. The -:ned:`PppInterface` module abstract that usage by adding :ned:`IHook` +:ned:`PppInterface` module abstracts that usage by adding :ned:`IHook` components to the network input and output of the :ned:`Ppp` component. -Any number of hook can be added by specifying the :par:`numOutputHooks` +Any number of hooks can be added by specifying the :par:`numOutputHooks` and :par:`numInputHooks` parameters and the types of the :var:`outputHook` and :var:`inputHook` components. The hooks are chained -in their numeric order. +in their numeric order. \ No newline at end of file diff --git a/doc/src/users-guide/ch-queueing.rst b/doc/src/users-guide/ch-queueing.rst index 3311b3bed06..6dda25e486d 100644 --- a/doc/src/users-guide/ch-queueing.rst +++ b/doc/src/users-guide/ch-queueing.rst @@ -20,9 +20,9 @@ implementations, and so on. Usage ~~~~~ -The queueing modules can be used in two very different ways. For one, they can +The queueing modules can be used in two very different ways. Firstly, they can be connected to other INET modules using gates. In this case, the modules send -and receive packets asynchronously as many other INET modules do. For example, +and receive packets asynchronously, as many other INET modules do. For example, application packet source and packet sink modules are used this way. The other way to use them is to directly call their C++ methods through one of the C++ interfaces of the contract package. In this case, the queueing modules are not @@ -33,7 +33,7 @@ Model ~~~~~ Most queueing model elements provide simple behaviors, so they are implemented -as simple modules. But queueing elements can also be composed to form more +as simple modules. However, queueing elements can also be composed to form more complex behaviors. For example, priority queues, request-response based traffic generators, traffic shapers are usually implemented as compound modules. In fact, some of the queueing model elements provided by INET are actually realized as @@ -48,7 +48,7 @@ Operation ~~~~~~~~~ Internally, connected queueing model elements most often communicate with each -other using synchronous C++ method calls without utilizing :cpp:`handleMessage()`. +other using synchronous C++ method calls, without utilizing :cpp:`handleMessage()`. The only exception is when an operation takes a non-zero simulation time, such as when the processing of a packet is delayed. The connections between the model elements are simply used to designate the caller and the callee. Other modules @@ -64,7 +64,7 @@ former case, when a packet is pushed, the activity is initiated by the source of the packet. In contrast, when a packet is pulled, the activity is initiated by the sink of the packet. In both cases, the passive elements can be asked via separate methods to tell if they can be pushed or pulled on a specific gate -in their current state either with respect to a specific packet or any packet +in their current state, either with respect to a specific packet or any packet thereof. Queueing model elements can be divided into two categories with respect to the @@ -85,19 +85,19 @@ The mechanism that allows passive modules to prevent a push or pull operation of an active module is called backpressure. For example, a queue that is full, and which doesn't have a configured packet dropping mechanism generates backpressure towards the connected active packet source. This backpressure prevents the source -from pushing more packets into the queue. Similarly an empty queue generates +from pushing more packets into the queue. Similarly, an empty queue generates backpressure towards the connected active server component. The backpressure prevents the server from pulling more packets from the queue. In general, -backpressure can be generated by modules on their own any time they want, it -can be transferred from one gate to another, or it can be simply absorbed by a +backpressure can be generated by modules on their own at any time they want; it +can be transferred from one gate to another; or it can be simply absorbed by a module. For example, a scheduler transfers the backpressure from its input gates -towards its output gate, and similarly a classifier transfers backpressure from +towards its output gate, and similarly, a classifier transfers backpressure from its output gates towards its input gate. Finally, modules can choose if they consider or ignore the backpressure from the connected modules. In the latter case, the push and pull operations may cause a runtime error. Pushing a packet into a gate (and similarly pulling a packet from a gate) can -have far reaching consequences by triggering a chain of operations potentially +have far-reaching consequences by triggering a chain of operations potentially by passing through multiple connected elements. For example, pushing a packet into a classifier will immediately push the packet into one of the connected queueing elements, and will also potentially lead to additional operations on @@ -117,8 +117,8 @@ These modules act as sources of packets. An active packet source pushes packets to its output. A passive packet source returns a packet when it is pulled by other queueing model elements. -- :ned:`ActivePacketSource`: generic source that produces packets periodically -- :ned:`PassivePacketSource`: generic source that provides packets as requested +- :ned:`ActivePacketSource`: a generic source that produces packets periodically +- :ned:`PassivePacketSource`: a generic source that provides packets as requested - :ned:`BurstyPacketProducer`: mixes two different sources to generate bursty traffic - :ned:`QueueFiller`: produces packets to continuously fill a queue - :ned:`ResponseProducer`: produces complex response traffic based on the incoming request type @@ -132,8 +132,8 @@ These modules act as sinks of packets. An active packet sink pulls packets from its input. A passive packet sink is pushed with packets by other queueing model elements. -- :ned:`ActivePacketSink`: generic sink that collects packets periodically -- :ned:`PassivePacketSink`: generic sink that consumes packets as they arrive +- :ned:`ActivePacketSink`: a generic sink that collects packets periodically +- :ned:`PassivePacketSink`: a generic sink that consumes packets as they arrive - :ned:`RequestConsumer`: processes incoming requests in order and initiates response traffic - :ned:`PcapFilePacketConsumer`: writes packets to a PCAP file - :ned:`FullPacketSink`: doesn't pull packets and doesn't allow packets to be pushed @@ -151,7 +151,7 @@ The following simpler equation about the number of packets always holds true for #pushed - #pulled - #dropped - #removed = #queueLength = #available -- :ned:`PacketQueue`: generic queue that provides ordering and selective dropping +- :ned:`PacketQueue`: a generic queue that provides ordering and selective dropping parameterizable with an :cpp:`IPacketComparatorFunction` and an :cpp:`IPacketDropperFunction` @@ -168,7 +168,7 @@ These modules deal with memory allocation of packets without considering the ordering among them. A packet buffer generally doesn't have gates, and packets are not pushed into or pulled from it. -- :ned:`PacketBuffer`: generic buffer that provides shared storage between several queues +- :ned:`PacketBuffer`: a generic buffer that provides shared storage between several queues parameterizable with an :cpp:`IPacketDropperFunction` @@ -177,13 +177,13 @@ are not pushed into or pulled from it. Filters ------- -These modules filter for specific packets while dropping the rest. When a packet +These modules filter specific packets while dropping the rest. When a packet is pushed into the input of a packet filter, then the filter either pushes the packet to its output or it simply drops the packet. In contrast, when a packet is pulled from the output of a packet filter, then it continuously pulls and drops packets from its input until it finds one that matches the filter criteria. -- :ned:`PacketFilter`: generic packet filter +- :ned:`PacketFilter`: a generic packet filter parameterizable with an :cpp:`IPacketFilterFunction` @@ -199,7 +199,7 @@ These modules classify packets to one of their outputs. When a packet is pushed into the input of a packet classifier, then it immediately pushes the packet to one of its outputs. -- :ned:`PacketClassifier`: generic packet classifier +- :ned:`PacketClassifier`: a generic packet classifier parameterizable with an :cpp:`IPacketClassifierFunction` @@ -217,7 +217,7 @@ These modules schedule packets from one of their inputs. When a packet is pulled from the output of a packet scheduler, then it immediately pulls a packet from one of its inputs and returns that packet. -- :ned:`PacketScheduler`: generic packet scheduler +- :ned:`PacketScheduler`: a generic packet scheduler parameterizable with an :cpp:`IPacketSchedulerFunction` @@ -243,7 +243,7 @@ Markers These modules attach some information to packets on an individual basis. Packets can be both pushed into the input and pulled from the output of packet markers. -- :ned:`PacketLabeler`: generic marker which attaches labels to matching packets +- :ned:`PacketLabeler`: a generic marker that attaches labels to matching packets parameterizable with an :cpp:`IPacketFilterFunction` @@ -267,7 +267,7 @@ Token generators ---------------- These modules generate tokens for other modules. A token generator generally -doesn't have gates and packets are not pushed into or pulled from it. +doesn't have gates, and packets are not pushed into or pulled from it. - :ned:`TimeBasedTokenGenerator`: generates tokens based on elapsed simulation time - :ned:`PacketBasedTokenGenerator`: generates tokens based on received packets @@ -279,11 +279,11 @@ Conditioners These modules actively shape traffic by changing the order of packets, dropping packets, delaying packets, etc. Note that the capabilities of conditioners also -includes delaying, which queues are not capable of. Traffic conditioners are +include delaying, which queues are not capable of. Traffic conditioners are generally built by composition using other queueing model elements. -- :ned:`LeakyBucket`: generic shaper with overflow and configurable output rate -- :ned:`TokenBucket`: generic shaper with overflow and configurable burstiness and output rate +- :ned:`LeakyBucket`: a generic shaper with overflow and configurable output rate +- :ned:`TokenBucket`: a generic shaper with overflow and configurable burstiness and output rate Other queueing elements ----------------------- @@ -298,4 +298,4 @@ into any of the above categories. - :ned:`PacketCloner`: sends one copy of each received packet to all outputs - :ned:`PacketHistory`: keeps track of the last N packets which can be inspected in Qtenv - :ned:`PacketDuplicator`: sends copies of each received packet to the only output -- :ned:`OrdinalBasedDuplicator`: duplicates received packets based on their ordinal number +- :ned:`OrdinalBasedDuplicator`: duplicates received packets based on their ordinal number \ No newline at end of file diff --git a/doc/src/users-guide/ch-routing.rst b/doc/src/users-guide/ch-routing.rst index 024adb58b7a..9d6898ec25a 100644 --- a/doc/src/users-guide/ch-routing.rst +++ b/doc/src/users-guide/ch-routing.rst @@ -8,13 +8,13 @@ Internet Routing Overview -------- -INET Framework has models for several internet routing protocols, -including RIP, OSPF and BGP. +The INET Framework has models for several internet routing protocols, +including RIP, OSPF, and BGP. The easiest way to add routing to a network is to use the :ned:`Router` NED type for routers. :ned:`Router` contains a conditional instance for each of the above protocols. These submodules can be enabled by setting -the :par:`hasRip`, :par:`hasOspf` and/or :par:`hasBgp` parameters to +the :par:`hasRip`, :par:`hasOspf`, and/or :par:`hasBgp` parameters to ``true``. Example: @@ -24,7 +24,7 @@ Example: **.hasRip = true There are also NED types called :ned:`RipRouter`, :ned:`OspfRouter`, -:ned:`BgpRouter`, which are all :ned:`Router`’s with appropriate routing +:ned:`BgpRouter`, which are all :ned:`Router`’s with an appropriate routing protocol enabled. .. _ug:sec:routing:rip: @@ -33,17 +33,17 @@ RIP --- RIP (Routing Information Protocol) is a distance-vector routing protocol -which employs the hop count as a routing metric. RIP prevents routing +that employs the hop count as a routing metric. RIP prevents routing loops by implementing a limit on the number of hops allowed in a path -from source to destination. RIP uses the *split horizon with poison -reverse* technique to work around the “count-to-infinity” problem. +from the source to the destination. RIP uses the *split horizon with poison +reverse* technique to work around the "count-to-infinity" problem. The :ned:`Rip` module implements distance vector routing as specified in RFC 2453 (RIPv2) and RFC 2080 (RIPng). The behavior can be selected by -setting the :par:`mode` parameter to either ``"RIPv2"`` or -``"RIPng"``. Protocol configuration such as link metrics and +setting the :par:`mode` parameter to either `RIPv2`` or +``RIPng``. Protocol configuration such as link metrics and per-interface operation mode (such as whether RIP is enabled on the -interface, and whether to use split horizon) can be specified in XML +interface and whether to use split horizon) can be specified in XML using the :par:`ripConfig` parameter. The following example configures a :ned:`Router` module to use RIPv2: @@ -54,7 +54,7 @@ The following example configures a :ned:`Router` module to use RIPv2: **.mode = "RIPv2" **.ripConfig = xmldoc("RIPConfig.xml") -The configuration file specifies the per interface parameters. Each +The configuration file specifies the per-interface parameters. Each ```` element configures one or more interfaces; the ``hosts``, ``names``, ``towards``, ``among`` attributes select the configured interfaces (in a similar way as with @@ -63,8 +63,8 @@ for further information. Additional attributes: -- ``metric``: metric assigned to the link, default value is 1. This - value is added to the metric of a learned route, received on this +- ``metric``: metric assigned to the link, the default value is 1. This + value is added to the metric of a learned route received on this interface. It must be an integer in the [1,15] interval. - ``mode``: mode of the interface. @@ -77,10 +77,10 @@ The mode attribute can be one of the following: - ``NoSplitHorizon``: no split horizon filtering; send all routes to neighbors. -- ``SplitHorizon``: do not sent routes whose next hop is the +- ``SplitHorizon``: do not send routes whose next hop is the neighbor. -- ``SplitHorizonPoisenedReverse`` (default): if the next hop is +- ``SplitHorizonPoisonedReverse`` (default): if the next hop is the neighbor, then set the metric of the route to infinity. The following example sets the link metric between router ``R1`` and @@ -119,11 +119,11 @@ the :ned:`Ospfv2` module. The ```` root element may contain ```` and ```` elements with various attributes specifying the -parameters for the network interfaces. Most importantly ```` +parameters for the network interfaces. Most importantly, ```` contains ```` elements enumerating the network -addresses that should be advertized by the protocol. Also +addresses that should be advertised by the protocol. Also, ```` elements may contain data for configuring various -pont-to-point or broadcast interfaces. +point-to-point or broadcast interfaces. .. code-block:: xml @@ -167,13 +167,13 @@ parameter. **.bgpConfig = xmldoc("BGPConfig.xml") -The configuration file may contain ````, ```` and +The configuration file may contain ````, ````, and ``Session`` elements at the top level. - ````: allows specifying various timing parameters for the routers. -- ````: defines Autonomous Systems, routers and rules to be +- ````: defines Autonomous Systems, routers, and rules to be applied. - ````: specifies open sessions between edge routers. It @@ -226,12 +226,12 @@ The configuration file may contain ````, ```` and -Inside ```` elements various rules can be sepecified: +Inside ```` elements, various rules can be specified: - DenyRoute: deny route in IN and OUT traffic (``Address`` and ``Netmask`` attributes must be specified.) -- DenyRouteIN : deny route in IN traffic (``Address`` and +- DenyRouteIN: deny route in IN traffic (``Address`` and ``Netmask`` attributes must be specified.) - DenyRouteOUT: deny route in OUT traffic (``Address`` and @@ -240,8 +240,9 @@ Inside ```` elements various rules can be sepecified: - DenyAS: deny routes learned by AS in IN and OUT traffic (AS id must be specified as the body of the element.) -- DenyASIN : deny routes learned by AS in IN traffic (AS id must be +- DenyASIN: deny routes learned by AS in IN traffic (AS id must be specified as the body of the element.) - DenyASOUT: deny routes learned by AS in OUT traffic (AS id must be specified as the body of the element.) + diff --git a/doc/src/users-guide/ch-scenario-scripting.rst b/doc/src/users-guide/ch-scenario-scripting.rst index f1be9c765ea..d9e1b705227 100644 --- a/doc/src/users-guide/ch-scenario-scripting.rst +++ b/doc/src/users-guide/ch-scenario-scripting.rst @@ -33,7 +33,7 @@ INET supports the following built-in actions: ScenarioManager --------------- -The :ned:`ScenarioManager` module type is for setting up and controlling +The :ned:`ScenarioManager` module type is used for setting up and controlling simulation experiments. In typical usage, it has only one instance in the network: @@ -51,8 +51,6 @@ carried out by other simple modules. An example script: - - .. code-block:: xml @@ -89,7 +87,7 @@ commands to be carried out at the same simulation time using More information can be found in the :ned:`ScenarioManager` documentation. -The script is usually placed in a separate file, and specified like +The script is usually placed in a separate file and specified like this: .. code-block:: ini diff --git a/doc/src/users-guide/ch-sensor-macs.rst b/doc/src/users-guide/ch-sensor-macs.rst index d52d0f3908d..a38b88bdb2c 100644 --- a/doc/src/users-guide/ch-sensor-macs.rst +++ b/doc/src/users-guide/ch-sensor-macs.rst @@ -9,18 +9,16 @@ Overview -------- The INET Framework contains the implementation of several MAC protocols -for wireless sensor networks (WSNs), including B-MAC, L-MAC and X-MAC. +for wireless sensor networks (WSNs), including B-MAC, L-MAC, and X-MAC. To create a wireless node with a specific MAC protocol, use a node type -that has a wireless interface, and set the interface type to the +that has a wireless interface and set the interface type to the appropriate type. For example, :ned:`WirelessHost` is a node type which is preconfigured to have one wireless interface, ``wlan[0]``. ``wlan[0]`` is of parametric type, so if you build the network from -:ned:`WirelessHost` nodes, you can configure all of them to use e.g. +:ned:`WirelessHost` nodes, you can configure all of them to use, for example, B-MAC with the following line in the ini file: - - .. code-block:: ini **.wlan[0].typename = "BMacInterface" @@ -32,12 +30,11 @@ B-MAC B-MAC (Berkeley MAC) is a carrier sense media access protocol for wireless sensor networks that provides a flexible interface to obtain -ultra low power operation, effective collision avoidance, and high -channel utilization. To achieve low power operation, B-MAC employs an +ultra-low power operation, effective collision avoidance, and high +channel utilization. To achieve low-power operation, B-MAC employs an adaptive preamble sampling scheme to reduce duty cycle and minimize idle -listening. B-MAC is designed for low traffic, low power communication, -and is one of the most widely used protocols (e.g. it is part of -TinyOS). +listening. B-MAC is designed for low-traffic, low-power communication and is +one of the most widely used protocols (e.g., it is part of TinyOS). The :ned:`BMac` module type implements the B-MAC protocol. @@ -49,7 +46,7 @@ to :ned:`BMac`. L-MAC ----- -L-MAC (Lightweight MAC) is an energy-efficient medium acces protocol +L-MAC (Lightweight MAC) is an energy-efficient medium access protocol designed for wireless sensor networks. Although the protocol uses TDMA to give nodes in the WSN the opportunity to communicate collision-free, the network is self-organizing in terms of time slot assignment and @@ -57,8 +54,8 @@ synchronization. The protocol reduces the number of transceiver state switches and hence the energy wasted in preamble transmissions. The :ned:`LMac` module type implements the L-MAC protocol, based on the -paper “A lightweight medium access protocol (LMAC) for wireless sensor -networks” by van Hoesel and P. Havinga. +paper "A lightweight medium access protocol (LMAC) for wireless sensor +networks" by van Hoesel and P. Havinga. :ned:`LMacInterface` is a :ned:`WirelessInterface` with the MAC type set to :ned:`LMac`. @@ -69,16 +66,16 @@ X-MAC ----- X-MAC is a low-power MAC protocol for wireless sensor networks (WSNs). -In contrast to B-MAC which employs an extended preamble and preamble +In contrast to B-MAC, which employs an extended preamble and preamble sampling, X-MAC uses a shortened preamble that reduces latency at each hop and improves energy consumption while retaining the advantages of -low power listening, namely low power communication, simplicity and a +low-power listening, namely low-power communication, simplicity, and a decoupling of transmitter and receiver sleep schedules. The :ned:`XMac` module type implements the X-MAC protocol, based on the -paper “X-MAC: A Short Preamble MAC Protocol for Duty-Cycled Wireless -Sensor Networks” by Michael Buettner, Gary V. Yee, Eric Anderson and +paper "X-MAC: A Short Preamble MAC Protocol for Duty-Cycled Wireless +Sensor Networks" by Michael Buettner, Gary V. Yee, Eric Anderson, and Richard Han. :ned:`XMacInterface` is a :ned:`WirelessInterface` with the MAC type set -to :ned:`XMac`. +to :ned:`XMac`. \ No newline at end of file diff --git a/doc/src/users-guide/ch-transmission-medium.rst b/doc/src/users-guide/ch-transmission-medium.rst index 12179c0d36e..baee781a3d0 100644 --- a/doc/src/users-guide/ch-transmission-medium.rst +++ b/doc/src/users-guide/ch-transmission-medium.rst @@ -15,15 +15,15 @@ transmissions, background noise, and other ongoing noises. It relies on several models: -#. signal propagation model +#. Signal propagation model -#. path loss model +#. Path loss model -#. obstacle loss model +#. Obstacle loss model -#. background noise model +#. Background noise model -#. medium analog model +#. Medium analog model With the help of the above models, the medium module computes when, where, and how signals arrive at receivers, including the set of @@ -37,18 +37,14 @@ RadioMedium ----------- The standard transmission medium model in INET is :ned:`RadioMedium`. -:ned:`RadioMedium` is as an OMNeT++ compound module with several -replaceable submodules. It contains submodules for each of the above -models (signal propagation, path loss, etc.), and various caches for -efficiency. - -Note that :ned:`RadioMedium` is an active compound module, that is, it -has an associated C++ class that encapsulates the computations. - -:ned:`RadioMedium` contains its components as submodules with parametric -types: +:ned:`RadioMedium` is an OMNeT++ compound module with several replaceable +submodules. It contains submodules for each of the above models (signal +propagation, path loss, etc.), and various caches for efficiency. +Note that :ned:`RadioMedium` is an active compound module, that is, it has an +associated C++ class that encapsulates the computations. +:ned:`RadioMedium` contains its components as submodules with parametric types: .. code-block:: ned @@ -68,14 +64,11 @@ There are many preconfigured versions of :ned:`RadioMedium`: - For use with :ned:`GenericUnitDiskRadio`: :ned:`UnitDiskRadioMedium` -- For APSK radios: :ned:`ScalarRadioMedium`, - :ned:`DimensionalRadioMedium` +- For APSK radios: :ned:`ScalarRadioMedium`, :ned:`DimensionalRadioMedium` -- For IEEE 802.11: :ned:`Ieee80211ScalarRadioMedium`, - :ned:`Ieee80211DimensionalRadioMedium`. +- For IEEE 802.11: :ned:`Ieee80211ScalarRadioMedium`, :ned:`Ieee80211DimensionalRadioMedium`. -- For IEEE 802.15.4: :ned:`Ieee802154UwbIrRadioMedium`, - :ned:`Ieee802154NarrowbandScalarRadioMedium` +- For IEEE 802.15.4: :ned:`Ieee802154UwbIrRadioMedium`, :ned:`Ieee802154NarrowbandScalarRadioMedium` The following sections describe the parts of the medium model. @@ -84,84 +77,71 @@ The following sections describe the parts of the medium model. Propagation Models ------------------ -When a transmitter starts to transmit a signal, the beginning of the -signal propagates through the transmission medium. When the transmitter -ends the transmission, the signal’s end propagates similarly. The -propagation model describes how a signal moves through space over time. -Its main purpose is to compute the arrival space-time coordinates at -receivers. There are two built-in models in INET, implemented as simple -modules: +When a transmitter starts to transmit a signal, the beginning of the signal +propagates through the transmission medium. When the transmitter ends the +transmission, the signal’s end propagates similarly. The propagation model +describes how a signal moves through space over time. Its main purpose is to +compute the arrival space-time coordinates at receivers. There are two built-in +models in INET, implemented as simple modules: -- :ned:`ConstantTimePropagation` is a simplistic model where the - propagation time is independent of the traveled distance. The - propagation time is simply determined by a module parameter. +- :ned:`ConstantTimePropagation` is a simplistic model where the propagation + time is independent of the travelled distance. The propagation time is simply + determined by a module parameter. - :ned:`ConstantSpeedPropagation` is a more realistic model where the - propagation time is proportional to the traveled distance. The - propagation time is independent of the transmitter and receiver - movement during both signal transmission and propagation. The - propagation speed is determined by a module parameter. + propagation time is proportional to the travelled distance. The propagation + time is independent of the transmitter and receiver movement during both + signal transmission and propagation. The propagation speed is determined by a + module parameter. The default propagation model is configured as follows: - - .. literalinclude:: lib/Snippets.ini :language: ini :start-after: !PropagationModelConfigurationExample :end-before: !End :name: Propagation model configuration example -A more accurate model could take into consideration the transmitter and -receiver movement. This effect becomes especially important for acoustic -communication, because the propagation speed of the signal is much more -comparable to the speed of the transceivers. +A more accurate model could take into consideration the transmitter and receiver +movement. This effect becomes especially important for acoustic communication, +because the propagation speed of the signal is much more comparable to the speed +of the transceivers. .. _ug:sec:medium:path-loss-models: Path Loss Models ---------------- -As a signal propagates through space its power density decreases. This -is called path loss and it is the combination of many effects such as -free-space loss, refraction, diffraction, reflection, and absorption. -There are several different path loss models in the literature, which -differ in their parameterization and application area. +As a signal propagates through space, its power density decreases. This is +called path loss and it is the combination of many effects such as free-space +loss, refraction, diffraction, reflection, and absorption. There are several +different path loss models in the literature, which differ in their +parameterization and application area. -In INET, a path loss model is an OMNeT++ simple module implementing a -specific path loss algorithm. Its main purpose is to compute the power -loss for a given signal, but it is also capable of estimating the range -for a given loss. The latter is useful, for example, to allow -visualizing communication range. INET contains a number of built-in path -loss algorithms, each comes with its own set of parameters: +In INET, a path loss model is an OMNeT++ simple module implementing a specific +path loss algorithm. Its main purpose is to compute the power loss for a given +signal, but it is also capable of estimating the range for a given loss. The +latter is useful, for example, to allow visualizing communication range. INET +contains a number of built-in path loss algorithms, each comes with its own set +of parameters: -- :ned:`FreeSpacePathLoss` models line of sight path loss for air or - vacuum. +- :ned:`FreeSpacePathLoss` models line of sight path loss for air or vacuum. -- :ned:`BreakpointPathLoss` refines it using dual slope model with two - separate path loss exponents. +- :ned:`BreakpointPathLoss` refines it using dual slope model with two separate path loss exponents. -- :ned:`LogNormalShadowing` models path loss for a wide range of - environments (e.g. urban areas, and buildings) +- :ned:`LogNormalShadowing` models path loss for a wide range of environments (e.g., urban areas, and buildings) -- :ned:`TwoRayGroundReflection` models interference between line of - sight and single ground reflection. +- :ned:`TwoRayGroundReflection` models interference between line of sight and single ground reflection. -- :ned:`TwoRayInterference` refines the above for inter-vehicle - communication. +- :ned:`TwoRayInterference` refines the above for inter-vehicle communication. -- :ned:`RicianFading` is a stochastical model for the anomaly caused by - partial cancellation of a signal by itself. +- :ned:`RicianFading` is a stochastic model for the anomaly caused by partial cancellation of a signal by itself. -- :ned:`RayleighFading` is a stochastical model for heavily built-up - urban environments when there is no dominant propagation along the - line of sight. +- :ned:`RayleighFading` is a stochastic model for heavily built-up urban environments when there is no dominant propagation along the line of sight. -- :ned:`NakagamiFading` further refines the above two models for - cellular systems. +- :ned:`NakagamiFading` further refines the above two models for cellular systems. -The following example replaces the default free-space path loss model -with log normal shadowing: +The following example replaces the default free-space path loss model with log normal shadowing: @@ -176,30 +156,28 @@ with log normal shadowing: Obstacle Loss Models -------------------- -When the signal propagates through space it also passes through physical -objects present in that space. As the signal penetrates physical -objects, its power decreases when it reflects from surfaces, and also -when it is absorbed by their material. There are various ways to model -this effect, which differ in the trade-off between accuracy and -performance. +When the signal propagates through space, it also passes through physical +objects present in that space. As the signal penetrates physical objects, its +power decreases when it reflects from surfaces, and also when it is absorbed by +their material. There are various ways to model this effect, which differ in the +trade-off between accuracy and performance. -In INET, an obstacle loss model is an OMNeT++ simple module. Its main -purpose is to compute the power loss based on the traveled path and the -signal frequency. The obstacle loss models most often use the physical -environment model to determine the set of penetrated physical objects. -INET contains a few built-in obstacle loss models: +In INET, an obstacle loss model is an OMNeT++ simple module. Its main purpose is +to compute the power loss based on the traveled path and the signal frequency. +The obstacle loss models most often use the physical environment model to +determine the set of penetrated physical objects. INET contains a few built-in +obstacle loss models: -- :ned:`IdealObstacleLoss` model determines total or no power loss at - all by checking if there is any obstructing physical object along the - straight propagation path. +- :ned:`IdealObstacleLoss` model determines total or no power loss at all by + checking if there is any obstructing physical object along the straight + propagation path. -- :ned:`DielectricObstacleLoss` computes the power loss based on the - accurate dielectric and reflection loss along the straight path - considering the shape, position, orientation, and material of - obstructing physical objects. +- :ned:`DielectricObstacleLoss` computes the power loss based on the accurate + dielectric and reflection loss along the straight path considering the shape, + position, orientation, and material of obstructing physical objects. -By default, the medium module doesn’t contain any obstacle loss model, -but configuring one is very simple: +By default, the medium module doesn’t contain any obstacle loss model, but +configuring one is very simple: @@ -209,32 +187,27 @@ but configuring one is very simple: :end-before: !End :name: Obstacle loss model configuration example -Statistical obstacle loss models are also possible but currently not -provided. +Statistical obstacle loss models are also possible but currently not provided. .. _ug:sec:medium:background-noise-models: Background Noise Models ----------------------- -Thermal noise, cosmic background noise, and other random fluctuations of -the electromagnetic field affect the quality of the communication -channel. This kind of noise doesn’t come from a particular source, so it -doesn’t make sense to model its propagation through space. The -background noise model describes instead how it changes over space and -time. +Thermal noise, cosmic background noise, and other random fluctuations of the +electromagnetic field affect the quality of the communication channel. This kind +of noise doesn’t come from a particular source, so it doesn’t make sense to +model its propagation through space. The background noise model describes +instead how it changes over space and time. -In INET, a background noise model is an OMNeT++ simple module. Its main -purpose is to compute the analog representation of the background noise -for a given space-time interval. For example, -:ned:`IsotropicScalarBackgroundNoise` computes a background noise that -is independent of space-time coordinates, and its scalar power is -determined by a module parameter. +In INET, a background noise model is an OMNeT++ simple module. Its main purpose +is to compute the analog representation of the background noise for a given +space-time interval. For example, :ned:`IsotropicScalarBackgroundNoise` computes +a background noise that is independent of space-time coordinates, and its scalar +power is determined by a module parameter. The simplest background noise model can be configured as follows: - - .. literalinclude:: lib/Snippets.ini :language: ini :start-after: !BackgroundNoiseModelConfigurationExample @@ -246,24 +219,20 @@ The simplest background noise model can be configured as follows: Medium Analog Models -------------------- -The analog signal is a complex physical phenomenon which can be modeled -in many different ways. Choosing the right analog domain signal -representation is the most important factor in the trade-off between -accuracy and performance. The analog model of the transmission medium -determines how signals are represented while being transmitted, -propagated, and received. +The analog signal is a complex physical phenomenon that can be modeled in many +different ways. Choosing the right analog domain signal representation is the +most important factor in the trade-off between accuracy and performance. The +analog model of the transmission medium determines how signals are represented +while being transmitted, propagated, and received. -In INET, a medium analog model is an OMNeT++ simple module. Its main purpose -is to compute the received signal from the transmitted signal. The -analog model combines the effect of the antenna, path loss, and obstacle -loss models. Transceivers must be configured transmit and receive -signals according to the representation used by the analog model. +In INET, a medium analog model is an OMNeT++ simple module. Its main purpose is +to compute the received signal from the transmitted signal. The analog model +combines the effect of the antenna, path loss, and obstacle loss models. +Transceivers must be configured to transmit and receive signals according to the +representation used by the analog model. The most commonly used medium analog model, which uses a scalar signal power -representation over a frequency and time interval, can be configured as -follows: - - +representation over a frequency and time interval, can be configured as follows: .. literalinclude:: lib/Snippets.ini :language: ini @@ -276,33 +245,28 @@ follows: Neighbor Cache -------------- -Transceivers are considered neighbors if successful communication is -possible between them. For wired communication it is easy to determine -which transceivers are neighbors, because they are connected by wires. -In contrast, in wireless communication determining which transceivers -are neighbors isn’t obvious at all. +Transceivers are considered neighbors if successful communication is possible +between them. For wired communication, it is easy to determine which +transceivers are neighbors because they are connected by wires. In contrast, in +wireless communication, determining which transceivers are neighbors isn’t +obvious at all. -In INET, a neighbor cache is an OMNeT++ simple module which provides an -efficient way of keeping track of the neighbor relationship between -transceivers. Its main purpose is to compute the set of affected -receivers for a given transmission. All built-in models in INET provide -a conservative approximation only, because they update their state -periodically: +In INET, a neighbor cache is an OMNeT++ simple module that provides an efficient +way of keeping track of the neighbor relationship between transceivers. Its main +purpose is to compute the set of affected receivers for a given transmission. +All built-in models in INET provide a conservative approximation only because +they update their state periodically: -- :ned:`NeighborListNeighborCache` takes a range as parameter, and for - each transceiver it maintains the list of receivers within range - (*neighbor list*). +- :ned:`NeighborListNeighborCache` takes a range as a parameter, and for each + transceiver, it maintains the list of receivers within range (neighbor list). -- :ned:`GridNeighborCache` organizes transceivers in a 3D grid with - constant cell size. +- :ned:`GridNeighborCache` organizes transceivers in a 3D grid with a constant + cell size. - :ned:`QuadTreeNeighborCache` organizes transceivers in a 2D quad tree - (ignoring the Z axis) with constant node size. - -The following example sets :ned:`QuadTreeNeighborCache` as neighbor -cache: - + (ignoring the Z axis) with a constant node size. +The following example sets :ned:`QuadTreeNeighborCache` as the neighbor cache: .. literalinclude:: lib/Snippets.ini :language: ini @@ -310,58 +274,56 @@ cache: :end-before: !End :name: Neighbor cache model configuration example -How should one decide which neighbor cache to choose for a given -simulation? As the sole purpose of the neighbor cache is to speed up the -simulation, one should choose the one that leads to the best performance -for that particular network. Which one performs best is best determined -by experimentation, as it depends on many factors: number of nodes, -their spatial distribution, their speed and movement pattern, their -communication pattern, and so on. Note that not only the choice of -neighbor cache but also its parameterization can affect performance. +How should one decide which neighbor cache to choose for a given simulation? As +the sole purpose of the neighbor cache is to speed up the simulation, one should +choose the one that leads to the best performance for that particular network. +Which one performs the best is best determined by experimentation, as it depends +on many factors: the number of nodes, their spatial distribution, their speed +and movement pattern, their communication pattern, and so on. Note that not only +the choice of the neighbor cache but also its parameterization can affect +performance. .. _ug:sec:medium:medium-limit-cache: Medium Limit Cache ------------------ -The medium limit cache (and its default implementation -:ned:`MediumLimitCache`) keeps track of certain thresholds and -minimum/maximum values of quantities related to layer 1 modeling. Some -of these limits can be gathered from other modules in the network, but -still, all of them can be explicitly specified by the user. The -quantities include: +The medium limit cache (and its default implementation :ned:`MediumLimitCache`) +keeps track of certain thresholds and minimum/maximum values of quantities +related to layer 1 modeling. Some of these limits can be gathered from other +modules in the network, but still, all of them can be explicitly specified by +the user. The quantities include: -- maximum speed (can be gathered from mobility models) +- Maximum speed (can be gathered from mobility models) -- maximum transmission power +- Maximum transmission power -- minimum interference power and reception power +- Minimum interference power and reception power -- maximum antenna gain (can be computed from antenna models) +- Maximum antenna gain (can be computed from antenna models) -- minimum time interval to consider two overlapping signals interfering +- Minimum time interval to consider two overlapping signals interfering -- maximum duration of a transmission +- Maximum duration of a transmission -- maximum communication range and interference range (can be computed - from transmitter and receiver models) +- Maximum communication range and interference range (can be computed from transmitter and receiver models) -These limits allow the transmission medium model to make assumptions -about the locations of nodes (i.e. the maximum distance they can move -during some interval), about the possibility of interference, and about -the possibility of a signal being receivable. +These limits allow the transmission medium model to make assumptions about the +locations of nodes (i.e. the maximum distance they can move during some +interval), about the possibility of interference, and about the possibility of a +signal being receivable. .. _ug:sec:medium:communication-cache: Communication Cache ------------------- -The communication cache is used to cache various intermediate -computation results related to the communication on the medium. The main -motivation to have multiple implementations is that different -implementations may be the most efficient in different simulations. -Also, a conservative (simple but robust) implementation may be used for -validating new (more efficient but also more complex) implementations. +The communication cache is used to cache various intermediate computation +results related to the communication on the medium. The main motivation to have +multiple implementations is that different implementations may be the most +efficient in different simulations. Also, a conservative (simple but robust) +implementation may be used for validating new (more efficient but also more +complex) implementations. Implementations include: @@ -376,44 +338,40 @@ Implementations include: Improving Scalability --------------------- -The simulation of wireless networks is inherently less scalable than -that of wired networks. In wired networks, a transmission only affects -the host’s neighbors on the link, which is usually 1 in modern networks -that are dominated by point-to-point links. The wireless medium, -however, is a broadcast medium. Any transmission is “heard” by all nodes -within interference range, not only the intended recipients. The signal -may be receivable by them (and must be indeed received before the -destination address field in it can be examined), or may interfere with -the reception of other transmissions. Whichever the case, the -transmission must be evaluated or processed by a much larger number of -nodes than in the wired case. This makes the computational complexity at -least :math:`O(n^2)` (:math:`n` being the number of nodes.) Other -effects may further increase the exponent. - -The medium module provides a set of parameters that can be used to -alleviate the scalability issue. These *filter* parameters that can be -used to reduce the amount of processing at nodes that are not the -intended recipients of the frame, increasing simulation performance. +The simulation of wireless networks is inherently less scalable than that of +wired networks. In wired networks, a transmission only affects the host’s +neighbors on the link, which is usually 1 in modern networks that are dominated +by point-to-point links. The wireless medium, however, is a broadcast medium. +Any transmission is “heard” by all nodes within the interference range, not only +the intended recipients. The signal may be receivable by them (and must be +indeed received before the destination address field in it can be examined) or +may interfere with the reception of other transmissions. Whichever the case, the +transmission must be evaluated or processed by a much larger number of nodes +than in the wired case. This makes the computational complexity at least +:math:`O(n^2)` (:math:`n` being the number of nodes.) Other effects may further +increase the exponent. + +The medium module provides a set of parameters that can be used to alleviate the +scalability issue. These *filter* parameters that can be used to reduce the +amount of processing at nodes that are not the intended recipients of the frame, +increasing simulation performance. There are several filters that can be enabled/disabled individually: -- *Range filter*. When this filter is active, the medium module does - not send signals to a radio if it is outside interference range (or - communication range, this option can also be selected.) +- *Range filter*. When this filter is active, the medium module does not send + signals to a radio if it is outside the interference range (or communication + range, this option can also be selected.) -- *Radio mode filter*. When this filter is active, the medium module - does not send signals to a radio if it is neither in *receiver* nor - in *transceiver* mode. +- *Radio mode filter*. When this filter is active, the medium module does not + send signals to a radio if it is neither in *receiver* nor in *transceiver* + mode. -- *Listening filter*. When this filter is active, the medium module - does not send signals to a radio if it listens on the channel in - incompatible mode (e.g. different carrier frequency and bandwidth, or - different modulation) +- *Listening filter*. When this filter is active, the medium module does not + send signals to a radio if it listens on the channel in incompatible mode + (e.g., different carrier frequency and bandwidth, or different modulation) -- *MAC address filter*. When this filter is active, the radio medium - does not send signals to a radio if it the destination MAC address - does not match +- *MAC address filter*. When this filter is active, the radio medium does not + send signals to a radio if the destination MAC address does not match -The corresponding module parameters are called ``rangeFilter``, -``radioModeFilter``, ``listeningFilter`` and -``macAddressFilter``. By default, all filters are turned off. +The corresponding module parameters are called ``rangeFilter``, ``radioModeFilter``, +``listeningFilter``, and ``macAddressFilter``. By default, all filters are turned off. diff --git a/doc/src/users-guide/ch-transport.rst b/doc/src/users-guide/ch-transport.rst index 22fd7bedd00..c604e2d7e5e 100644 --- a/doc/src/users-guide/ch-transport.rst +++ b/doc/src/users-guide/ch-transport.rst @@ -38,11 +38,11 @@ TCP Overview ~~~~~~~~ -TCP protocol is the most widely used protocol of the Internet. It -provides reliable, ordered delivery of stream of bytes from one +The TCP protocol is the most widely used protocol of the Internet. It +provides reliable, ordered delivery of a stream of bytes from one application on one computer to another application on another computer. The baseline TCP protocol is described in RFC793, but other tens of RFCs -contains modifications and extensions to the TCP. As a result, TCP is a +contain modifications and extensions to TCP. As a result, TCP is a complex protocol and sometimes it is hard to see how the different requirements interact with each other. @@ -108,7 +108,7 @@ protocol in the INET framework. - Delayed ACK algorithm -- Nagle’s algorithm +- Nagle's algorithm - Silly window avoidance @@ -150,7 +150,7 @@ registering them in C++. TcpLwip ~~~~~~~ -*lwIP* is a light-weight implementation of the TCP/IP protocol suite +lwIP is a light-weight implementation of the TCP/IP protocol suite that was originally written by Adam Dunkels of the Swedish Institute of Computer Science. The current development homepage is http://savannah.nongnu.org/projects/lwip/. @@ -166,7 +166,7 @@ Features: - delayed ACK -- Nagle’s algorithm +- Nagle's algorithm - round trip time estimation @@ -202,7 +202,7 @@ Limitations TcpNsc ~~~~~~ -Network Simulation Cradle (NSC) is a tool that allow real-world TCP/IP +Network Simulation Cradle (NSC) is a tool that allows real-world TCP/IP network stacks to be used in simulated networks. The NSC project is created by Sam Jansen and available on http://research.wand.net.nz/software/nsc.php. NSC currently contains @@ -284,7 +284,7 @@ SCTP The :ned:`Sctp` module implements the Stream Control Transmission Protocol (SCTP). Like TCP, SCTP provides reliable ordered data delivery -over an ureliable network. The most prominent feature of SCTP is the +over an unreliable network. The most prominent feature of SCTP is the capability of transmitting multiple streams of data at the same time between two end points that have established a connection. @@ -297,7 +297,7 @@ The Real-time Transport Protocol (RTP) is a transport layer protocol for delivering audio and video over IP networks. RTP is used extensively in communication and entertainment systems that involve streaming media, such as telephony, video teleconference applications including WebRTC, -television services and web-based push-to-talk features. +television services, and web-based push-to-talk features. The RTP Control Protocol (RTCP) is a sister protocol of the Real-time Transport Protocol (RTP). RTCP provides out-of-band statistics and diff --git a/doc/src/users-guide/ch-tsn.rst b/doc/src/users-guide/ch-tsn.rst index 135bc439162..86d36c34ff2 100644 --- a/doc/src/users-guide/ch-tsn.rst +++ b/doc/src/users-guide/ch-tsn.rst @@ -3,9 +3,9 @@ Time-Sensitive Networking ========================= -This chapter describes the part of INET Framework that implements a subset of +This chapter describes the part of the INET Framework that implements a subset of the IEEE standards related to Time-Sensitive Networking (TSN). The supported -TSN features include among others: time synchronization, per-stream filtering +TSN features include, among others: time synchronization, per-stream filtering and policing, scheduling and traffic shaping, frame replication and elimination, frame preemption, cut-through switching, automatic network configuration for failure protection, stream redundancy, and gate scheduling. @@ -50,8 +50,8 @@ Time Synchronization -------------------- This section describes the modules that implement a subset of the IEEE 802.1AS -standard titled as Timing and Synchronization for Time-Sensitive Applications (IEEE -802.1AS-2020). There are two main components for this TSN feature, clock modules +standard titled "Timing and Synchronization for Time-Sensitive Applications" (IEEE +802.1AS-2020). There are two main components for this TSN feature: clock modules that keep track of time in the individual network nodes, and time synchronization protocol modules that synchronize these clocks. All required modules are already included in the TSN specific network nodes. @@ -64,7 +64,7 @@ can still be used to keep track of time in the network nodes. - :ned:`SettableClock` extends the previous model with the capability of setting the clock time -Similarly to the above the following gPTP time synchronization related protocol +Similarly to the above, the following gPTP time synchronization related protocol modules and network nodes can also be used to build time synchronization in a network: @@ -78,7 +78,7 @@ In order to implement node failure (e.g. master clock) and link failure (e.g. between gPTP bridges) protection, multiple time synchronization domains are required. These time domains operate independently of each other and it's up to the clock user modules of each network node to decide which clock they are using. -Typically they use the active clock of the :ned:`MultiClock` and there has to +Typically, they use the active clock of the :ned:`MultiClock`, and there has to be some means of changing the active clocks when failover happens. The following modules can be used to implement multiple time domains: @@ -107,12 +107,12 @@ The simplest module for IEEE 802.1Q per-stream filtering and policing is the :ned:`SimpleIeee8021qFilter` compound module. This module combines several submodules: a packet classifier at the input, a packet multiplexer at the output, and one packet meter, one packet filter, and one packet gate per stream. Each -one of the latter per-stream 3 modules are optional. +one of the latter per-stream 3 modules is optional. When a packet arrives at the input of the :ned:`SimpleIeee8021qFilter`, it first gets classified into one of the filtering and policing submodule paths. Then the packet meter measures the packet as part of the packet stream that was seen -so far, and attaches the result of the measurement. The result may be as +so far and attaches the result of the measurement. The result may be as simple as a label on the packet. After the metering, the packet filter checks if the packet matches the required conditions and either lets the packet go through or drops it. Finally, the packet gate allows the automatic time based @@ -122,18 +122,18 @@ either pass through or get dropped immediately. Note that any of the :ned:`SimpleIeee8021qFilter` default submodules can be replaced with other variants. Moreover, other more complicated internal structures -are also possible, this is especially the case when the packet meters are +are also possible. This is especially the case when the packet meters are replaced with token bucket classifiers as described below. As the first step, the default policing process starts with a packet classifier, -module, the :ned:`StreamClassifier` by default, that classifies packets based on the +module, the :ned:`StreamClassifier` by default that classifies packets based on the attached stream information. This classifier simply maps stream names to output gate indices. Please note that the stream decoding and identification process is not part of the :ned:`SimpleIeee8021qFilter`. In the second step, the default policing process continues with a packet meter module, the :ned:`DualRateThreeColorMeter` by default, that labels the packets either -as green, yellow or red based on the committed and excess information rate, +as green, yellow or red based on the committed and excess information rate and the committed and excess burst size parameters. The most commonly used packet meters for per-stream filtering and policing @@ -168,12 +168,12 @@ NED package for alternatives. Finally, the default policing process finishes by merging the per-stream filtering and policing paths into a single output gate by using the generic :ned:`PacketMultiplexer` module. There's no need to prioritize between the per-stream -paths here, because the packets pass through in zero simulation time. +paths here because the packets pass through in zero simulation time. Different per-stream filtering and policing compound modules can also be created by combining the existing queueing and protocol element modules of the INET Framework. For example, instead of the packet meter modules, -the token bucket based packet classifier modules give more freedom in terms +the token bucket-based packet classifier modules give more freedom in terms of the module structure. See the inet.queueing NED package for more modules. The most commonly used packet classifiers for per-stream filtering and @@ -219,9 +219,9 @@ of the IEEE 802.1Q standard that was originally introduced by the Enhancements for Scheduled Traffic (IEEE 802.1Qbv-2015) amendment. The traffic shaping architecture is part of the queue submodule of the MAC layer -in the network interface. Currently three different packet shaper algorithms -are supported, the credit-based shaper, the time-aware shaper, and the asynchronous -shaper. In order to configure the network interface to use traffic shaping the +in the network interface. Currently, three different packet shaper algorithms +are supported: the credit-based shaper, the time-aware shaper, and the asynchronous +shaper. In order to configure the network interface to use traffic shaping, the queue submodule must be replaced with either the :ned:`GatingPriorityQueue` or the :ned:`PriorityShaper` compound modules. Both contain a packet classifier to differentiate between the traffic categories and a priority packet scheduler @@ -229,22 +229,22 @@ that prefers higher priority traffic categories over lower priority ones. The difference is in the structure of the other submodules that form the shapers. The credit-based shaper is implemented in the :ned:`CreditBasedShaper` module -using a standard :ned:`PacketQueue` and a special purpose :ned:`Ieee8021qCreditBasedGate` +using a standard :ned:`PacketQueue` and a special-purpose :ned:`Ieee8021qCreditBasedGate` submodule. The latter module keeps track of the available credits for the given traffic category and allows or forbids the transmission of packets. The time-aware shaper is implemented in the :ned:`TimeAwareShaper` compound module -that uses a standard :ned:`PacketQueue` and a special purpose :ned:`PeriodicGate`. +that uses a standard :ned:`PacketQueue` and a special-purpose :ned:`PeriodicGate`. The latter module has parameters to control the gate schedule that determines the periodic open and gate. -The asynchronous shaper is in part implemented in the :ned:`AsynchronousShaper` +The asynchronous shaper is, in part, implemented in the :ned:`AsynchronousShaper` compound module. This shaper is somewhat more complicated than the previous two because it also contains submodules that are part of the ingress per-stream filtering module in the bridging layer. These are the :ned:`EligibilityTimeMeter` and the corresponding :ned:`EligibilityTimeFilter` submodules. The first is responsible for calculating the transmission eligibility time for incoming packets, the -latter is responsible for dropping packets which are considered to be too old +latter is responsible for dropping packets which are considered too old for transmission. The shaper in the network interface queue contains two additional submodules called :ned:`EligibilityTimeQueue` and :ned:`EligibilityTimeGate`. The former is responsible for sorting the frames according to the transmission @@ -263,8 +263,8 @@ Frame Replication and Elimination --------------------------------- This section describes the modules that implement a subset of the functionality -of the IEEE 802.1CB standard titled as Frame Replication and Elimination for -Reliability (IEEE 802.1CB-2017). +of the IEEE 802.1CB standard titled "Frame Replication and Elimination for +Reliability" (IEEE 802.1CB-2017). The relevant modules are all part of the :ned:`BridgingLayer` compound module that resides between the network layer and link layer protocols. This compound @@ -272,13 +272,13 @@ module also contains other functionality such as frame forwarding. There are four relevant submodules, each one implements a very specific part of frame replication. -The first part deals with stream identification, and is implemented in the +The first part deals with stream identification and is implemented in the :ned:`StreamIdentifierLayer` module and its :ned:`StreamIdentifier` submodule. This module is only useful in network nodes which produce application traffic themselves. The stream identifier module is responsible for assigning a stream -name for outgoing packets by looking at their contents and meta data. For example, +name for outgoing packets by looking at their contents and metadata. For example, packets can be identified by the destination MAC address and PCP request tags. -Since at this point the packets don't yet contain any layer 2 header the decision +Since at this point the packets don't yet contain any layer 2 header, the decision can be based on the attached request tags that will be later turned into packet headers. @@ -289,15 +289,15 @@ for merging incoming member streams into a single stream and removing duplicate frames. The latter is responsible for splitting outgoing streams into potentially several member streams. -The third part deals with ingress and egress stream filtering, and it's implemented +The third part deals with ingress and egress stream filtering and is implemented in the :ned:`StreamFilterLayer` module that contains one submodule for both directions. This part is not strictly necessary for frame replication. Most often only the ingress filtering submodule is used as described in the previous section. The last layer handles incoming packet decoding and outgoing packet encoding. -This module is called the :ned:`StreamCoderLayer` and it contains two submodules -the :ned:`StreamDecoder` and :ned:`StreamEncoder`. The former handles the stream +This module is called the :ned:`StreamCoderLayer` and it contains two submodules: +the :ned:`StreamDecoder` and the :ned:`StreamEncoder`. The former handles the stream decoding of incoming packets by checking the attached indication tags. The latter deals with the encoding of outgoing packets by attaching the necessary request tags. @@ -327,8 +327,8 @@ where modules pass packets around as a whole. - :ned:`EthernetPreemptingPhyLayer` models a PHY layer that allows the preemption of an ongoing transmission -The TSN specific network nodes, :ned:`TsnDevice` and :ned:`TsnSwitch`, have a -special parameter called the :par:`hasFramePreemption` which can be used to +The TSN specific network nodes :ned:`TsnDevice` and :ned:`TsnSwitch` have a +special parameter called :par:`hasFramePreemption` which can be used to enable frame preemption in the network interfaces. Of course, these modules can also be used in other ways. @@ -339,10 +339,10 @@ Cut-through Switching The default store and forward mechanism in Ethernet switches greatly influences the end-to-end latency of application traffic. This effect can be overcome and -drastically reduced by using cut-through switching. This methods starts forwarding +drastically reduced by using cut-through switching. This method starts forwarding the incoming frame before the whole frame has been received, usually right after the reception of the MAC header. However, cut-through switching is not a standard -mechanism and there are all kinds of variants in operation. +mechanism, and there are all kinds of variants in operation. INET provides the following modules related to cut-through switching: @@ -357,11 +357,11 @@ INET provides the following modules related to cut-through switching: - :ned:`EthernetCutthroughSink` models the sink of the cut-through forwarding inside the network interface -Surprisingly cut-through switch also has to be enabled in the end devices because +Surprisingly, cut-through switch also has to be enabled in the end devices because the receiving switch has to be notified both at the start and at the end of the frame. -The TSN specific network nodes, :ned:`TsnDevice` and :ned:`TsnSwitch`, have a -special parameter called the :par:`hasCutthroughSwitching` which can be used to +The TSN specific network nodes :ned:`TsnDevice` and :ned:`TsnSwitch` have a +special parameter called :par:`hasCutthroughSwitching` which can be used to enable cut-through switching in the network interfaces. Of course, these modules can also be used in other ways. @@ -372,11 +372,11 @@ Automatic Network Configuration Configuring the features of Time-Sensitive Networking in a complex network that contains many applications with different traffic requirements is a difficult -and error prone task. To facilitate this task, INET provides three types of +and error-prone task. To facilitate this task, INET provides three types of network level configurators: - gate scheduling configurators are capable of configuring the gate control - lists (i.e. periodic open/close states) for all traffic classes in all network + lists (i.e., periodic open/close states) for all traffic classes in all network interfaces based on packet length, packet interval, and maximum latency parameters - stream redundancy configurators are capable of configuring the stream merging and stream splitting modules as well as the stream identification in all network @@ -385,7 +385,7 @@ network level configurators: achieve the desired link and node failure protections for all streams in the network based on the set of failure cases -All other network level configurators such as the :ned:`Ipv4NetworkConfigurator` +All other network-level configurators such as the :ned:`Ipv4NetworkConfigurator` or the :ned:`MacForwardingTableConfigurator` can also be used. There are several different automatic gate scheduling configurators having @@ -403,7 +403,7 @@ There is only one stream redundancy configurator: - :ned:`StreamRedundancyConfigurator` configures stream splitting, stream merging and stream filtering in all network nodes -Currently there is only one failure protection configurator: +Currently, there is only one failure protection configurator: - :ned:`FailureProtectionConfigurator` configures the gate scheduling and the stream redundancy configurators to provide protection against the specified link and node failures diff --git a/doc/src/users-guide/ch-usage.rst b/doc/src/users-guide/ch-usage.rst index f8f00d3054f..8c3a42348ad 100644 --- a/doc/src/users-guide/ch-usage.rst +++ b/doc/src/users-guide/ch-usage.rst @@ -10,21 +10,21 @@ Installation There are several ways to install the INET Framework: -- Let the OMNeT++ IDE download and install it for you. This is the - easiest way. Just accept the offer to install INET in the dialog that - comes up when you first start the IDE, or choose :menuselection:`Help --> Install - Simulation Models` any time later. - -- From INET Framework web site, *http://inet.omnetpp.org*. The IDE - always installs the last stable version compatible with your version - of OMNeT++. If you need some other version, they are available for - download from the web site. Installation instructions are also - provided there. - -- From GitHub. If you have experience with *git*, clone the INET - Framework project (``inet-framework/inet``), check out the - revision of your choice, and follow the INSTALL file in the project - root. +- Let the OMNeT++ IDE download and install it for you. This is the + easiest way. Just accept the offer to install INET in the dialog that + comes up when you first start the IDE, or choose :menuselection:`Help --> Install + Simulation Models` any time later. + +- From the INET Framework website, *http://inet.omnetpp.org*. The IDE + always installs the latest stable version compatible with your version + of OMNeT++. If you need a different version, they are available for + download from the website. Installation instructions are also + provided there. + +- From GitHub. If you have experience with *git*, clone the INET + Framework project (``inet-framework/inet``), check out the + revision of your choice, and follow the INSTALL file in the project + root. .. _ug:sec:usage:installing-inet-extensions: @@ -37,22 +37,22 @@ follow the installation instructions provided with them. In the absence of specific instructions, the following procedure usually works: -- First, check if the project root contains a file named - :file:`.project`. +- First, check if the project root contains a file named + :file:`.project`. -- If it does, then the project can be imported into the IDE (use - :menuselection:`File --> Import --> General --> Existing Project` - into workspace). Make sure - that the project is recognized as an OMNeT++ project (the :guilabel:`Project - Properties` dialog contains a page titled *OMNeT++*), and it lists - the INET project as dependency (check the :guilabel:`Project References` page - in the :guilabel:`Project Properties` dialog). +- If it does, then the project can be imported into the IDE (use + :menuselection:`File --> Import --> General --> Existing Project` + into workspace). Make sure + that the project is recognized as an OMNeT++ project (the :guilabel:`Project + Properties` dialog contains a page titled *OMNeT++*), and it lists + the INET project as a dependency (check the :guilabel:`Project References` page + in the :guilabel:`Project Properties` dialog). -- If there is no :file:`.project` file, you can create an empty OMNeT++ - project using the :guilabel:`New OMNeT++ Project` wizard in - :menuselection:`File --> New`, add the INET project as dependency - using the :guilabel:`Project References` page in the :guilabel:`Project Properties` - dialog, and copy the source files into the project. +- If there is no :file:`.project` file, you can create an empty OMNeT++ + project using the :guilabel:`New OMNeT++ Project` wizard in + :menuselection:`File --> New`, add the INET project as a dependency + using the :guilabel:`Project References` page in the :guilabel:`Project Properties` + dialog, and copy the source files into the project. .. _ug:sec:usage:getting-familiar-with-inet: @@ -60,43 +60,43 @@ Getting Familiar with INET -------------------------- The INET Framework builds upon OMNeT++, and uses the same concept: -modules that communicate by message passing. Hosts, routers, switches +modules that communicate by message passing. Hosts, routers, switches, and other network devices are represented by OMNeT++ compound modules. These compound modules are assembled from simple modules that represent protocols, applications, and other functional units. A network is again -an OMNeT++ compound module that contains host, router and other modules. +an OMNeT++ compound module that contains host, router, and other modules. Modules are organized into a directory structure that roughly follows OSI layers: -- :file:`src/inet/applications/` – traffic generators and application - models +- :file:`src/inet/applications/` – traffic generators and application + models -- :file:`src/inet/transportlayer/` – transport layer protocols +- :file:`src/inet/transportlayer/` – transport layer protocols -- :file:`src/inet/networklayer/` – network layer protocols and - accessories +- :file:`src/inet/networklayer/` – network layer protocols and + accessories -- :file:`src/inet/linklayer/` – link layer protocols and accessories +- :file:`src/inet/linklayer/` – link layer protocols and accessories -- :file:`src/inet/physicallayer/` – physical layer models +- :file:`src/inet/physicallayer/` – physical layer models -- :file:`src/inet/routing/` – routing protocols (internet and ad hoc) +- :file:`src/inet/routing/` – routing protocols (internet and ad hoc) -- :file:`src/inet/mobility/` – mobility models +- :file:`src/inet/mobility/` – mobility models -- :file:`src/inet/power/` – energy consumption modeling +- :file:`src/inet/power/` – energy consumption modeling -- :file:`src/inet/environment/` – model of the physical environment +- :file:`src/inet/environment/` – model of the physical environment -- :file:`src/inet/node/` – preassembled network node models +- :file:`src/inet/node/` – preassembled network node models -- :file:`src/inet/visualizer/` – visualization components (2D and 3D) +- :file:`src/inet/visualizer/` – visualization components (2D and 3D) -- :file:`src/inet/common/` – miscellaneous utility components +- :file:`src/inet/common/` – miscellaneous utility components -The OMNeT++ NED language uses hierarchical packages names. Packages -correspond to directories under :file:`src/`, so e.g. the +The OMNeT++ NED language uses hierarchical package names. Packages +correspond to directories under :file:`src/`, so for example, the :file:`src/inet/transportlayer/tcp` directory corresponds to the ``inet.transportlayer.tcp`` NED package. diff --git a/doc/src/users-guide/ch-visualization.rst b/doc/src/users-guide/ch-visualization.rst index bc959675485..c4684a31cea 100644 --- a/doc/src/users-guide/ch-visualization.rst +++ b/doc/src/users-guide/ch-visualization.rst @@ -8,11 +8,11 @@ Visualization Overview -------- -The INET Framework is able to visualize a wide range of events and -conditions in the network: packet drops, data link connectivity, -wireless signal path loss, transport connections, routing table routes, -and many more. Visualization is implemented as a collection of -configurable INET modules that can be added to simulations at will. +The INET Framework is capable of visualizing a wide range of events and +conditions in the network: packet drops, data link connectivity, wireless signal +path loss, transport connections, routing table routes, and many more. +Visualization is implemented as a collection of configurable INET modules that +can be added to simulations at will. .. _ug:sec:visualization:network-communication: @@ -24,41 +24,38 @@ Visualizing Network Communication Visualizing Packet Drops ~~~~~~~~~~~~~~~~~~~~~~~~ -Several network problems manifest themselves as excessive packet drops, -for example poor connectivity, congestion, or misconfiguration. -Visualizing packet drops helps identifying such problems in simulations, -thereby reducing time spent on debugging and analysis. Poor connectivity -in a wireless network can cause senders to drop unacknowledged packets -after the retry limit is exceeded. Congestion can cause queues to -overflow in a bottleneck router, again resulting in packet drops. - -Packet drops can be visualized by including a -:ned:`PacketDropVisualizer` module in the simulation. The -:ned:`PacketDropVisualizer` module indicates packet drops by displaying -an animation effect at the node where the packet drop occurs. In the -animation, a packet icon gets thrown out from the node icon, and fades -away. - -The visualization of packet drops can be enabled with the visualizer’s -:par:`displayPacketDrops` parameter. By default, packet drops at all -nodes are visualized. This selection can be narrowed with the -:par:`nodeFilter`, :par:`interfaceFilter` and :par:`packetFilter` -parameters. - -One can click on the packet drop icon to display information about the -packet drop in the inspector panel. +Several network problems manifest themselves as excessive packet drops, such as +poor connectivity, congestion, or misconfiguration. Visualizing packet drops +helps in identifying such problems in simulations and reduces time spent on +debugging and analysis. Poor connectivity in a wireless network can cause +senders to drop unacknowledged packets after the retry limit is exceeded. +Congestion can cause queues to overflow in a bottleneck router, resulting in +packet drops. + +Packet drops can be visualized by including a :ned:`PacketDropVisualizer` module +in the simulation. The :ned:`PacketDropVisualizer` module indicates packet drops +by displaying an animation effect at the node where the packet drop occurs. In +the animation, a packet icon gets thrown out from the node icon and fades away. + +The visualization of packet drops can be enabled with the visualizer's +:par:`displayPacketDrops` parameter. By default, packet drops at all nodes are +visualized. This selection can be narrowed with the :par:`nodeFilter`, +:par:`interfaceFilter`, and :par:`packetFilter` parameters. + +One can click on the packet drop icon to display information about the packet +drop in the inspector panel. Packets are dropped for the following reasons: -- queue overflow +- Queue overflow -- retry limit exceeded +- Retry limit exceeded -- unroutable packet +- Unroutable packet -- network address resolution failed +- Network address resolution failed -- interface down +- Interface down .. _ug:sec:visualization:transport-path-activity: @@ -75,7 +72,7 @@ feedback about transport layer traffic. the transport layers of two endpoints. Adding an :ned:`IntegratedVisualizer` is also an option, because it also contains a :ned:`TransportRouteVisualizer`. Transport path activity visualization -is disabled by default, it can be enabled by setting the visualizer’s +is disabled by default, it can be enabled by setting the visualizer's :par:`displayRoutes` parameter to true. :ned:`TransportRouteVisualizer` observes packets that pass through the @@ -91,7 +88,7 @@ Color, fading time and other graphical properties can be changed with parameters of the visualizer. By default, all packets and nodes are considered for the visualization. -This selection can be narrowed with the visualizer’s packetFilter and +This selection can be narrowed with the visualizer's packetFilter and nodeFilter parameters. .. _ug:sec:visualization:network-path-activity: @@ -104,7 +101,7 @@ Network layer traffic can be visualized by including a :ned:`IntegratedVisualizer` module is also an option, because it also contains a :ned:`NetworkRouteVisualizer` module. Network path activity visualization is disabled by default, it can be enabled by setting the -visualizer’s :par:`displayRoutes` parameter to true. +visualizer's :par:`displayRoutes` parameter to true. :ned:`NetworkRouteVisualizer` currently observes packets that pass through the network layer (i.e. carry data from/to higher layers), but @@ -115,14 +112,14 @@ will not trigger the visualization. The activity between two nodes is represented visually by a polyline arrow which points from the source node to the destination node. :ned:`NetworkRouteVisualizer` follows packet throughout its path so the -polyline goes through all nodes that are part of the packet’s path. The +polyline goes through all nodes that are part of the packet's path. The arrow appears after the first packet has been received, then gradually fades out unless it is reinforced by further packets. Color, fading time and other graphical properties can be changed with parameters of the visualizer. By default, all packets and nodes are considered for the visualization. -This selection can be narrowed with the visualizer’s packetFilter and +This selection can be narrowed with the visualizer's packetFilter and nodeFilter parameters. .. _ug:sec:visualization:data-link-activity: @@ -134,7 +131,7 @@ Data link activity (layer 2 traffic) can be visualized by adding a :ned:`DataLinkVisualizer` module to the simulation. Adding an :ned:`IntegratedVisualizer` module is also an option, because it includes a :ned:`DataLinkVisualizer` module. Data link visualization is -disabled by default, it can be enabled by setting the visualizer’s +disabled by default, it can be enabled by setting the visualizer's displayLinks parameter to true. :ned:`DataLinkVisualizer` currently observes packets that pass through @@ -154,7 +151,7 @@ visualizer. By default, all packets, interfaces and nodes are considered for the visualization. This selection can be narrowed to certain packets and/or -nodes with the visualizer’s :par:`packetFilter`, :par:`interfaceFilter`, +nodes with the visualizer's :par:`packetFilter`, :par:`interfaceFilter`, and :par:`nodeFilter` parameters. .. _ug:sec:visualization:physical-link-activity: @@ -164,78 +161,71 @@ Visualizing Physical Link Activity Physical link activity can be visualized by including a :ned:`PhysicalLinkVisualizer` module in the simulation. Adding an -:ned:`IntegratedVisualizer` module is also an option, because it also -contains a :ned:`PhysicalLinkVisualizer` module. Physical link activity -visualization is disabled by default, it can be enabled by setting the -visualizer’s :par:`displayLinks` parameter to true. +:ned:`IntegratedVisualizer` module is also an option, as it also contains a +:ned:`PhysicalLinkVisualizer` module. Physical link activity visualization is +disabled by default, but it can be enabled by setting the visualizer's +:par:`displayLinks` parameter to true. -:ned:`PhysicalLinkVisualizer` observes frames that pass through the -physical layer, i.e. are received correctly. +:ned:`PhysicalLinkVisualizer` observes frames that pass through the physical +layer, meaning they are received correctly. -The activity between two nodes is represented visually by a dotted arrow -which points from the sender node to the receiver node. The arrow -appears after the first frame has been received, then gradually fades -out unless it is refreshed by further frames. Color, fading time and -other graphical properties can be changed with parameters of the -visualizer. +The activity between two nodes is visually represented by a dotted arrow that +points from the sender node to the receiver node. The arrow appears after the +first frame has been received and gradually fades out unless it is refreshed by +further frames. Color, fading time, and other graphical properties can be +changed with parameters of the visualizer. -By default, all packets, interfaces and nodes are considered for the -visualization. This selection can be narrowed with the visualizer’s -:par:`packetFilter`, :par:`interfaceFilter`, and :par:`nodeFilter` -parameters. +By default, all packets, interfaces, and nodes are considered for the +visualization. This selection can be narrowed with the visualizer's +:par:`packetFilter`, :par:`interfaceFilter`, and :par:`nodeFilter` parameters. .. _ug:sec:visualization:routing-tables: Visualizing Routing Tables ~~~~~~~~~~~~~~~~~~~~~~~~~~ -In a complex network topology, it is difficult to see how a packet would -be routed because the relevant data is scattered among network nodes and -hidden in their routing tables. INET contains support for visualization -of routing tables, and can display routing information graphically in a -concise way. Using visualization, it is often possible to understand -routing in a simulation without looking into individual routing tables. -The visualization currently supports IPv4. - -The :ned:`RoutingTableVisualizer` module (included in the network as -part of :ned:`IntegratedVisualizer`) is responsible for visualizing -routing table entries. - -The visualizer basically annotates network links with labeled arrows -that connect source nodes to next hop nodes. The module visualizes those -routing table entries that participate in the routing of a given set of -destination addresses, by default the addresses of all interfaces of all -nodes in the network. That is, it selects the best (longest prefix) -matching routes for all destination addresses from each routing table, -and shows them as arrows that point to the next hop. Note that one arrow -might need to represent several routing entries, for example when -distinct prefixes are routed towards the same next hop. - -Routing table entries are represented visually by solid arrows. An arrow -going from a source node represents a routing table entry in the source -node’s routing table. The endpoint node of the arrow is the next hop in -the visualized routing table entry. By default, the routing entry is -displayed on the arrows in following format: - - - -:: - - destination/mask -> gateway (interface) - -The format can be changed by setting the visualizer’s :par:`labelFormat` +In a complex network topology, it is difficult to see how a packet would be +routed because the relevant data is scattered among network nodes and hidden in +their routing tables. INET contains support for visualization of routing tables +and can display routing information graphically in a concise way. Using +visualization, it is often possible to understand routing in a simulation +without looking into individual routing tables. The visualization currently +supports IPv4. + +The :ned:`RoutingTableVisualizer` module (included in the network as part of +:ned:`IntegratedVisualizer`) is responsible for visualizing routing table +entries. + +The visualizer basically annotates network links with labeled arrows that +connect source nodes to next hop nodes. The module visualizes those routing +table entries that participate in the routing of a given set of destination +addresses, by default the addresses of all interfaces of all nodes in the +network. That is, it selects the best (longest prefix) matching routes for all +destination addresses from each routing table and shows them as arrows that +point to the next hop. Note that one arrow might need to represent several +routing entries, for example, when distinct prefixes are routed towards the same +next hop. + +Routing table entries are visually represented by solid arrows. An arrow going +from a source node represents a routing table entry in the source node's routing +table, and the endpoint node of the arrow is the next hop in the visualized +routing table entry. By default, the routing entry is displayed on the arrows in +the following format: + +destination/mask -> gateway (interface) + +The format can be changed by setting the visualizer's :par:`labelFormat` parameter. -Filtering is also possible. The :par:`nodeFilter` parameter controls -which nodes’ routing tables should be visualized (by default, all -nodes), and the :par:`destinationFilter` parameter selects the set of -destination nodes to consider (again, by default all nodes.) +Filtering is also possible. The :par:`nodeFilter` parameter controls which +nodes' routing tables should be visualized (by default, all nodes), and the +:par:`destinationFilter` parameter selects the set of destination nodes to +consider (again, by default all nodes). -The visualizer reacts to changes. For example, when a routing protocol -changes a routing entry, or an IP address gets assigned to an interface -by DHCP, the visualizer automatically updates the visualizations -according to the specified filters. This is very useful e.g. for the -simulation of mobile ad-hoc networks. +The visualizer reacts to changes, such as when a routing protocol changes a +routing entry or an IP address gets assigned to an interface by DHCP. The +visualizer automatically updates the visualizations according to the specified +filters. This is very useful for the simulation of mobile ad-hoc networks. .. _ug:sec:visualization:displaying-ip-addresses-and-other-interface-information: @@ -252,7 +242,7 @@ can also be accessed in the GUI by diving into the interface tables of each node, that is tedious, and unsuitable for getting an overview. The :ned:`InterfaceTableVisualizer` module (included in the network as -part of :ned:`IntegratedVisualizer`) displays data about network nodes’ +part of :ned:`IntegratedVisualizer`) displays data about network nodes' interfaces. (Interfaces are contained in interface tables, hence the name.) By default, the visualization is turned off. When it is enabled using the :par:`displayInterfaceTables` parameter, the default is that @@ -277,8 +267,8 @@ takes a format string, which can contain the following directives: - %M: MAC address -- %\: conditional newline for wired interfaces. The ’\’ needs to be - escaped with another ’\’, i.e. ’%\\’ +- %\: conditional newline for wired interfaces. The '\' needs to be + escaped with another '\', i.e. '%\\' - %i and %s: the info() and str() functions for the networkInterface class, respectively @@ -286,7 +276,7 @@ takes a format string, which can contain the following directives: The default format string is ``"%N %\\%n/%l"``, i.e. interface name, IP address and netmask length. -The set of visualized interfaces can be selected with the configurator’s +The set of visualized interfaces can be selected with the configurator's :par:`nodeFilter` and :par:`interfaceFilter` parameters. By default, all interfaces of all nodes are visualized, except for loopback addresses (the default for the :par:`interfaceFilter` parameter is ``"not lo\"``.) @@ -303,67 +293,63 @@ selection. Visualizing IEEE 802.11 Network Membership ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When simulating wifi networks that overlap in space, it is difficult to -see which node is a member of which network. The membership may even -change over time. It would be useful to be able to display e.g. the SSID -above node icons. +When simulating Wi-Fi networks that overlap in space, it is difficult to see +which node is a member of which network. The membership may even change over +time. It would be useful to be able to display the SSID above node icons. -IEEE 802.11 network membership can be visualized by including a +IEEE 802.11 network membership can be visualized by including an :ned:`Ieee80211Visualizer` module in the simulation. Adding an -:ned:`IntegratedVisualizer` is also an option, because it also contains -a :ned:`Ieee80211Visualizer`. Displaying network membership is disabled -by default, it can be enabled by setting the visualizer’s +:ned:`IntegratedVisualizer` is also an option, as it also contains an +:ned:`Ieee80211Visualizer`. Displaying network membership is disabled by +default, but it can be enabled by setting the visualizer's :par:`displayAssociations` parameter to true. -The :ned:`Ieee80211Visualizer` displays an icon and the SSID above -network nodes which are part of a wifi network. The icons are -color-coded according to the SSID. The icon, colors, and other visual -properties can be configured via parameters of the visualizer. +The :ned:`Ieee80211Visualizer` displays an icon and the SSID above network nodes +that are part of a Wi-Fi network. The icons are color-coded according to the +SSID. The icon, colors, and other visual properties can be configured via +parameters of the visualizer. -The visualizer’s :par:`nodeFilter` parameter selects which nodes’ -memberships are visualized. The :par:`interfaceFilter` parameter selects -which interfaces are considered in the visualization. By default, all -interfaces of all nodes are considered. +The visualizer's :par:`nodeFilter` parameter selects which nodes' memberships +are visualized. The :par:`interfaceFilter` parameter selects which interfaces +are considered in the visualization. By default, all interfaces of all nodes are +considered. .. _ug:sec:visualization:transport-connections: Visualizing Transport Connections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In a large network with a complex topology, there might be many -transport layer applications and many nodes communicating. In such a -case, it might be difficult to see which nodes communicate with which, -or if there is any communication at all. Transport connection -visualization makes it easy to get information about the active -transport connections in the network at a glance. Visualization makes it -easy to identify connections by their two endpoints, and to tell -different connections apart. It also gives a quick overview about the -number of connections in individual nodes and the whole network. +In a large network with a complex topology, there might be many transport layer +applications and many nodes communicating. In such a case, it might be difficult +to see which nodes communicate with which, or if there is any communication at +all. Transport connection visualization makes it easy to get information about +the active transport connections in the network at a glance. Visualization makes +it easy to identify connections by their two endpoints and to tell different +connections apart. It also gives a quick overview of the number of connections +in individual nodes and the whole network. The :ned:`TransportConnectionVisualizer` module (also part of -:ned:`IntegratedVisualizer`) displays color-coded icons above the two -endpoints of an active, established transport layer level connection. -The icons will appear when the connection is established, and disappear -when it is closed. Naturally, there can be multiple connections open at -a node, thus there can be multiple icons. Icons have the same color at -both ends of the connection. In addition to colors, letter codes (A, B, -AA, …) may also be displayed to help in identifying connections. Note -that this visualizer does not display the paths the packets take. If you -are interested in that, take a look at :ned:`TransportRouteVisualizer`, -covered in section :ref:`ug:sec:visualization:transport-path-activity`. - -The visualization is turned off by default, it can be turned on by -setting the :par:`displayTransportConnections` parameter of the -visualizer to true. - -It is possible to filter the connections being visualized. By default, -all connections are included. Filtering by hosts and port numbers can be -achieved by setting the :par:`sourcePortFilter`, -:par:`destinationPortFilter`, :par:`sourceNodeFilter` and -:par:`destinationNodeFilter` parameters. - -The icon, colors and other visual properties can be configured by -setting the visualizer’s parameters. +:ned:`IntegratedVisualizer`) displays color-coded icons above the two endpoints +of an active, established transport layer level connection. The icons appear +when the connection is established and disappear when it is closed. Naturally, +there can be multiple connections open at a node, thus there can be multiple +icons for each node. Icons have the same color at both ends of the connection. +In addition to colors, letter codes (A, B, AA, ...) may also be displayed to +help identify connections. Note that this visualizer does not display the paths +the packets take. If you are interested in that, take a look at +:ned:`TransportRouteVisualizer`, covered in section +:ref:`ug:sec:visualization:transport-path-activity`. + +The visualization is turned off by default, but it can be turned on by setting +the :par:`displayTransportConnections` parameter of the visualizer to true. + +It is possible to filter the connections being visualized. By default, all +connections are included. Filtering by hosts and port numbers can be achieved by +setting the :par:`sourcePortFilter`, :par:`destinationPortFilter`, +:par:`sourceNodeFilter`, and :par:`destinationNodeFilter` parameters. + +The icon, colors, and other visual properties can be configured by setting the +visualizer's parameters. .. _ug:sec:visualization:the-infrastructure: @@ -375,70 +361,65 @@ Visualizing The Infrastructure Visualizing the Physical Environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The physical environment has a profound effect on the communication of -wireless devices. For example, physical objects like walls inside -buildings constraint mobility. They also obstruct radio signals often -resulting in packet loss. It’s difficult to make sense of the simulation -without actually seeing where physical objects are. +The physical environment has a profound effect on the communication of wireless +devices. Physical objects like walls inside buildings constrain mobility and +obstruct radio signals, often resulting in packet loss. It's difficult to make +sense of the simulation without actually seeing where physical objects are. -The visualization of physical objects present in the physical -environment is essential. +The visualization of physical objects present in the physical environment is +essential. The :ned:`PhysicalEnvironmentVisualizer` (also part of -:ned:`IntegratedVisualizer`) is responsible for displaying the physical -objects. The objects themselves are provided by the PhysicalEnvironment -module; their geometry, physical and visual properties are defined in -the XML configuration of the PhysicalEnvironment module. +:ned:`IntegratedVisualizer`) is responsible for displaying the physical objects. +The objects themselves are provided by the PhysicalEnvironment module; their +geometry, physical, and visual properties are defined in the XML configuration +of the PhysicalEnvironment module. The two-dimensional projection of physical objects is determined by the -:ned:`SceneCanvasVisualizer` module. (This is because the projection is -also needed by other visualizers, for example -:ned:`MobilityVisualizer`.) The default view is top view (z axis), but -you can also configure side view (x and y axes), or isometric or -ortographic projection. +:ned:`SceneCanvasVisualizer` module. (This is because the projection is also +needed by other visualizers, for example, :ned:`MobilityVisualizer`). The +default view is top view (z-axis), but you can also configure a side view (x and +y axes), or isometric or orthographic projection. -The visualizer also supports OpenGL-based 3D rendering using the -OpenSceneGraph (OSG) library. If the OMNeT++ installation has been -compiled with OSG support, you can switch to 3D view using the Qtenv -toolbar. +The visualizer also supports OpenGL-based 3D rendering using the OpenSceneGraph +(OSG) library. If the OMNeT++ installation has been compiled with OSG support, +you can switch to 3D view using the Qtenv toolbar. .. _ug:sec:visualization:node-mobility: Visualizing Node Mobility ~~~~~~~~~~~~~~~~~~~~~~~~~ -In INET simulations, the movement of mobile nodes is often as important -as the communication among them. However, as mobile nodes roam, it is -often difficult to visually follow their movement. INET provides a -visualizer that not only makes visually tracking mobile nodes easier, -but also indicates other properties like speed and direction. +In INET simulations, the movement of mobile nodes is often as important as the +communication among them. However, as mobile nodes roam, it is often difficult +to visually follow their movement. INET provides a visualizer that not only +makes visually tracking mobile nodes easier but also indicates other properties +like speed and direction. -Node mobility of nodes can be visualized by :ned:`MobilityVisualizer` -module (included in the network as part of :ned:`IntegratedVisualizer`). -By default, mobility visualization is enabled, it can be disabled by -setting :par:`displayMovements` parameter to false. +Node mobility can be visualized by the :ned:`MobilityVisualizer` module +(included in the network as part of :ned:`IntegratedVisualizer`). By default, +mobility visualization is enabled, but it can be disabled by setting the +:par:`displayMovements` parameter to false. -By default, all mobilities are considered for the visualization. This -selection can be narrowed with the visualizer’s :par:`moduleFilter` -parameter. +By default, all mobilities are considered for the visualization. This selection +can be narrowed with the visualizer's :par:`moduleFilter` parameter. The visualizer has several important features: -- Movement Trail: It displays a line along the recent path of - movements. The trail gradually fades out as time passes. Color, trail - length and other graphical properties can be changed with parameters - of the visualizer. +- Movement Trail: It displays a line along the recent path of movements. The + trail gradually fades out as time passes. Color, trail length, and other + graphical properties can be changed with parameters of the visualizer. + +- Velocity Vector: Velocity is visually represented by an arrow. Its starting + point is the node, and its direction coincides with the movement's direction. + The arrow's length is proportional to the node's speed. -- Velocity Vector: Velocity is represented visually by an arrow. Its - starting point is the node, and its direction coincides with the - movement’s direction. The arrow’s length is proportional to the - node’s speed. +- Orientation Arc: Node orientation is represented by an arc whose size is + specified by the :par:`orientationArcSize` parameter. This value is the + relative size of the arc compared to a full circle. The default arc size is + 0.25, meaning a quarter of a circle. -- Orientation Arc: Node orientation is represented by an arc whose size - is specified by the :par:`orientationArcSize` parameter. This value - is the relative size of the arc compared to a full circle. The arc’s - default value is 0.25, i.e. a quarter of a circle. +These features are disabled by default but can be enabled by setting the +visualizer's :par:`displayMovementTrails`, :par:`displayVelocities`, and +:par:`displayOrientations` parameters to true. -These features are disabled by default; they can be enabled by setting -the visualizer’s :par:`displayMovementTrails`, :par:`displayVelocities` -and :par:`displayOrientations` parameters to true. diff --git a/doc/src/users-guide/index.rst b/doc/src/users-guide/index.rst index 0e044023e35..bcb9ce64c9f 100644 --- a/doc/src/users-guide/index.rst +++ b/doc/src/users-guide/index.rst @@ -4,7 +4,7 @@ Release: |release| This manual is written for users who are interested in assembling simulations using the components provided by the INET Framework. (In -contrast, if you are interested in modifying INET’s components or plan to +contrast, if you are interested in modifying INET's components or plan to extend INET with new protocols or other components using C++, we recommend the :doc:`INET Developer's Guide `.)