PacketFlowManager: comments cleaned up

Author: avarga

src/simu5g/stack/packetFlowManager/PacketFlowManagerBase.h

@@ -26,24 +26,26 @@ class LteRlcUmDataPdu;
 struct StatusDescriptor;
 
 /**
- * This module is responsible for keeping track of all PDCP SDUs.
+ * This module is responsible for keeping tracking the flow of SDUs in the stack,
+ * and compute statistics from them. It is passive observer of the packet flow.
+ *
  * A PDCP SDU is encapsulated in the following packets while it is going down
  * through the LTE NIC layers:
  *
- * PDCP SDU
- * some operations
- * PDCP PDU
- * RLC SDU
- * RLC PDU or fragmented into more than one RLC PDUs
- * MAC SDU
- * inserted into one TB
- * MAC PDU (aka TB)
+ * - PDCP SDU
+ * - some operations
+ * - PDCP PDU
+ * - RLC SDU
+ * - RLC PDU or fragmented into more than one RLC PDUs
+ * - MAC SDU
+ * - inserted into one TB
+ * - MAC PDU (aka TB)
  *
- * Each PDCP has its own seq number, managed by the corresponding LCID
+ * Each PDCP has its own sequence number, managed by the corresponding LCID
  *
  * The main functions of this module are:
  *  - detect PDCP SDUs discarded (no part transmitted)
- *  - calculate the delay time of a pkt, from PDCP SDU to last Harq ACK of the
+ *  - calculate the delay time of a packet, from PDCP SDU to last HARQ ACK of the
  *    corresponding seq number.
  */
 class PacketFlowManagerBase : public cSimpleModule
@@ -66,7 +68,7 @@ class PacketFlowManagerBase : public cSimpleModule
     DiscardedPkts pktDiscardCounterTotal_; // total discarded packets counter of the node
 
     RanNodeType nodeType_; // UE or ENODEB (used for set MACROS)
-    short int harqProcesses_; // number of harq processes
+    short int harqProcesses_; // number of HARQ processes
 
     std::string pfmType;
 
@@ -77,77 +79,81 @@ class PacketFlowManagerBase : public cSimpleModule
     void initialize(int stage) override;
     void finish() override;
 
-    // return true if a structure for this lcid is present
+    // Return true if a data structure for this LCID is present
     virtual bool hasLcid(LogicalCid lcid) = 0;
-    /*
-     * initialize a new structure for this lcid
-     * abstract since in eNodeB case, it initializes
-     * different structure with respect to the UE
-     */
+
+    // Initialize a new data structure for this LCID. Abstract since in eNodeB case,
+    // it initializes different structures with respect to the UE
     virtual void initLcid(LogicalCid lcid, MacNodeId nodeId) = 0;
 
-    /* reset the structure for this lcid
-     * abstract since in eNodeB case, it clears
-     * different structure with respect to the UE
-     */
+    // Reset the data structure for this LCID. Abstract since in eNodeB case,
+    // it clears different structures with respect to the UE
     virtual void clearLcid(LogicalCid lcid) = 0;
 
-    // reset structures for all connections
+    // Reset data structures for all connections
     virtual void clearAllLcid() = 0;
 
   public:
-    /*
-     * This method inserts a new pdcp seqnum and the corresponding entry time
-     * @param lcid
-     * @param pdcpSno sequence number of the pdcp pdu
-     * @param entryTime the time the packet enters the PDCP layer
-     *
-     * Used only by the eNodeB packetFlowManager
+    /**
+     * This method is called when a PDCP SDU enters the PDCP layer for downlink transmission.
+     * It records the PDCP sequence number and entry timestamp in the tracking data structures
+     * to enable delay measurement and packet flow monitoring. Used only by the eNodeB.
      */
     virtual void insertPdcpSdu(inet::Packet *pdcpPkt) = 0;
+
+    /**
+     * This method is called when a PDCP SDU is received on the uplink.
+     * It tracks uplink data volume and packet loss rate statistics.
+     */
     virtual void receivedPdcpSdu(inet::Packet *pdcpPkt) = 0;
 
-    /*
-     * This method inserts a new rlc seqnum and the corresponding pdcp pdus inside it
-     * @param lcid
-     * @param rlcPdu packet pointer
+    /**
+     * This method is called when an RLC PDU is created from PDCP SDUs for transmission.
+     * It records the mapping between the RLC PDU and its contained PDCP SDUs in the tracking
+     * data structures, along with burst status information for throughput measurement.
      */
     virtual void insertRlcPdu(LogicalCid lcid, const inet::Ptr<LteRlcUmDataPdu> rlcPdu, RlcBurstStatus status) = 0;
 
-    /*
-     * This method inserts a new macPduId Omnet id and the corresponding rlc pdus inside it
-     * @param lcid
-     * @param macPdu packet pointer
+    /**
+     * This method is called when a MAC PDU is inserted into the HARQ buffer for transmission.
+     * It records the mapping between the MAC PDU and its contained RLC PDUs in the tracking
+     * data structures for downlink packet flow management.
      */
     virtual void insertMacPdu(const inet::Ptr<const LteMacPdu> macPdu) = 0;
 
-    /*
-     * This method checks if the HARQ aSequenceNumberSet related to a macPduId acknowledges an ENTIRE
-     * pdcp sdu
-     * @param lcid
-     * @param macPduId Omnet id of the mac pdu
+    /**
+     * This method is called when a downlink MAC PDU is successfully acknowledged by the UE.
+     * It processes the acknowledgment to determine if complete PDCP SDUs have been delivered,
+     * calculates packet delays, and updates statistics for downlink transmission.
      */
     virtual void macPduArrived(const inet::Ptr<const LteMacPdu> macPdu) = 0;
 
+    /**
+     * This method is called when an uplink MAC PDU is received from a UE at the eNodeB.
+     * It measures uplink packet delay by matching the received PDU with the corresponding
+     * grant that was previously sent to the UE (identified by grantId).
+     */
     virtual void ulMacPduArrived(MacNodeId nodeId, unsigned int grantId) {};
-    /*
+
+    /**
      * This method is called after maxHarqTransmission of a MAC PDU ID has been
-     * reached. The PDCP, RLC, seq numbers referred to the macPdu are cleared from the
-     * data structures
-     * @param lcid
-     * @param macPduId Omnet id of the mac pdu to be discarded
+     * reached. The PDCP, RLC sequence numbers referred to the MAC PDU are cleared from the
+     * data structures.
      */
     virtual void discardMacPdu(const inet::Ptr<const LteMacPdu> macPdu) = 0;
 
-    /*
-     * This method is used to keep track of all discarded RLC pdus. If all rlc pdus
-     * that compose a PDCP SDU have been discarded the discarded counters are updated
-     * @param lcid
-     * @param rlcSno sequence number of the rlc pdu
-     * @param fromMac used when this method is called by discardMacPdu
+    /**
+     * This method is used to keep track of all discarded RLC PDUs. If all RLC PDUs
+     * that compose a PDCP SDU have been discarded, the discarded counters are updated.
+     * The fromMac parameter is used when this method is called by discardMacPdu.
      */
     virtual void discardRlcPdu(LogicalCid lcid, unsigned int rlcSno, bool fromMac = false) = 0;
 
+    /**
+     * This method is called when an uplink grant is sent to a UE.
+     * It records the grant transmission timestamp to enable uplink delay
+     * measurement when the corresponding MAC PDU is received.
+     */
     virtual void grantSent(MacNodeId nodeId, unsigned int grantId) {}
 
     virtual void resetDiscardCounter();
@@ -156,4 +162,3 @@ class PacketFlowManagerBase : public cSimpleModule
 } //namespace
 
 #endif
-

src/simu5g/stack/packetFlowManager/PacketFlowManagerEnb.cc

@@ -85,7 +85,7 @@ void PacketFlowManagerEnb::clearAllLcid()
     EV_FATAL << NOW << " " << pfmType << "::clearAllLcid - cleared data structures for all lcids " << endl;
 }
 
-void PacketFlowManagerEnb::initPdcpStatus(StatusDescriptor *desc, unsigned int pdcp, unsigned int sduHeaderSize, simtime_t& arrivalTime)
+void PacketFlowManagerEnb::initPdcpStatus(StatusDescriptor *desc, unsigned int pdcp, unsigned int sduHeaderSize, simtime_t arrivalTime)
 {
     // if pdcpStatus_ already present, error
     std::map<unsigned int, PdcpStatus>::iterator it = desc->pdcpStatus_.find(pdcp);

src/simu5g/stack/packetFlowManager/PacketFlowManagerEnb.h

@@ -26,25 +26,7 @@ using namespace omnetpp;
 class LteRlcUmDataPdu;
 
 /**
- * This module is responsible for keeping track of all PDCP SDUs.
- * A PDCP SDU passes through the following states while it is going down
- * through the LTE NIC layers:
- *
- * PDCP SDU
- * few operations
- * PDCP PDU
- * RLC SDU
- * RLC PDU or fragmented into more than one RLC PDU
- * MAC SDU
- * inserted into one TB
- * MAC PDU (aka TB)
- *
- * Each PDCP has its own sequence number, managed by the corresponding LCID
- *
- * The main functions of this module are:
- *  - detect PDCP SDU discarded (no part transmitted)
- *  - calculate the delay time of a packet, from PDCP SDU to last Harq ACK of the
- *    corresponding sequence number.
+ * The eNB-specific version of PacketFlowManager.
  */
 class PacketFlowManagerEnb : public PacketFlowManagerBase
 {
@@ -129,15 +111,15 @@ class PacketFlowManagerEnb : public PacketFlowManagerBase
      * total of the burst size.
      * It is called by macPduArrived (ack true) and rlcPduDiscarded (ack false)
      * @param desc LCID descriptor
-     * @param pdcpSno PDCP sequence number
+     * @param rlcSno RLC sequence number
      * @bool ack PDCP acknowledgment flag
      */
     void removePdcpBurstRLC(StatusDescriptor *desc, unsigned int rlcSno, bool ack);
 
     /*
      * This method creates a pdcpStatus structure when a PDCP SDU arrives at the PDCP layer.
      */
-    void initPdcpStatus(StatusDescriptor *desc, unsigned int pdcp, unsigned int sduHeaderSize, simtime_t& arrivalTime);
+    void initPdcpStatus(StatusDescriptor *desc, unsigned int pdcp, unsigned int sduHeaderSize, simtime_t arrivalTime);
 
     // return true if a structure for this LCID is present
     bool hasLcid(LogicalCid lcid) override;
@@ -151,50 +133,20 @@ class PacketFlowManagerEnb : public PacketFlowManagerBase
   public:
     void insertPdcpSdu(inet::Packet *pdcpPkt) override;
     void receivedPdcpSdu(inet::Packet *pdcpPkt) override;
-
     void insertRlcPdu(LogicalCid lcid, const inet::Ptr<LteRlcUmDataPdu> rlcPdu, RlcBurstStatus status) override;
-
     void insertMacPdu(inet::Ptr<const LteMacPdu>) override;
-
-    /*
-     * This method checks if the HARQ acknowledgment relative to a macPduId acknowledges an ENTIRE
-     * PDCP SDU
-     * @param lcid
-     * @param macPduId Omnet ID of the MAC PDU
-     */
     void macPduArrived(inet::Ptr<const LteMacPdu>) override;
-
     void ulMacPduArrived(MacNodeId nodeId, unsigned int grantId) override;
-
-    /*
-     * This method is called after maxHarqTransmission of a MAC PDU ID has been
-     * reached. The PDCP, RLC, SN referred to the macPdu are cleared from the
-     * data structures
-     * @param lcid
-     * @param macPduId Omnet ID of the MAC PDU to be discarded
-     */
     void discardMacPdu(const inet::Ptr<const LteMacPdu> macPdu) override;
-
-    /*
-     * This method is used to keep track of all discarded RLC PDUs. If all RLC PDUs
-     * that compose a PDCP SDU have been discarded the discarded counters are updated
-     * @param lcid
-     * @param rlcSno sequence number of the RLC PDU
-     * @param fromMac used when this method is called by discardMacPdu
-     */
     void discardRlcPdu(LogicalCid lcid, unsigned int rlcSno, bool fromMac = false) override;
-
     void grantSent(MacNodeId nodeId, unsigned int grantId) override;
 
-    /*
-     * deletes all the LCID structures related to the UE
-     * called upon handover
+    /**
+     * Deletes all the LCID structures related to the UE. Called upon handover.
      */
     virtual void deleteUe(MacNodeId id);
 
-    /*
-     * The methods are called for a specific UE
-     */
+    // Per-UE statistics
 
     virtual uint64_t getDataVolume(MacNodeId nodeId, Direction dir);
     virtual void resetDataVolume(MacNodeId nodeId, Direction dir);

src/simu5g/stack/packetFlowManager/PacketFlowManagerUe.h

@@ -23,29 +23,10 @@ class LteRlcUmDataPdu;
 class LtePdcpUe;
 
 /**
- * This module is responsible for keeping track of all PDCP SDUs.
- * A PDCP SDU passes through the following states while it is going down
- * through the LTE NIC layers:
- *
- * PDCP SDU
- * few operations
- * PDCP PDU
- * RLC SDU
- * RLC PDU or fragmented into more than one RLC PDU
- * MAC SDU
- * inserted into one TB
- * MAC PDU (aka TB)
- *
- * Each PDCP has its own sequence number, managed by the corresponding LCID.
- *
- * The main functions of this module are:
- *  - detect PDCP SDU discarded (no part transmitted)
- *  - calculate the delay time of a packet, from PDCP SDU to last HARQ ACK of the
- *    corresponding sequence number.
+ * The UE-specific version of Packet Flow Manager.
  */
 class PacketFlowManagerUe : public PacketFlowManagerBase
 {
-
     /*
      * The node can have different active connections (LCID) at the same time, hence we need to
      * maintain the status for each of them.
@@ -69,12 +50,10 @@ class PacketFlowManagerUe : public PacketFlowManagerBase
     std::set<unsigned int> myset;
 
   protected:
-
     void initialize(int stage) override;
     void finish() override;
 
     void initPdcpStatus(StatusDescriptor *desc, unsigned int pdcp, unsigned int sduHeaderSize, simtime_t& arrivalTime);
-
     // return true if a structure for this LCID is present
     bool hasLcid(LogicalCid lcid) override;
     // initialize a new structure for this LCID
@@ -86,57 +65,16 @@ class PacketFlowManagerUe : public PacketFlowManagerBase
 
   public:
     void insertPdcpSdu(inet::Packet *pdcpPkt) override;
-
     void receivedPdcpSdu(inet::Packet *pdcpPkt) override { /*TODO*/ }
-
-    /*
-     * This method inserts a new RLC sequence number and the corresponding PDCP PDUs inside it.
-     * @param lcid
-     * @param rlcSno sequence number of the RLC PDU
-     * @param pdcpSnoSet list of PDCP PDUs inside the RLC PDU
-     * @param lastIsFrag used to inform if the last PDCP is fragmented or not.
-     */
-
     void insertRlcPdu(LogicalCid lcid, const inet::Ptr<LteRlcUmDataPdu> rlcPdu, RlcBurstStatus status) override;
-
-    /*
-     * This method inserts a new MAC PDU ID Omnet ID and the corresponding RLC PDUs inside it.
-     * @param lcid
-     * @param macPdu packet pointer
-     */
     void insertMacPdu(const inet::Ptr<const LteMacPdu> macPdu) override;
-
-    /*
-     * This method checks if the HARQ ACK sequence number set relative to a MAC PDU ID acknowledges an ENTIRE
-     * PDCP SDU.
-     * @param lcid
-     * @param macPduId Omnet ID of the MAC PDU
-     */
     void macPduArrived(const inet::Ptr<const LteMacPdu> macPdu) override;
-
-    /*
-     * This method is called after the maximum HARQ transmission of a MAC PDU ID has been
-     * reached. The PDCP, RLC, sequence number referred to the MAC PDU are cleared from the
-     * data structures.
-     * @param lcid
-     * @param macPduId Omnet ID of the MAC PDU to be discarded
-     */
     void discardMacPdu(const inet::Ptr<const LteMacPdu> macPdu) override;
-
-    /*
-     * This method is used to keep track of all discarded RLC PDUs. If all RLC PDUs
-     * that compose a PDCP SDU have been discarded, the discard counters are updated.
-     * @param lcid
-     * @param rlcSno sequence number of the RLC PDU
-     * @param fromMac used when this method is called by discardMacPdu
-     */
     void discardRlcPdu(LogicalCid lcid, unsigned int rlcSno, bool fromMac = false) override;
 
     DiscardedPkts getDiscardedPkt();
-
     double getDelayStats();
     void resetDelayCounter();
-
 };
 
 } //namespace