INET 4.3.0

This is a new minor stable release of the INET 4.x branch. The highlights of this
release are the infrastructure for Time-Sensitive Networking protocols, the EIGRP
routing protocol and DCTCP congestion control.

For TSN support, a new modular Ethernet MAC and PHY layer model has been added
which provides Ethernet frame preemption, Ethernet cut-through switching, a gating
mechanism for packet queueing, and a clock model which also models clock drifting.

New API level features include intra-node packet streaming, inter-node transmission
update support, bit level packet data identity tracking, and the ability to define
and measure packet flows.

There are also a number of small improvements, and several bug fixes. Some changes
are backward incompatible, so existing models may need to be updated. This version
requires OMNeT++ 6.0 preview 10 or later.

For a complete list of all added, removed, and change folders, NED modules, packet
chunks, packet tags, statistics, C++ classes, and signals please refer to src/ChangeLog.

Notable backward incompatible changes

1. Packet API

The packet tag, chunk tag and chunk region tag APIs have been changed to
store all tags using shared pointers. Moreover, the vectors containing said
tags have also been changed to be stored using shared pointers. These shared
data structures are automatically copied behind the scenes when they are
modified, and they are also shared among multiple packets.

The reasoning is that packets are copied quite often, so this operation must
be very efficient both in terms of space and time. Often the copied packet is
not modified with respect to the attached tags, so it makes sense to share these
data structures. The previous packet API already shared the packet data between
copies, but it didn't share the attached tags.

Internally, the class TagSet has been replaced with another class, SharedTagSet,
and similarly, the class RegionTagSet has been replaced with SharedRegionTagSet.

This change requires the modification of simulation models, because tags are
now returned as shared pointers. Moreover, a different method must be called,
namely the ones with the 'ForUpdate' suffix, to modify existing tags. Due to
this copy-on-write semantics, this change can also break existing user code.

2. Ethernet

Several modules which had an abbreviated Ether in their names have been renamed
to have the complete word, Ethernet, in their names instead. This change affects
many names: EthernetSwitch, EthernetMac, EthernetLink, EthernetSignal, etc.

The Ethernet switch relay functionality provided by the MacRelayUnit and
Ieee8021dRelay modules have been refactored. The most prominent change is that
these modules no longer work on Ethernet frames only. They simply expect the
packets to contain the necessary metadata such as the incoming interface
indication (InterfaceInd) and the source and destination MAC address indication
(MacAddressInd) in order to operate.

A new WireJunction module has been added which replaces the functionality of
the old EtherBus and EtherHub modules. This module represents a generic wiring
hub, and simply broadcasts messages (packets, frames, signals) received on one
port to all other ports, mimicking the propagation of wired electrical signals.

The physical signal class hierarchy has been refactored, the old Signal class
has been split into a generic wireless signal, called WirelessSignal, and
a generic wired signal, called WiredSignal, both subclassed from Signal.

The renames may break existing simulations but they are easy to follow. The
MAC relay changes are internal to network nodes and may only break Ethernet
extension models. All the other changes are likely to produce compilation
errors.

3. IEEE 802.1q support

The old 802.1q support has been removed from the default EthernetInterface,
because it unnecessarily complicated the network interface and it was not
extensible.

The LinkLayerNodeBase base module has been extended with separate and optional
Ethernet and IEEE 802.1q protocol layers, where protocol modules have on instance
per network node. This results in a different structure from the default one
where the Ethernet protocol is part of the network interface. The advantage is
that various additional IEEE 802 protocols such as 802 LLC, 802 SNAP, 802.1q
and 802.1ae are better composable this way.

Several small layered protocol models and infrastructure components have been
added to support these IEEE 802 protocols. These include among others protocol
header inserters and checkers, protocol printers and dissectors, etc.

This change may break simulations that used the old IEEE 802.1q support. They
must be carefully investigated and updated to use the new model instead.

4. VLAN support

The VLAN support has been completely refactored to use separate modules for
filtering and mapping VLAN indications and requests on packets according to
a user-configurable policy. The new VlanIndFilter and VlanReqMapper modules
are part of a VLAN policy module of Ethernet switches by default.

This change may cause simulations to ignore certain parameters which are
expected to affect virtual interfaces and thus break existing simulations.

5. Virtual interfaces

The vlan submodule vector of network nodes inherited from LinkLayerNodeBase
has been renamed to virt. The original name suggested misleadingly that this
set of network interfaces were meant to be used exclusively for VLAN, but that
is not the case. The virtual interfaces, called VirtualInterface, can be used
for all kinds of protocol parameterization such as changing the source MAC
address.

This change may cause simulations to ignore certain parameters which are
expected to affect virtual interfaces.

6. Registering protocols and services

There was some confusion with respect to the expected module gates in the
arguments of the registerService() and registerProtocol() methods. Following
the OSI terminology, the registerService() method now takes the requestIn
and indicationOut gates, the registerProtocol() method takes the requestOut
and indicationIn gates as arguments. This change has been followed with
all affected modules.

Unfortunately, this change may break existing code silently, although not
very likely. The registration calls may provide the incorrect gates to the
MessageDispatcher modules, which in turn will dispatch the packets to the
wrong modules or not at all. Luckily, in the latter case, an error will be
thrown and the simulation terminates.

7. Mobility

All methods in the IMobility interface that returned a Coord or a Quaternion
data structure by value have been changed to return a const reference instead.
These methods, especially the getCurrentPosition() method, may be called quite
often, so avoiding the copying of said data structures increases performance.

This change can be followed easily by implementations, because in most cases
the values were already stored in the mobility modules. This change is not
expected to break existing models silently.

8. Radio medium analog model

Similarly to the IMobility interface change, several methods that returned
or received as an argument a Coord or a Quaternion data structure by value
has been changed to return or receive a const reference instead. Again, these
methods may be called quite often in wireless network simulations, so avoiding
the copying of these data structures increases performance.

This change has very little effect on the implementations, since in most cases
the values were already stored in the related object with a large enough dynamic
extent. This change is not expected to break existing models silently.

9. Queueing model

The IPacketQueue interface has been changed to use explicit enqueuePacket()
and dequeuePacket() methods instead of relying on the generic pushPacket()
and pullPacket().

This change required to updated all existing MAC models to use the new API.
Other 3rd party MAC modules have to be updated accordingly.

10. Renames

Several folders in the physicallayer folder have been moved below the newly
added wired and wireless folders, and renamed. Besides, all support modules have
been moved one level deeper into the common folders. This change helps new
users to find existing physical layer technologies more easily, because they
have their own folders right inside the wired and wireless folders. This change
separates the largely independent wired and wireless physical layer support
modules and implementations.

Similary to the above, several folders in the visualizer folder have been
moved below the newly added canvas and osg folders. This change is required
in order to be able to add separate features for canvas (2D) and OSG (3D)
visualizations.

The InterfaceEntry module that represents network interfaces has been renamed
to NetworkInterface. The old name was a left-over from the time when this
class was really an integral part of the InterfaceTable module. This is no
longer the case, thus the renaming makes perfect sense.

The Protocol::ieee8022 global protocol variable has been renamed, and split
into Protocol::ieee8022llc and Protocol::ieee8022snap.

The queueing API has been updated to reflect the new push/pull duality in
the naming convention as opposed to the old push/pop duality. For example,
the old packetPopped signal has been renamed to packetPulled, and the old
popPacket() method in the IPassivePacketSource has been renamed to pullPacket().

The IPacketQueueingElement C++ interface and the corresponding base class,
called PacketQueueingElementBase, has been renamed to IPacketProcessor and
PacketProcessorBase, respectively. The reason is that, although these classes
are part of the queueing API, they are more general and their original name
didn't capture this fact. Also, in several protocol implementations deriving
classes from the classes with the original names looked really weird.

All integral C++ type alias have been replaced with the standard variants.
For example, the int64 type alias has been replaced with int64_t.

These changes mostly result in NED errors and C++ compilation errors in the
simulation models which are affected, and they are easy to follow.

11. Removed models

The NetAnimTrace module has been removed. The visualization functionality it
provided has been replaced with the much more versatile and feature rich
visualizer modules.

The PacketDump class, which was used to provide a very basic human readable
string representation of the packet content, has been removed. The packet
printer API is a much more versatile and widely parameterizable way of
printing packets, and there's no reason to have two different ways of doing
the same thing.

The EtherBus module has been removed because it has been completely replaced
with the generic WireJunction module.

The Ieee8021qEncap module has been removed. This module was used in the Ethernet
network interfaces to provide IEEE 802.1q protocol support and VLAN networking.

These changes break existing simulation models with a compile time or runtime
error.

Notable backward compatible changes

1. Packet API

The Packet API has been extended with several new replace and update methods.
The replace methods allow replacing arbitrary parts of the packet content with
a single method call. The update methods allow updating arbitrary parts of the
packet content in place with a single method call. Similarly to the completeness
of these methods, the remove and insert methods have also been further extended.

Moreover, the Packet API has been extended with a packet level region tag
support. This allows attaching region tags to the data of packets similarly
to how chunks already allowed this. The main difference is that when data
is attached to chunks, then it must be in a form that can be shared among
multiple packets which share the same chunk throughout the network. For
example, the creation timestamp of coherent data fragments is such a data.
In contrast, the queueing time of coherent data fragments belongs to the
individual packets, and must be separately updated for different paths the
same data takes in the network.

The chunk API has been extended with a bit-level identity tracking of data.
In other words, it is now possible to determine if the data that shows up at
two different locations in the network, independently of whether these locations
are in the same network node or not, and also independently of how the data
is represented (field-based or binary), is the same data or not. This feature,
for example, is useful for end-to-end delay measurements and more accurate
path visualization.

A new chunk class, called EncryptedChunk, has been added to allow storing
encrypted data in a packet without actually encrypting the data. Internally,
the new chunk uses a shared reference to the encrypted chunk and the length
of the encrypted binary representation.

Efficient parsim support has been added to all classes of the Packet API,
including the Packet class itself, all chunk classes, and all tags.

The PacketProtocolTag has been extended with an extra front and back offset
that further specifies where the actual protocol is to be found within the
packet data. This feature is primarily useful to keep the associated protocol
of the packet up to date even while the packet is being constructed within a
protocol module. Doing so allows the packet printer and packet dissector to
understand a partially encapsulated, incomplete packet.

2. Clock model

Several new modules have been added to support the modeling of hardware clocks
and the related clock drift phenomena. The new modules can be found in a new
top level folder called clock. The clock model is an optional feature that
can be most conveniently used via the ClockUserModuleBase and ClockUserModuleMixin
classes.

Several modules have been extended with optional clock support: UdpBasicApp,
InterpacketGapInserter, TransmitterBase, PeriodicGate, etc. This feature has
been documented in the User's Guide.

3. Ethernet

A completely new modular Ethernet model has been added to the linklayer and
physicallayer folders. The three most prominent new features that are directly
supported are the Ethernet frame preemption, Ethernet cut-through switching,
and the gating mechanism in the Ethernet queues.

The new model contains of several smaller modules that allow the user to
combine them in more ways than before and also to customize their behavior.
The main purpose of this change was to provide support for Ethernet
Time-Sensitive Networking (TSN) features.

Following the changes in the OMNeT++ cDatarateChannel API, both existing
Ethernet MAC models that used the old forceTransmissionFinishTime() API have
been updated to use the new transmission update mechanism instead.

4. PPP

Similarly to the change in the Ethernet model, the PPP protocol implementation
has been changed to use the new transmission update API in place of the old
forceTransmissionFinishTime().

5. TCP

A new congestion control algorithm, called DCTCP, has been added by Marcel
Marek. Also, related to this change, the ECN support has been enhanced to be
customizable by congestion control algorithms.

6. Enhanced Interior Gateway Routing Protocol (EIGRP)

A new model of the routing protocol EIGRP with support for IPv4 and IPv6 has
been ported from ANSAINET 3.4.0 to INET. This is a large addition that adds a
lot of modules, some new network node types, and it also comes with several new
examples.

This model was contributed by Vladimir Vesely, Jan Bloudicek, Vit Rek, and Jan
Zavrel from the Brno University of Technology.

7. Packet flows and timing measurements

The concept of packet flows has been added to provide support for advanced timing
measurements. A packet flow is a logical classification of packets, identified
by a name, over the whole network and over the duration of the whole simulation.
Packets may have a PacketFlow tag attached to a region of data which describes
flow membership.

This feature allows making timing measurements between two or more arbitrary
end points in the network. The measurement can separate queueing time, processing
time, propagation time, transmission time, etc. on a per-bit basis efficiently.
It is also possible to collect all packet events (e.g queueing, processing,
transmission, propagation) and do arbitrary computations again on a per-bit
basis. This feature is provided by the FlowMeasurementStarter and FlowMeasurementRecorder
modules. The measurement data are collected on packets in various time tags
(e.g. QueueingTimeTag), which are updated by all related modules (e.g. PacketQueue).

8. Queueing model

The synchronous packet processing API has been extended with the support of
packet streaming between modules. This feature allows two modules within the
same network node to communicate synchronously (without sending asynchronous
messages) and process a packet bit by bit over a nonzero amount of time. The
related methods are called pushPacketStart(), pushPacketEnd(), pushPacketProgress(),
pullPacketStart(), pullPacketEnd(), and pullPacketProgress().

Several queueing model base classes have been refined and somewhat refactored
in order to better support the new feature. Also, many queueing model elements
have been extended with direct packet streaming support.

A few new queueing model elements have also been added that provide support
for the gating mechanism of Time-Sensitive Networking and for the preemption
mechanism of Ethernet. Some notable examples are PacketGate, PeriodicGate,
PreemptingServer, PreemptableStreamer, etc.

9. PCAP

The PCAP support has been extended with the more modern PCAPng file format.
This is the new default output file format for the PcapRecorder module. The
support for recording PCAP files has been extended to the network, network
node, and network interface level. The new format allows recording the network
interface and packet direction (outbound/inbound) for frames and also supports
mixing packet formats, making it possible to record the traffic of potentially
the whole network into a single file.

10. Socket processing

Several new modular socket command and packet processing components have been
added for Ethernet and IEEE 802.2 LLC protocols. There are modules for handling
the opening, configuration, and closing commands for sockets, others for maintaining
a table of open sockets (which can also be inspected in the runtime user interface),
and some for processing and duplicating the incoming packets for all open sockets.

11. Protocol elements library

Many small generic and reusable protocol implementation support components
have been added. These components include, among others, generic components for
packet fragmentation and defragmentation, aggregation and deaggregation, CRC and
FCS insertion and checking, and physical layer wired transmitter and receiver
models.

12. Visualizer

A new packet flow visualizer has been added, called PacketFlowCanvasVisualizer
and its OSG variant PacketFlowOsgVisualizer. They have also been included in
the integrated visualizer modules. The new visualizers display the packet flow
paths as polylines along with some basic statistics. This visualizer relies on
the newly introduced packet flow concept.

The spectrum and spectrogram visualization of the MediumCanvasVisualizer has
been further enhanced with better options and a more efficient implementation.

13. Printing formatted output

Support for producing formatted log output has been added with the new EV_FIELD
and other EV_ macros. The default str() method in several Packet API classes
(e.g. Packet, various Chunks, Signal) have been enhanced to provide better
textual representation in the log.

The IPrintableObject C++ interface has been moved to the common folder. It
has also been extended with template support for printing objects without
having to repeat a lot of code and with using the default shift operator.

14. Features (.oppfeatures):

Several new OMNeT++ features have been added and some old features have been
split. These changes can be found in the IDE on the INET project properties:

• Clock
• Clock examples
• EIGRP routing
• EIGRP routing examples
• Emulation showcase
• IEEE 802.1ae
• IEEE 802.1q
• IEEE 802.2
• Internet protocol examples
• Open MP support
• Physical layer common
• Physical layer wired common
• Physical layer wireless common
• Protocol support
• Protocol tutorial
• Queueing library
• Queueing tutorial
• Unit disk radio
• Virtual interface
• Visualization OSG (3D)
• Visualization OSG (3D) showcases
• Visualization canvas (2D)
• Visualization canvas (2D) showcases
• Visualization common
• Wireless noise source

15. Examples

Several new examples have been added:

• clock drift
• Ethernet frame preemption
• Ethernet cut-through switching
• gating mechanism in Ethernet queueing
• modular Ethernet interface
• DCTCP congestion algorithm
• timing measurement along packet flows
• video streaming using network emulation
• signal power spectral density visualization

A few examples have been substantially changed to follow other changes:

• IEEE 802.1d
• virtual LAN

16. Testing

The fingerprint testing script has been extended with support for computing
multiple different fingerprints and a separate fingerprint calculator option.
The updated fingerprint tests contain four separate fingerprint values for
each example simulation:

• detailed model behavior
• complete network byte order packet data and timing at the network level
• complete network packet length and timing at the network level
• graphics in the runtime user interface.

Several new fingerprint, module, and unit tests have been added for the new
clock model, the protocol support modules, and the new formatted output.

17. Documentation

A new chapter about the newly added clock model has been added to the User's
Guide. The Collecting Results chapter has been completed and also extended
with a new section that describes how to do timing measurements along packet
flows. The queueing model and emulation chapters of the User's Guide has been
updated to reflect the changes in the queueing model of this release.

18. Bug fixes

A bug in the TCP Nagle's algorithm has been fixed, see #558.

A bug related to using the latest avcodec libraries (e.g. Ubuntu 20.10) in
the VoIP streaming applications has been fixed.

The C++ numeric type selection/promotion support for unit specific binary
operators has been fixed to follow what C++ does with the standard types.

19. Code cleanup and formatting

The whole source tree has been cleaned up with respect to C++ code formatting,
indentation, header guards, whitespace, and so on. Moreover, all copyright
headers in the C++ source files have been updated to use the official GPL-2
and GPL-3 formats as suggested.

All markers (TBD, XXX, etc.) in the source code has been unified to use one
of the standard TODO, FIXME, and KLUDGE markers. These have well-defined
meaning and it makes finding them easier.

20. Other notable changes

• A few new multi-dimensional mathematical functions have been added that can
  be useful to represent signal power density in the physical layer. These new
  functions are the Rasterized2DFunction, PeriodicallyInterpolated2DFunction,
  LeftCurryingFunction and RightCurryingFunction.

• In several places the std::min and std::max calls have been replaced with
  inet::minnan, inet::maxnan that properly propagate NaN values.

• The IProtocolRegistrationListener interfaces have been extended to allow
  registering a protocol group or any protocol as a fallback for a service or
  protocol available at a module gate.

• A new OperationalMixin template base class has been added that allows using
  the same behavior as the OperationBase where it was not applicable due to
  it having a specific base class.

• Several network base NED modules (NetworkBase, WiredNetworkBase, WirelessNetworkBase,
  Ieee80211NetworkBase) have been added to support easier use of the typical
  configurator, radio medium, visualizer, etc. network level submodules.

• The module initialization stages have been extended with INITSTAGE_CLOCK and
  INITSTAGE_NETWORK_LAYER_PROTOCOLS.

• Several automatic weak shared module pointers have been added to so simplify
  direct cross module communication via C++ method calls. The added cl...