INET Framework for the OMNeT++ discrete event simulator
This is a minor patch release of INET 4.5 containing several fixes since the 4.5.1 version.
This patch release resolves a Windows-specific linker error (missing symbols) that occurred when trying to build model frameworks based on INET. It was fixed by adding INET_API annotations where they were missing.
This is a new minor stable release within the INET 4.x branch. The main feature of this release is the ability to concurrently run multiple simulations within the same process (requires OMNeT++ 7.0 preview 2 or later), along with an extended Ethernet cut-through switching functionality.
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 or later.
For a complete list of all added, removed, and changed folders, NED modules, packet chunks, packet tags, statistics, C++ classes, and signals please refer to the ChangeLog file in the src folder.
Notable backward incompatible changes are the following:
Ethernet cut-through switching
The Ethernet cut-through switching implementation has been extended to work with all TSN traffic filtering and TSN traffic shaping methods. Previously it was not possible to combine these features. For a packet that was forwarded using cut-through switching, the otherwise configured traffic shaping and traffic filtering methods in the switch were completely bypassed.
The new implementation allows processing the incomplete packet in the switch while the packet buffer is being filled up by the incoming interface. All Ethernet headers are available and the packet length is known, so traffic filtering and traffic shaping can take place the same way it does for store-and-forward packets.
For more information, see the showcase at: https://inet.omnetpp.org/docs/showcases/tsn/cutthroughswitching/doc/index.html
This change doesn't require the modification of simulation models, but it may significantly change the statistical results of simulations that use traffic filtering or traffic shaping with cut-through switching.
Clock model
The RandomDriftOscillator module has been refactored to have a more useful parameterization. The module has an initial random drift rate parameter that represents the inaccuracy of device production. Besides, the module uses a random walk process for an additional drift rate change that represents the voltage and temperature dependent inaccuracy of the device.
Please note that the gPTP time synchronization change (described later) makes the RandomDriftOscillator module more useful than the previously widely used ConstantDriftOscillator module because the first time synchronization can now completely eliminate the effects of a constant drift.
This change requires the modification of simulation models that use the RandomDriftOscillator module because the parameterization has been changed.
Time-Sensitive Networking
The credit-based shaper has been changed to stop accumulating credits when the corresponding time-aware shaper (same traffic category) transmission gate is closed. Additionally, the credit-based shaper can also stop accumulating credits when the implicit guard band of the time-aware shaper is active.
The time-aware shaper already provides an implicit guard band before each time a gate is closing according to the gate schedule. This guard band is defined by the following rule: no packet is allowed to pass the gate unless the packet can be transmitted completely before the gate closes.
This change doesn't require the modification of simulation models, but it may significantly change the statistical results of simulations that use both the credit-based shaper and the time-aware shaper for the same traffic category.
Running simulations concurrently (experimental)
INET has been changed to support running multiple simulations concurrently within a single process. Previously this was not possible, partly because OMNeT++ itself didn't support concurrent simulation execution, but also because INET contained several global variables. Please note that this is an experimental feature in both OMNeT++ and INET.
In order to provide this feature, global variables have been either eliminated, or replaced with simulation shared variables, or marked with the 'const' qualifier signifying that their values cannot be changed, or marked with the 'OPP_THREAD_LOCAL' macro to store their values separately for each thread.
This change may require the modification of simulation models if they directly access some of the modified global variables. Additionally, simulation models that have their own global variables must be updated to support running simulations concurrently.
This feature requires using OMNeT++ 7.0 preview 2 or later. For more information, see the https://omnetpp.org/download/preview page.
Notable backward compatible changes are the following:
Clock model
The clock model has been extended with an oscillator compensation parameter. This parameter can be used to reduce the effect of an inaccurate oscillator on clock time. Time synchronization mechanisms can often estimate the clock speed differences and set this parameter to reduce the clock time difference that would arise over time from clocks running at different speeds.
IEEE 802.1-AS (gPTP)
The gPTP time synchronization protocol has been extended to also compensate for a drifting oscillator. Previously time synchronization only set the clock time but it didn't account for the clock speed differences between the master and the slave clock.
This change can result in an order of magnitude smaller maximum clock time difference between the master and slave clocks over the period of two time synchronization events.
Queueing model
The behavior of complex queueing models depends among others on the execution order of timers. Previously the scheduling priority for such timers were not configurable, so the user could not control the order of their execution. This limitation could prevent getting the desired behavior from the combination of certain modules. For example, a packet server may need to wait for all gates to open or close before using the scheduler to process the next packet at the same simulation time.
Several queueing modules have been extended with additional parameters to control the scheduling priority of timers. This gives fine grained control over the order of timer events, that affects how the modules can be combined into more complex behavior.
Additionally, the active packet source and packet sink modules that generate or consume traffic periodically have been extended with initial offset parameters.
IEEE 802.11
The 802.11 model contains several policy modules that can be replaced by the user to customize the model behavior. For example, the fragmentation policy decides when and how frames should be fragmented. Unfortunately, previously several policy modules were not replaceable using only INI file parameter assignments. This limitation has been fixed.
All policy submodules have been replaced with submodules having parameterized module types and corresponding module interfaces, making it easy to replace policy submodules using only INI files. Additionally, the documentation of several 802.11 modules and module interfaces have been refined.
Protocol element
The generic protocol elements library have been extended with a protocol independent cut-through implementation. The new modules provide an example of how this mechanism can be implemented and allows teaching and researching this topic.
Notable bug fixes and other changes
This is a minor bugfix release, mostly fixing linker errors on Windows for projects depending on INET.
This is a new minor stable release of the INET 4.x branch. The highlight of this release is the implementation of several Time-Sensitive Networking (TSN) features. Also, INET is now fully licensed under LGPL (see later for details).
Experimental Python support has been added for running simulations concurrently and optionally on an SSH cluster. This is mostly useful for running parameter studies, automated testing and optimizing parameters.
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 or later.
For a complete list of all added, removed, and changed folders, NED modules, packet chunks, packet tags, statistics, C++ classes, and signals please refer to the ChangeLog file in the src folder.
Notable backward incompatible changes are the following:
Network interfaces
The queue modules are placed back inside the network interface compound module as direct submodules, reverting back a previous change in INET 4.2 version.
In the INET 3.x versions, the network interface queue submodules were part of the network interface compound modules, and they were directly connected to other submodules within the network interface using connections and gates. This structure was not ideal when a packet could be immediately served by the MAC layer, because the queue recorded a zero simulation time increase in the queue length. The problem was especially difficult to get around when compound packet queues were used. In order to fix this issue, we decided to move the MAC layer queues (as simple submodules) under the MAC layer compound module. Having this structure allowed the MAC modules to completely bypass the queue modules if the queueing of the packet was not necessary.
Unfortunately, this change turned out to be bad for various reasons. The most important is that the queue needs to communicate with the module it is connected to. For example, a complex compound queue which can delay packets needs to notify the connected module, in this case of the MAC module, when a packet becomes ready to be pulled. So once again, we decided to move the queues back where they were before, outside of the MAC modules. Of course, the original queue length hazard problem still had to be solved, but as it turned out that problem had to be solved anyway.
This change may require the modification of simulation models, because the queue module parameter assignments (referring to the old module positions) may have no effect any more. This change can break existing simulations silently producing different results.
Network nodes
The addition of Time-Sensitive Networking features required to further extend the network node architecture by adding a separate bridging layer compound module between the L2 and L3 layers. This new module is optional and it can be present in both Ethernet switches and standard hosts.
The VLAN policy module has been moved into the new bridging layer in order to correctly combine with the TSN stream features.
This change requires updating the VLAN policy module parameter assignments, otherwise simulations may silently produce different results.
Packet filter expressions
Several INET modules (packet filters, packet classifiers, packet schedulers, various visualizers, etc.) use packet filter expressions to differentiate packets. In earlier INET versions, the packet filter expressions were limited to only access certain parts of the packet: name, length, kind, one protocol header at a time. Perhaps the most important such limitation was that it was not really possible to combine conditions for different protocol headers.
The new packet filter expression syntax is more general while it retains the often useful simple pattern matching mechanism for packet names. The generic NED expression syntax supports the more complicated cases, where filtering for packet content and packet meta-data is needed. It also allows the combination of conditions for different protocol headers that was not possible before.
This change may require the modification of simulation models, because packet filter expressions are not backward compatible. This change can break existing simulations silently producing different results.
The User's Guide contains a separate chapter describing the packet filter expressions with several examples.
Signals and statistics
Several signals and statistics have been renamed and several others are split into multiple different ones. This change was necessary in order to have a more coherent naming and also to have more fine-grained results. The most important affected modules are the flow measurement recorder and the queueing model elements. See the ChangeLog file under the src folder for more details.
This change may require the modification of analysis files, because the results may be different. This change can break existing analysis files silently producing different diagrams.
Notable backward compatible changes are the following:
Time-Sensitive Networking
Several new modules have been added to provide new features of Time-Sensitive Networking.
An existing implementation of the gPTP time synchronization protocol has been ported and merged into the INET framework. The protocol has been extended with the support of multiple time synchronization domains. The clock model has been extended to allow changing the active time domain to simulate failover. Please note that the actual mechanism that detects the time synchronization failure is not yet provided, so right now only manual failover can be simulated.
The new traffic shaping feature provides modules for time-aware shaping, credit-based shaping, asynchronous shaping, and also various combinations of them. These modules are usually part of the network interfaces in the complex queueing mechanism of Time-Sensitive Networking.
The per-stream filtering feature provides modules for token-bucket-based traffic metering, transmission eligibility time calculation, and a form of statistical traffic metering. These modules are usually part of the ingress traffic filter of the bridging layer.
The frame replication and elimination feature provides modules for stream identification, stream splitting/merging, and stream encoding/decoding as part of the bridging layer.
All of the above TSN features are described in detail in the User's Guide and the respective NED files. Besides, there are several new showcases that demonstrate the individual TSN features and a few combinations.
Ethernet model
The old Ethernet (non-TSN) network interface infrastructure has been changed.
The FCS protocol header insertion has been moved from the Ethernet MAC layer module to the Ethernet protocol layer module. The Ethernet protocol layer was already separated from the network interface and moved to separate module in network nodes in the previous INET version. This change makes it possible to use the old and the new TSN capable Ethernet models interchangeably.
Link-layer network-wide automatic configuration
Several new network-wide automatic configurator modules have been added.
One such network configurator module configures all MAC address tables (aka. MAC forwarding information databases) automatically in all Ethernet switches by discovering the network topology and finding the shortest paths between all network node pairs. This configurator can be used instead of manually configuring the Ethernet switches or instead of using an automatic spanning tree protocol such as STP or RSTP.
There are several newly added gate scheduling configurators. They can configure the gate schedules of time-aware shapers for all traffic categories in all network interfaces of all network nodes. The resulting schedules are such that the required end-to-end latency and jitter limits are met for all configured streams. The following gate scheduling configurators are available:
Another network level configurator that is used in Time-Sensitive Networking is the stream redundancy configurator. This module configures the stream merger and stream splitter modules in all network nodes such that all redundant traffic paths are used. The redundant streams make the network resilient to various node and/or link failures.
Finally, there is the so called failure protection configurator that is used in Time-Sensitive Networking. This module configures the network using the stream redundancy, and optionally the gate scheduling configurators, to meet the complex node and/or link failure protection requirements of all traffic streams by figuring out the necessary redundant paths.
Processing delay
A simple packet processing delay mechanism has been added to the TSN network interface and also to the bridging layer. This allows one to simulate a very simple packet processing delay for incoming and outgoing packets, and also for packets that are forwarded by the bridging layer.
Queueing model and protocol elements
The queueing model have been extended with various token bucket meters and classifiers. The model also allows one to create chained token buckets where the overflowing tokens go to another bucket. Meters simply attach meta data to packets while classifiers push packets to different gates, both based on the state of the token buckets. These modules are currently used in TSN per-stream traffic filtering.
Several new generic protocol support elements have been added. There are several new modules, currently used in TSN frame replication, for stream identification, stream splitting/merging, stream encoding/decoding. There are a few other new modules, currently used in TSN asynchronous shaping, for transmission eligibility time metering, filtering, and queueing.
A new interactive packet gate has been added that allows the user to directly control the gate's open/closed state from Qtenv and experiment interactively.
Please note that in OMNeT++ 6.0 version of Qtenv the simulation may stop more than once in the same event. This is called pause points, and it happens every time a packet is passed from one module to another using to queueing model elements, the protocol support modules, or the INET packet processing API.
Applications
A new simple out-of-band clock synchronizer application has been added. This module can be used to synchronize clocks in the whole network without actually sending any time synchronization packets.
New IEEE 802.2 LLC protocol-specific applications have been added. These allow to send IEEE 802.2 LLC packets directly from the application layer.
Packet chunks, tags and serializers
New packet chunks have been added for the IEEE 802.1r protocol.
Several new packet tags have been added: PcpReq/PcpInd, StreamReq/StreamInd, SequenceNumberReq/SequenceNumberInd, ResidenceTimeTag, EligibilityTimeTag, CreditGateTag, EnapsulationProtocolReq/EnapsulationProtocolInd. The purpose and usage of these tags can be found at the relevant modules.
New packet chunk serializers have been added for the IEEE 802.1as and IEEE 802.1r tags. This allows recording of PCAP traces in TSN simulations.
Signals and statistics
Several new signals and statistics have been added. The most notable newly added statistics are the measurement of the transmission duration, the signal propagation time, and the packet residence time. The latter being the duration the packet spends in individual network nodes. For a complete list of signal and statistic changes see the ChangeLog in the src folder.
Project features
Several new project features have been added. The IEEE 802.1as and the IEEE 802.1r features are used in Time-Sensitive Networking. Another feature is added for the Microsoft Z3 SAT-solver-based gate schedule configurator, it requires the installation of an external library.
Finally, there is a new feature for an automatic simulation model self documenter. This feature allows one to observe the simulations while they are running and to collect several categories of information about what the simulation modules are doing. The result can be automatically included in the generated NED documentation.
Visualization
New visualizers have been added that display some aspects of the Time-Sensitive Networking configuration. One visualizer displays the gate schedule for the time-aware shapers for multiple network interfaces in multiple network nodes. Another visualizer displays the redundant traffic paths configured in the stream splitting and stream merging components.
Several new Time-Sensitive Networking specific examples have been added under the showcases/tsn folder. The new examples cover the topic of time synchronization, traffic shaping, gate scheduling, per-stream filtering, frame replication, frame preemption, cut-through switching, and several combinations of these features.
Another set of new examples, found under the showcases/measurement folder, have been added to demonstrate how to do some widely used communication network measurements. There are examples for datarate, throughput, utilization, end-to-end delay, jitter, queueing time, residence time, transmission time, propagation time and various packet-flow-specific measurements.
A new experimental Python package has been added that allows the automation of running and testing multiple simulations concurrently and also optionally on an SSH cluster. The automated testing covers smoke, fingerprint, sanitizer, statistical, and several other tests. The inet_python_repl shell script starts the Python interpreter and loads the required OMNeT++/INET Python packages. The main entry points are run_simulations, run_smoke_tests, run_fingerprint_tests, and several other run_* functions, there's also an optimize_simulation_parameters function. There are also shell scripts (called inet_run_*) that can be used in the simulation folders directly.
This package will be officially supported in the next OMNeT++/INET release.
The User's Guide has been extended with new chapters. One new chapter is about the new Time-Sensitive Networking features. It gives an overview of the available modules and how to use them. Another new chapter is about the new packet filter expression syntax. It gives a brief description of the syntax and provides several examples.
The whole INET Framework has been re-licensed under the LGPL. The vast majority of INET components were already licensed under LGPL. All other components that were not, and where we could not reach the original authors, or they did not agree with the new license, have been moved into a separate INET-GPL project.
As of today, the new INET-GPL project (https://github.com/inet-framework/inet-gpl) contains the following old INET components:
All source files have been changed with respect to license headers. The longer license header variants have been replaced with a standard one-liner SPX license reference.
Compatibility fixes for OMNeT++ 6.0. (Preview and RC versions are NOT supported.)
Several minor bugfixes plus some compatibility fixes for OMNeT++ 6.0. OMNeT++ 6.0 Preview and RC versions are NOT supported.
Contains compatibility fixes for OMNeT++ 6.0. Requires OMNeT++ 5.7 or 6.0
Several minor bugfix plus some compatibility fixes for OMNeT++ 6.0. Preview and RC versions are NOT supported.
findInterfaceByAddress() and findHostWithAddress(), uses NetworkInterface::hasNetworkAddress()
findInterfaceByAddress and isLocalAddress in RoutingTablessimtime_t fields to -1 instead of NaN, because double NaN cannot be converted to simtime_t.init() to new init(Context* ctx) in ResultFilters.uniform(a,b) now expecting a<=b
Contains compatibility fixes for OMNeT++ 6.0. Requires OMNeT++ 5.7 or 6.0rc1.