Merge branch 'release/5.0.0'

README.md

@@ -16,6 +16,7 @@ Thanks to the main contributors:
 * Luciano Jerez Chaves
 * Vítor Marge Eichemberger
 * Islene Calciolari Garcia
+* Arthur Boeacht Mazzi
 * *"Your name here"*
 
 # Contact #

RELEASE_NOTES

@@ -5,6 +5,44 @@ OFSwitch13 release notes
 This file contains OFSwitch13 release notes (most recent releases first).
 
 
+Release 5.0.0 (Dec 19, 2021)
+============================
+
+- BE AWARE THAT this release brings incompatible API changes in respect to
+  prior OFSwitch13 versions.
+
+- Refactoring OFSwitch13Controller::Dpctl* () methods:
+  * The DpctlExecute () method has no more overloaded definitions. The target
+    switch (first parameter) must be the switch's datapath IP. Previous
+    signature using the Ptr<const RemoteSwitch> swtch pointer was removed.
+    Users can fix compilation errors by just using swtch->GetDpId () when
+    invoking DpctlExecute ();
+  * The DpctlSchedule () method was deprecated in favor of DpctlExecute ().
+    When the switch is not connected to the controller, the DpctlExecute ()
+    will automatically schedule the command for execution just after the
+    handshake procedure. This is particularly useful for executing dpctl
+    commands when creating the topology, before invoking Simulator::Run ().
+
+- Creating a new OFSwitch13Device::TableDrop trace source to notify unmatched
+  packets dropped by flow tables without table-miss entries. A new TabDrps
+  column was also inserted in the OFSwitch13StatsCalculator output file.
+
+- Updating OFSwitch13Queue for compatibility with the ns-3 queue API.
+
+- Updating the ofswitch13-external-controller example with a custom topology
+  configuration. This example was tested with the Ryu controller.
+
+- Fixing incorrect Ethernet 802.3 packet header parsing.
+
+- Fixing errors when compiling the project with gcc 9.3.0 in Ubuntu 20.04.
+
+- This version is compatible with ofsoftswitch13 library release v5.0.x and
+  ns-3 version 3.30 (including patch). There is no backward compatibility with
+  older ns-3 versions.
+
+- Compilation was tested in Debian 8, Ubuntu 18.04 LTS, and Ubuntu 20.04 LTS.
+
+
 Release 4.0.0 (Apr 02, 2019)
 ============================
 
@@ -89,9 +127,11 @@ Release 4.0.0 (Apr 02, 2019)
 - Merging new commits from the CPqD ofsoftswitch13 library.
 
 - This version is compatible with ofsoftswitch13 library release v4.0.x and
-  ns-3 versions 3.28 or later (including patches). There is no backward
+  ns-3 versions 3.28 and 3.29 (including patches). There is no backward
   compatibility with older ns-3 versions.
 
+- Compilation was tested in Ubuntu 18.04 LTS.
+
 
 Release 3.3.0 (Sep 29, 2018)
 ============================

doc/source/conf.py

@@ -41,16 +41,16 @@
 
 # General information about the project.
 project = u'OFSwitch13'
-copyright = u'2019 Computer Networks Laboratory'
+copyright = u'2021 Computer Networks Laboratory'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '4.0.0'
+version = '5.0.0'
 # The full version, including alpha/beta/rc tags.
-release = '4.0.0'
+release = '5.0.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/source/ofswitch13-description.rst

@@ -107,7 +107,7 @@ Packets coming back from the library for output action are sent to the OpenFlow
 queue provided by the module. An OpenFlow switch provides limited QoS support
 employing a simple queuing mechanism, where each port can have one or more
 queues attached to it. Packets sent to a specific queue are treated according
-to that queue’s configuration. Queue configuration takes place outside the
+to that queue's configuration. Queue configuration takes place outside the
 OpenFlow protocol. The ``OFSwitch13Queue`` abstract base class implements the
 queue interface, extending the |ns3| ``Queue<Packet>`` class to allow
 compatibility with the ``CsmaNetDevice`` used within ``OFSwitch13Port`` objects
@@ -359,13 +359,12 @@ receive callback into |ns3| source code, available under
 the receive callbacks inclusion, and an optional *doc* patch that can be used
 for including the |ofs13| when compiling Doxygen and Sphinx documentation.
 
-The current |ofs13| stable version is 4.0.0. This version is compatible with
-|ns3| version 3.28 or later, and will not compile with older |ns3|
-versions. If you need to use another |ns3| release, you can check the |ofs13|
-RELEASE_NOTES file for previous |ofs13| releases and their |ns3| version
-compatibility, but keep in mind that old releases may have known bugs and an
-old API. It is strongly recommended to use the latest module version for better
-results.
+The current |ofs13| stable version is 5.0.0. This version is compatible with
+|ns3| version 3.30, and will not compile with older |ns3| versions. If you need
+to use another |ns3| release, you can check the |ofs13| RELEASE_NOTES file for
+previous |ofs13| releases and their |ns3| version compatibility, but keep in
+mind that old releases may have known bugs and an old API. It is strongly
+recommended to use the latest module version for better results.
 
 References
 ==========
@@ -394,7 +393,7 @@ References
 
 .. [Risso2006] Fulvio Risso and Mario Baldi. `"Netpdl: An extensible xml-based language
    for packet header description" <http://dx.doi.org/10.1016/j.comnet.2005.05.029>`_.
-   Computer Networks, 50(5):688–706, 2006.
+   Computer Networks, 50(5):688-706, 2006.
 
 .. [Chaves2016] Luciano J. Chaves, Islene C. Garcia, and Edmundo R. M. Madeira.
    `"OFSwitch13: Enhancing ns-3 with OpenFlow 1.3 support"

doc/source/ofswitch13-usage.rst

@@ -16,33 +16,32 @@ Building the Module
 The |ofs13| module was designed as an interface for interconnecting the |ns3|
 simulator to the |ofslib| software switch compiled as a library. Follow the
 instructions below to compile and link the |ns3| simulator to the |ofslib|
-library. *These instructions were tested on Debian 8, Ubuntu 16.04 LTS, and
-Ubuntu 18.04 LTS. Other distributions or versions may require different steps,
+library. *These instructions were tested on Debian 8, Ubuntu 18.04.6 LTS, and
+Ubuntu 20.04.3 LTS. Other distributions or versions may require different steps,
 especially regarding library compilation.*
 
 Before starting
 ###############
 
 Before starting, ensure you have the following packages installed on your
-system [#f1]_:
+system:
 
 .. code-block:: bash
 
   $ sudo apt-get install build-essential gcc g++ python git mercurial unzip cmake
-  $ sudo apt-get install pkg-config autoconf libtool libboost-dev
-
-.. [#f1] The *NetBee* library dependence was removed in |ofs13|
-         release version 4.0.0.
+  $ sudo apt-get install pkg-config autoconf automake libtool libboost-dev
 
 Compiling the code
 ##################
 
-Download a recent stable |ns3| code into your machine (we are using the
-mercurial repository for ns-3.29):
+Clone the |ns3| source code repository into your machine and checkout a stable
+version (we are using the ns-3.30):
 
 .. code-block:: bash
 
-  $ hg clone http://code.nsnam.org/ns-3.29
+  $ git clone https://gitlab.com/nsnam/ns-3-dev.git
+  $ cd ns-3-dev
+  $ git checkout -b ns-3.30 ns-3.30
 
 Download the |ofs13| code into the ``src/`` folder (starting with ns-3.28, you
 can also download the code into the new ``contrib/`` folder). This procedure
@@ -51,13 +50,13 @@ will recursively download the |ofslib| code into the
 
 .. code-block:: bash
 
-  $ cd ns-3.29/src
+  $ cd src/
   $ git clone --recurse-submodules https://github.com/ljerezchaves/ofswitch13.git
 
-Update the code to the desired release version (we are using release 4.0.0,
-which is compatible with ns-3.28 or later) [#f2]_:
+Update the code to the desired release version (we are using the latest release
+5.0.0, which is compatible with ns-3.30) [#f1]_:
 
-.. [#f2] For |ofs13| release versions prior to 3.2.2 (when no submodule
+.. [#f1] For |ofs13| release versions prior to 3.2.2 (when no submodule
          dependence was configured in the git repository), the |ofslib| code
          will not automatically update to the correct version. In this case,
          you must manually updated the |ofslib| code to the proper version
@@ -67,7 +66,7 @@ which is compatible with ns-3.28 or later) [#f2]_:
 .. code-block:: bash
 
   $ cd ofswitch13
-  $ git checkout 4.0.0 && git submodule update --recursive
+  $ git checkout 5.0.0 && git submodule update --recursive
 
 Now it is time to compile the |ofslib| as a static library. Configure and
 build the library (don't forget to add the ``--enable-ns3-lib`` during
@@ -89,8 +88,8 @@ correct |ns3| version):
 .. code-block:: bash
 
   $ cd ../../../../
-  $ patch -p1 < src/ofswitch13/utils/ofswitch13-src-3_29.patch
-  $ patch -p1 < src/ofswitch13/utils/ofswitch13-doc-3_29.patch
+  $ patch -p1 < src/ofswitch13/utils/ofswitch13-src-3_30.patch
+  $ patch -p1 < src/ofswitch13/utils/ofswitch13-doc-3_30.patch
 
 The ``src`` patch creates the new OpenFlow receive callback at
 ``CsmaNetDevice`` and ``VirtualNetDevice``, allowing OpenFlow switch to get raw
@@ -413,8 +412,9 @@ the following datapath metrics on the output file:
 #. [``LoaUsag``] Average CPU processing capacity usage (percent);
 #. [``Packets``] Packets processed by the pipeline in the last interval;
 #. [``DlyUsec``] EWMA pipeline lookup delay for packet processing (usecs);
-#. [``LoaDrop``] Packets dropped by capacity overloaded in the last interval;
+#. [``LoaDrps``] Packets dropped by capacity overloaded in the last interval;
 #. [``MetDrps``] Packets dropped by meter bands in the last interval;
+#. [``TabDrps``] Unmatched packets dropped by flow tables in the last interval;
 #. [``FloMods``] Flow-mod operations executed in the last interval;
 #. [``MetMods``] Meter-mod operations executed in the last interval;
 #. [``GroMods``] Group-mod operations executed in the last interval;
@@ -560,10 +560,11 @@ switch. With this tool, it is possible to add flows to the flow table, query
 for switch features and status, and change other configurations. The
 ``DpctlExecute()`` function can be used by derived controllers to convert a
 variety of ``dpctl`` commands into OpenFlow messages and send it to the target
-switch. There's also the ``DpctlSchedule()`` variant, which can be used to
-schedule commands to be executed just after the handshake procedure between the
-controller and the switch (this can be useful for scheduling commands during
-the topology creation, before the simulation start).
+switch. If the switch is not connected to the controller yet, this method will
+automatically schedule the commands for execution just after the handshake
+procedure between the controller and the switch. This is particularly useful
+for executing dpctl commands when creating the topology, before invoking
+``Simulator::Run ()``.
 
 Check the `utility documentation
 <https://github.com/CPqD/ofsoftswitch13/wiki/Dpctl-Documentation>`_ for details
@@ -651,10 +652,8 @@ controller is running on the local machine at port 6653 (the helper
 automatically sets the IP address). Users can modify the local port number
 setting the ``OFSwitch13ExternalHelper::Port`` attribute.
 
-This example was tested with the Floodlight 1.2 controller
-(http://www.projectfloodlight.org) running on the local machine. Consistent
-behavior was observed once sufficient time elapses (say 3 to 5 minutes) between
-any two executions.
+This example was tested with the Ryu controller (https://ryu-sdn.org) running
+on the local machine.
 
 Examples
 ========