neddoc added to various modules

using llm

LLDPAgent documented

HF doc

hyperflowagent docu

IControllerApp

OF_Controller etc doc

AbstractTCPControllerApp

flowtable

Author: avarga

src/openflow/controllerApps/AbstractTCPControllerApp.ned

@@ -15,15 +15,33 @@
 // along with this program; if not, see <http://www.gnu.org/licenses/>.
 //
 
-
 package openflow.controllerApps;
 
 import inet.applications.contract.IApp;
 
-
 //
-// Template for TCP applications. It shows what gates a TCP app
-// needs, to be able to be used in ~StandardHost etc.
+// AbstractTCPControllerApp is a base class for OpenFlow controller applications that need
+// to communicate over TCP in addition to interacting with the OpenFlow controller.
+//
+// This module extends AbstractControllerApp (which provides the basic controller application
+// functionality) and implements the INET IApp interface (which provides TCP socket functionality).
+// It serves as a bridge between the OpenFlow controller architecture and the INET TCP/IP stack.
+//
+// Key features of AbstractTCPControllerApp:
+//
+// 1. TCP Socket Management: Provides functionality for creating and managing TCP sockets,
+//    allowing controller applications to establish connections with external entities.
+//
+// 2. Message Queue Processing: Implements a message queue with configurable service time
+//    to simulate processing delay for incoming messages. Messages are processed sequentially
+//    with the specified service time between them.
+//
+// 3. Statistics Collection: Collects and records statistics about queue size, waiting time,
+//    and packets processed per second, which can be used for performance analysis.
+//
+// This class is used as a base for controller applications that need to communicate with
+// external systems, such as the HyperFlowAgent which connects to a HyperFlowSynchronizer
+// to enable distributed controller functionality.
 //
 simple AbstractTCPControllerApp like IControllerApp, IApp
 {
@@ -34,12 +52,15 @@ simple AbstractTCPControllerApp like IControllerApp, IApp
         @statistic[queueSize](title="QueueSize"; record=vector?,stats; interpolationmode=none);
         @signal[waitingTime](type="simtime_t");
         @statistic[waitingTime](title="WaitingTime"; record=vector?,stats?; interpolationmode=none);
+
+        // Processing time for each message (used to simulate processing delay).
+        // Messages are processed sequentially with this delay between them.
         double serviceTime @unit("s") = default(0s);
+
+        // Priority of flow entries installed by this application (higher values are matched first)
         int priority = default(1);
 
     gates:
         input socketIn @labels(TcpCommand/up);
         output socketOut @labels(TcpCommand/down);
 }
-
-

src/openflow/controllerApps/IControllerApp.ned

@@ -19,8 +19,28 @@
 package openflow.controllerApps;
 
 //
-// Template for TCP applications. It shows what gates a TCP app
-// needs, to be able to be used in ~StandardHost etc.
+// IControllerApp is the base interface for all OpenFlow controller applications in the
+// openflow simulation model. It defines the common parameters and signals that all
+// controller applications must implement.
+//
+// Controller applications are modules that implement specific control logic for an OpenFlow
+// network. They run within an OpenFlow controller and make decisions about how packets should
+// be handled by OpenFlow switches. Examples include learning switches, routing applications,
+// load balancers, and security applications.
+//
+// The controller application architecture follows a modular design where multiple applications
+// can be installed in a single controller, each handling different aspects of network control.
+// Applications receive events from the controller (like packet-in messages from switches),
+// process them according to their logic, and respond with appropriate actions (like sending
+// flow modification messages to install flow entries in switches).
+//
+// Signal Definitions:
+// - PacketIn: Emitted when a packet-in message is received from a switch
+// - PacketOut: Emitted when a packet-out message is sent to a switch
+// - PacketFeatureRequest: Emitted when a feature request message is sent to a switch
+// - PacketFeatureReply: Emitted when a feature reply message is received from a switch
+// - PacketExperimenter: Emitted for experimenter (vendor) messages
+// - Booted: Emitted when the controller has completed initialization
 //
 moduleinterface IControllerApp
 {
@@ -33,7 +53,10 @@ moduleinterface IControllerApp
         @signal[PacketExperimenter];
         @signal[Booted];
         @display("i=block/app");
+
+        // Priority of flow entries installed by this application (higher values are matched first)
+        // In OpenFlow, when multiple flow entries match a packet, the entry with the highest
+        // priority is used. This parameter determines the priority value set in flow modification
+        // messages sent by this controller application.
         int priority;
 }
-
-

src/openflow/controllerApps/LLDPAgent.ned

@@ -15,19 +15,47 @@
 
 package openflow.controllerApps;
 
+//
+// The LLDPAgent is a controller application responsible for network topology discovery
+// using the Link Layer Discovery Protocol (LLDP). It is deployed exclusively on the
+// controller side, not on switches.
+//
+// The module periodically sends LLDP packets to all switches using OpenFlow packet-out
+// messages. Each switch forwards these LLDP packets on all its ports. When a switch
+// receives an LLDP packet on one of its ports, it forwards it to the controller via
+// a packet-in message. The LLDPAgent uses these packet-in messages to build a graph
+// of the network topology.
+//
+// The topology information is stored in an LLDPMibGraph, which represents the network
+// as a graph where switches and hosts are vertices and links are edges. This graph
+// is used by other controller applications like LLDPBalancedMinHop to compute paths
+// between hosts.
+//
+// The LLDPAgent installs flow entries in switches to forward LLDP packets to the
+// controller. It also handles the expiration of topology information based on the
+// configured timeout.
+//
 simple LLDPAgent like IControllerApp
 {
     parameters:
         @class(openflow::LLDPAgent);
         @display("i=block/app");
 
-        //default value cisco
+        // How often to send LLDP packets for topology discovery (default value from Cisco)
         double pollInterval @unit("s") = default(30s);
 
-        //default value cisco
+        // How long topology information is valid before expiring (default value from Cisco)
         double timeOut @unit("s") = default(120s);
+
+        // Hard timeout for flow entries (0 means no hard timeout)
         int flowModHardTimeOut = default(0);
+
+        // Idle timeout for flow entries (how long a flow entry remains if not used)
         int flowModIdleTimeOut = default(60);
+
+        // Whether to print the topology graph to the console
         bool printMibGraph = default(false);
+
+        // Priority of flow entries installed by this application (higher values are matched first)
         int priority = default(1);
 }

src/openflow/hyperflow/HF_ARPResponder.ned

@@ -2,7 +2,41 @@
 package openflow.hyperflow;
 import openflow.controllerApps.IControllerApp;
 
-
+//
+// The HF_ARPResponder is a specialized controller application that extends the basic ARPResponder
+// functionality to work within the HyperFlow distributed controller architecture. (The HF prefix
+// stands for HyperFlow.)
+//
+// Basic ARPResponder Functionality:
+// - Maintains a mapping between IP addresses and MAC addresses
+// - Responds to ARP requests if it knows the MAC address for the requested IP
+// - Floods ARP requests to all switches if it doesn't know the requested MAC address
+// - Learns new IP-to-MAC mappings from ARP packets passing through the network
+//
+// HyperFlow is a distributed controller architecture that:
+// - Enables multiple OpenFlow controllers to work together as a logically centralized controller
+// - Provides fault tolerance and scalability through controller distribution
+// - Synchronizes state between controllers using a publish-subscribe mechanism
+// - Allows controllers to operate independently while maintaining a consistent network view
+//
+// HF_ARPResponder's Role:
+//
+// 1. State Synchronization: When it learns a new IP-to-MAC mapping, it not only stores it locally
+//    but also publishes this information to other controllers through the HyperFlow synchronization channel.
+//
+// 2. Distributed Learning: It can receive IP-to-MAC mappings discovered by other controllers through
+//    the HyperFlow "ReFire" mechanism, allowing all controllers to maintain a consistent ARP table.
+//
+// 3. Fault Tolerance: If one controller fails, others can continue to respond to ARP requests
+//    because they share the same ARP table information.
+//
+// 4. Scalability: By distributing the ARP handling across multiple controllers, the system can
+//    handle larger networks more efficiently.
+//
+// Note: HF_ARPResponder requires the HyperFlowAgent to be installed in the same controller.
+// The HyperFlowAgent provides the communication infrastructure that enables the
+// distributed functionality of HF_ARPResponder.
+//
 simple HF_ARPResponder like IControllerApp
 {
     parameters:

src/openflow/hyperflow/HyperFlowAgent.ned

@@ -1,31 +1,79 @@
 
 package openflow.hyperflow;
 
-
-
+//
+// The HyperFlowAgent is a core component of the HyperFlow distributed controller architecture
+// for OpenFlow networks. It enables multiple OpenFlow controllers to work together as a logically
+// centralized controller while being physically distributed.
+//
+// HyperFlow is a distributed controller architecture that:
+// - Enables multiple OpenFlow controllers to work together as a logically centralized controller
+// - Provides fault tolerance and scalability through controller distribution
+// - Synchronizes state between controllers using a publish-subscribe mechanism
+// - Allows controllers to operate independently while maintaining a consistent network view
+//
+// HyperFlowAgent's Role:
+//
+// 1. State Synchronization: The HyperFlowAgent maintains two channels for synchronization:
+//    - Control Channel: Contains information about controllers and their connected switches
+//    - Data Channel: Contains events and state changes that need to be synchronized
+//
+// 2. Controller Communication: The HyperFlowAgent connects to a central HyperFlowSynchronizer
+//    that facilitates communication between distributed controllers. It periodically:
+//    - Reports its status and connected switches (ReportIn)
+//    - Requests synchronization with other controllers (SyncRequest)
+//    - Checks if other controllers are alive (CheckAlive)
+//
+// 3. Event Distribution: When state changes occur in one controller (e.g., a new ARP entry),
+//    the HyperFlowAgent:
+//    - Packages the change as a DataChannelEntry
+//    - Sends it to the HyperFlowSynchronizer
+//    - The change is then distributed to all other controllers
+//
+// 4. Event Notification: The HyperFlowAgent emits HyperFlowReFire signals to notify other
+//    controller applications (like HF_ARPResponder, HF_LLDPAgent) about state changes from
+//    other controllers, allowing them to update their local state.
+//
+// 5. Fault Tolerance: The HyperFlowAgent detects controller failures and recoveries, enabling
+//    the system to continue operating even if some controllers fail.
+//
 simple HyperFlowAgent extends openflow.controllerApps.AbstractTCPControllerApp
 {
     parameters:
         @class(openflow::HyperFlowAgent);
         @class(HyperFlowAgent);
         @signal[HyperFlowReFire];
         @display("i=block/app");
+
+        // Hard timeout for flow entries (0 means no hard timeout)
         int flowModHardTimeOut = default(0);
+
+        // Idle timeout for flow entries (how long a flow entry remains if not used)
         int flowModIdleTimeOut = default(1);
+
+        // Local port for the TCP socket (use -1 for automatic port assignment)
         int localPort = default(-1);
+
+        // Local address for the TCP socket (use "" for any address)
         string localAddress = default("");
+
+        // Address of the HyperFlowSynchronizer to connect to
         string connectAddressHyperFlowSynchronizer = default("HyperFlowSynchronizer");
+
+        // Port of the HyperFlowSynchronizer to connect to
         int connectPortHyperFlowSynchronizer = default(1003);
 
+        // When to initiate the connection to the HyperFlowSynchronizer
         double connectAt @unit("s") = default(1s);
 
-        //should be 1/3 of the checkAliveEvery
+        // How often to send ReportIn messages (should be 1/3 of the checkAliveEvery)
+        // ReportIn messages inform the synchronizer about this controller and its switches
         double reportInEvery @unit("s") = default(1s);
+
+        // How often to send SyncRequest messages to get updates from other controllers
         double checkSyncEvery @unit("s") = default(1s);
 
-        //should be the same as aliveintervall of the synchronizer module
+        // How often to check if other controllers are alive
+        // Should be the same as aliveInterval of the synchronizer module
         double checkAliveEvery @unit("s") = default(3s);
-
-
-
 }

src/openflow/openflow/controller/IOpenFlowController.ned

@@ -1,21 +1,37 @@
 
-
 package openflow.openflow.controller;
 
-//Interface module for the OpenFlow Controller module.
-//Communication with OpenFlow switch;
-//Sending Packet-Out messages;
-//Sending Flow Modification messages;
-
+//
+// IOpenFlowController is the base interface for OpenFlow controller implementations in the
+// openflow4core simulation model. It defines the common parameters and gates that all
+// OpenFlow controller implementations must provide.
+//
+// The OpenFlow controller is responsible for:
+//
+// 1. Establishing and maintaining connections with OpenFlow switches
+// 2. Processing OpenFlow protocol messages (HELLO, FEATURES_REQUEST, PACKET_IN, etc.)
+// 3. Managing the network by installing flow entries in switches
+// 4. Providing an interface for controller applications to implement network control logic
+//
+// This interface allows for different controller implementations while maintaining
+// compatibility with the rest of the simulation model. The primary implementation
+// is the OF_Controller module.
+//
 moduleinterface IOpenFlowController
 {
     parameters:
-        
-        string address;// = default("");
-        int port;// = default(6633);
-        double serviceTime @unit("s");// = default(0s);
-        double bootTime @unit("s");// = default(0s);
-        
+        // IP address the controller listens on
+        string address;
+
+        // TCP port the controller listens on (standard OpenFlow port is 6633)
+        int port;
+
+        // Processing time for each message (used to simulate controller processing delay)
+        double serviceTime @unit("s");
+
+        // Time before the controller is fully operational (boot delay)
+        double bootTime @unit("s");
+
     gates:
         input socketIn @labels(TcpCommand/up);
         output socketOut @labels(TcpCommand/down);

src/openflow/openflow/controller/OF_Controller.ned

@@ -1,11 +1,32 @@
 
-
 package openflow.openflow.controller;
 
-//Communication with OpenFlow switch;
-//Sending Packet-Out messages;
-//Sending Flow Modification messages;
-
+//
+// The OF_Controller is the core module that implements the OpenFlow controller functionality
+// in the openflow simulation model. It handles the communication with OpenFlow switches,
+// processes OpenFlow protocol messages, and provides an interface for controller applications.
+//
+// The OF_Controller is responsible for:
+//
+// 1. Connection Management: Establishing and maintaining TCP connections with OpenFlow switches.
+//    It handles the OpenFlow handshake process (HELLO, FEATURES_REQUEST, FEATURES_REPLY) and
+//    maintains information about connected switches.
+//
+// 2. Message Processing: Processing OpenFlow protocol messages received from switches, such as
+//    PACKET_IN, FEATURES_REPLY, and EXPERIMENTER messages. It also sends messages to switches,
+//    such as PACKET_OUT and FLOW_MOD messages.
+//
+// 3. Controller Application Interface: Providing an interface for controller applications to
+//    register themselves and receive notifications about OpenFlow events. It emits signals for
+//    various events (PacketIn, PacketOut, etc.) that controller applications can subscribe to.
+//
+// 4. Switch Information Management: Maintaining a list of connected switches and their capabilities,
+//    which can be accessed by controller applications.
+//
+// The OF_Controller is typically used as a submodule within the Open_Flow_Controller compound module,
+// which combines it with standard networking components (TCP/IP stack, Ethernet interfaces) and
+// controller applications to form a complete OpenFlow controller.
+//
 simple OF_Controller like IOpenFlowController
 {
     parameters:
@@ -22,13 +43,24 @@ simple OF_Controller like IOpenFlowController
         @signal[waitingTime](type="simtime_t");
         @statistic[waitingTime](title="WaitingTime"; record=vector?,stats?; interpolationmode=none);
         @display("i=block/app");
-        
+
+        // IP address the controller listens on (empty string means all available interfaces)
         string address = default("");
+
+        // TCP port the controller listens on (standard OpenFlow port is 6633)
         int port = default(6633);
+
+        // Processing time for each message (used to simulate controller processing delay)
         double serviceTime @unit("s") = default(0s);
+
+        // Time before the controller is fully operational (boot delay)
         double bootTime @unit("s") = default(0s);
+
+        // Whether to process messages in parallel (true) or sequentially (false)
+        // When false, messages are processed one at a time with serviceTime delay between them
+        // When true, multiple messages can be processed simultaneously
 		bool parallelProcessing = default(false);
-        
+
     gates:
         input socketIn @labels(TcpCommand/up);
         output socketOut @labels(TcpCommand/down);