From aa43850bac06e5c3462f3b28dfed35fedcb1cc27 Mon Sep 17 00:00:00 2001 From: Eduardo Almeida Date: Fri, 9 Jun 2023 10:08:12 +0100 Subject: [PATCH] click: Fix Doxygen warnings --- .../helper/click-internet-stack-helper.cc | 29 +++++++++- .../helper/click-internet-stack-helper.h | 57 +++++++++++++++---- src/click/model/ipv4-click-routing.h | 49 ++++++++++------ src/click/model/ipv4-l3-click-protocol.h | 54 ++++++++++++++---- src/click/test/ipv4-click-routing-test.cc | 40 ++++++++++++- 5 files changed, 189 insertions(+), 40 deletions(-) diff --git a/src/click/helper/click-internet-stack-helper.cc b/src/click/helper/click-internet-stack-helper.cc index 57c1d276f..c997331bd 100644 --- a/src/click/helper/click-internet-stack-helper.cc +++ b/src/click/helper/click-internet-stack-helper.cc @@ -58,6 +58,13 @@ static InterfaceFileMapIpv4 static InterfaceStreamMapIpv4 g_interfaceStreamMapIpv4; /**< A mapping of Ipv4/interface pairs to ascii streams */ +/** + * IPv4 Rx / Tx packet callback. + * + * \param p Packet. + * \param ipv4 IPv4 stack. + * \param interface Interface number. + */ static void Ipv4L3ProtocolRxTxSink(Ptr p, Ptr ipv4, uint32_t interface) { @@ -80,6 +87,16 @@ Ipv4L3ProtocolRxTxSink(Ptr p, Ptr ipv4, uint32_t interface) file->Write(Simulator::Now(), p); } +/** + * Packet dropped callback without context. + * + * \param stream Output stream. + * \param header IPv4 header. + * \param packet Packet. + * \param reason Packet drop reason. + * \param ipv4 IPv4 stack. + * \param interface Interface number. + */ static void Ipv4L3ProtocolDropSinkWithoutContext(Ptr stream, const Ipv4Header& header, @@ -106,6 +123,17 @@ Ipv4L3ProtocolDropSinkWithoutContext(Ptr stream, *stream->GetStream() << "d " << Simulator::Now().GetSeconds() << " " << *p << std::endl; } +/** + * Packet dropped callback with context. + * + * \param stream Output stream. + * \param context Context. + * \param header IPv4 header. + * \param packet Packet. + * \param reason Packet drop reason. + * \param ipv4 IPv4 stack. + * \param interface Interface number. + */ static void Ipv4L3ProtocolDropSinkWithContext(Ptr stream, std::string context, @@ -145,7 +173,6 @@ ClickInternetStackHelper::ClickInternetStackHelper() Initialize(); } -// private method called by both constructor and Reset () void ClickInternetStackHelper::Initialize() { diff --git a/src/click/helper/click-internet-stack-helper.h b/src/click/helper/click-internet-stack-helper.h index 47ae3de51..a4f0e919e 100644 --- a/src/click/helper/click-internet-stack-helper.h +++ b/src/click/helper/click-internet-stack-helper.h @@ -57,7 +57,20 @@ class ClickInternetStackHelper : public PcapHelperForIpv4, public AsciiTraceHelp * Destroy the ClickInternetStackHelper */ ~ClickInternetStackHelper() override; - ClickInternetStackHelper(const ClickInternetStackHelper&); + + /** + * Copy constructor. + * + * \param o Object to copy from. + */ + ClickInternetStackHelper(const ClickInternetStackHelper& o); + + /** + * Assignment operator. + * + * \param o Object to copy from. + * \return Reference to updated object. + */ ClickInternetStackHelper& operator=(const ClickInternetStackHelper& o); /** @@ -143,11 +156,12 @@ class ClickInternetStackHelper : public PcapHelperForIpv4, public AsciiTraceHelp private: /** - * @brief Enable pcap output the indicated Ipv4 and interface pair. + * \brief Enable pcap output the indicated Ipv4 and interface pair. * - * @param prefix Filename prefix to use for pcap files. - * @param ipv4 Ptr to the Ipv4 interface on which you want to enable tracing. - * @param interface Interface ID on the Ipv4 on which you want to enable tracing. + * \param prefix Filename prefix to use for pcap files. + * \param ipv4 Ptr to the Ipv4 interface on which you want to enable tracing. + * \param interface Interface ID on the Ipv4 on which you want to enable tracing. + * \param explicitFilename Whether the filename is explicit or not. */ void EnablePcapIpv4Internal(std::string prefix, Ptr ipv4, @@ -155,13 +169,14 @@ class ClickInternetStackHelper : public PcapHelperForIpv4, public AsciiTraceHelp bool explicitFilename) override; /** - * @brief Enable ascii trace output on the indicated Ipv4 and interface pair. + * \brief Enable ascii trace output on the indicated Ipv4 and interface pair. * - * @param stream An OutputStreamWrapper representing an existing file to use + * \param stream An OutputStreamWrapper representing an existing file to use * when writing trace data. - * @param prefix Filename prefix to use for ascii trace files. - * @param ipv4 Ptr to the Ipv4 interface on which you want to enable tracing. - * @param interface Interface ID on the Ipv4 on which you want to enable tracing. + * \param prefix Filename prefix to use for ascii trace files. + * \param ipv4 Ptr to the Ipv4 interface on which you want to enable tracing. + * \param interface Interface ID on the Ipv4 on which you want to enable tracing. + * \param explicitFilename Whether the filename is explicit or not. */ void EnableAsciiIpv4Internal(Ptr stream, std::string prefix, @@ -169,12 +184,34 @@ class ClickInternetStackHelper : public PcapHelperForIpv4, public AsciiTraceHelp uint32_t interface, bool explicitFilename) override; + /** + * Initialize stack helper. + * Called by both constructor and Reset(). + */ void Initialize(); + /** + * Create and aggregate object from type ID. + * + * \param node Node. + * \param typeId Type ID. + */ static void CreateAndAggregateObjectFromTypeId(Ptr node, const std::string typeId); + /** + * Check if PCAP is hooked. + * + * \param ipv4 IPv4 stack. + * \return True if PCAP is hooked. + */ bool PcapHooked(Ptr ipv4); + /** + * Check if ASCII is hooked. + * + * \param ipv4 IPv4 stack. + * \return True if ASCII is hooked. + */ bool AsciiHooked(Ptr ipv4); /** diff --git a/src/click/model/ipv4-click-routing.h b/src/click/model/ipv4-click-routing.h index d772bcd80..cded799e7 100644 --- a/src/click/model/ipv4-click-routing.h +++ b/src/click/model/ipv4-click-routing.h @@ -54,7 +54,6 @@ class UniformRandomVariable; * \ingroup click * \brief Class to allow a node to use Click for external routing */ - class Ipv4ClickRouting : public Ipv4RoutingProtocol { public: @@ -63,11 +62,22 @@ class Ipv4ClickRouting : public Ipv4RoutingProtocol friend class ::ClickIfidFromNameTest; friend class ::ClickIpMacAddressFromNameTest; + /** + * Get type ID. + * + * \return TypeId. + */ static TypeId GetTypeId(); + /** Constructor. */ Ipv4ClickRouting(); ~Ipv4ClickRouting() override; + /** + * Get the uniform random variable. + * + * \return Uniform random variable. + */ Ptr GetRandomVariable(); protected: @@ -103,27 +113,30 @@ class Ipv4ClickRouting : public Ipv4RoutingProtocol /** * \brief Read Handler interface for a node's Click Elements. * Allows a user to read state information of a Click element. - * \param elementName name of the Click element - * \param handlerName name of the handler to be read + * \param elementName name of the Click element. + * \param handlerName name of the handler to be read. + * \return String read. */ std::string ReadHandler(std::string elementName, std::string handlerName); /** - * \brief Write Handler interface for a node's Click Elements + * \brief Write Handler interface for a node's Click Elements. * Allows a user to modify state information of a Click element. - * \param elementName name of the Click element - * \param handlerName name of the handler to be read - * \param writeString string to be written using the write handler + * \param elementName name of the Click element. + * \param handlerName name of the handler to be read. + * \param writeString string to be written using the write handler. + * \return Write operation status. */ int WriteHandler(std::string elementName, std::string handlerName, std::string writeString); /** - * * \brief Sets an interface to run on promiscuous mode. + * \param ifid Interface ID. */ void SetPromisc(int ifid); private: + /// Pointer to the simclick node simclick_node_t* m_simNode; /** @@ -185,6 +198,7 @@ class Ipv4ClickRouting : public Ipv4RoutingProtocol /** * \brief Provides for SIMCLICK_IF_READY + * \param ifid Interface ID * \return Returns 1, if the interface is ready, -1 if ifid is invalid */ bool IsInterfaceReady(int ifid); @@ -203,7 +217,8 @@ class Ipv4ClickRouting : public Ipv4RoutingProtocol void AddSimNodeToClickMapping(); /** - * \brief Get current simulation time as a timeval + * \brief Get current simulation time as a timeval. + * \return Current simulation time as a timeval. */ struct timeval GetTimevalFromNow() const; @@ -273,16 +288,16 @@ class Ipv4ClickRouting : public Ipv4RoutingProtocol void NotifyRemoveAddress(uint32_t interface, Ipv4InterfaceAddress address) override; private: - std::string m_clickFile; - std::map m_defines; - std::string m_nodeName; - std::string m_clickRoutingTableElement; + std::string m_clickFile; //!< Name of .click configuration file + std::map m_defines; //!< Defines for .click configuration file parsing + std::string m_nodeName; //!< Name of the node + std::string m_clickRoutingTableElement; //!< Name of the routing table element - bool m_clickInitialised; - bool m_nonDefaultName; + bool m_clickInitialised; //!< Whether click has been initialized + bool m_nonDefaultName; //!< Whether a non-default name has been set - Ptr m_ipv4; - Ptr m_random; + Ptr m_ipv4; //!< Pointer to the IPv4 object + Ptr m_random; //!< Uniform random variable }; } // namespace ns3 diff --git a/src/click/model/ipv4-l3-click-protocol.h b/src/click/model/ipv4-l3-click-protocol.h index d17a939a8..d90f5403d 100644 --- a/src/click/model/ipv4-l3-click-protocol.h +++ b/src/click/model/ipv4-l3-click-protocol.h @@ -61,6 +61,11 @@ class Icmpv4L4Protocol; class Ipv4L3ClickProtocol : public Ipv4 { public: + /** + * Get Type ID. + * + * \return The type ID. + */ static TypeId GetTypeId(); /** @@ -223,6 +228,12 @@ class Ipv4L3ClickProtocol : public Ipv4 void SetDown(uint32_t i) override; bool IsForwarding(uint32_t i) const override; void SetForwarding(uint32_t i, bool val) override; + + /** + * Sets an interface to run on promiscuous mode. + * + * \param i Interface ID. + */ void SetPromisc(uint32_t i); protected: @@ -235,6 +246,17 @@ class Ipv4L3ClickProtocol : public Ipv4 void NotifyNewAggregate() override; private: + /** + * Build IPv4 header. + * + * \param source IPv4 source address. + * \param destination IPv4 destination address. + * \param protocol Protocol. + * \param payloadSize Payload size. + * \param ttl Time To Live (TTL). + * \param mayFragment Whether the packet can be fragmented or not. + * \return The IPv4 header. + */ Ipv4Header BuildHeader(Ipv4Address source, Ipv4Address destination, uint8_t protocol, @@ -247,32 +269,42 @@ class Ipv4L3ClickProtocol : public Ipv4 void SetWeakEsModel(bool model) override; bool GetWeakEsModel() const override; + /** + * \brief List of IPv4 interfaces. + */ typedef std::vector> Ipv4InterfaceList; + /** * \brief Container of NetDevices registered to IPv4 and their interface indexes. */ typedef std::map, uint32_t> Ipv4InterfaceReverseContainer; + + /** + * \brief List of sockets. + */ typedef std::list> SocketList; + /** * \brief Container of the IPv4 L4 keys: protocol number, interface index */ typedef std::pair L4ListKey_t; + /** * \brief Container of the IPv4 L4 instances. */ typedef std::map> L4List_t; - Ptr m_routingProtocol; - bool m_ipForward; - bool m_weakEsModel; - L4List_t m_protocols; - Ipv4InterfaceList m_interfaces; + Ptr m_routingProtocol; //!< IPv4 routing protocol + bool m_ipForward; //!< Whether IP forwarding is enabled + bool m_weakEsModel; //!< Whether to use weak Es model + L4List_t m_protocols; //!< List of IPv4 L4 protocols + Ipv4InterfaceList m_interfaces; //!< List of interfaces Ipv4InterfaceReverseContainer - m_reverseInterfacesContainer; //!< Container of NetDevice / Interface index associations. - uint8_t m_defaultTtl; - uint16_t m_identification; + m_reverseInterfacesContainer; //!< Container of NetDevice / Interface index associations + uint8_t m_defaultTtl; //!< Default TTL + uint16_t m_identification; //!< Identification - Ptr m_node; + Ptr m_node; //!< Node /** \todo Remove; this TracedCallback is never invoked. */ TracedCallback, uint32_t> m_sendOutgoingTrace; @@ -281,9 +313,9 @@ class Ipv4L3ClickProtocol : public Ipv4 /** \todo This TracedCallback is invoked but not accessible. */ TracedCallback, uint32_t> m_localDeliverTrace; - SocketList m_sockets; + SocketList m_sockets; //!< List of sockets - std::vector m_promiscDeviceList; + std::vector m_promiscDeviceList; //!< List of promiscuous devices }; } // namespace ns3 diff --git a/src/click/test/ipv4-click-routing-test.cc b/src/click/test/ipv4-click-routing-test.cc index 7fb9af14a..93c915af3 100644 --- a/src/click/test/ipv4-click-routing-test.cc +++ b/src/click/test/ipv4-click-routing-test.cc @@ -30,6 +30,17 @@ using namespace ns3; +/** + * \file + * \ingroup click-tests + * Click test suite. + */ + +/** + * Add Click Internet stack. + * + * \param node Node. + */ static void AddClickInternetStack(Ptr node) { @@ -38,6 +49,14 @@ AddClickInternetStack(Ptr node) internet.Install(node); } +/** + * Add network device. + * + * \param node Node. + * \param macaddr MAC address. + * \param ipv4addr IPv4 address. + * \param ipv4mask IPv4 mask. + */ static void AddNetworkDevice(Ptr node, Mac48Address macaddr, Ipv4Address ipv4addr, Ipv4Mask ipv4mask) { @@ -54,6 +73,10 @@ AddNetworkDevice(Ptr node, Mac48Address macaddr, Ipv4Address ipv4addr, Ipv ipv4->SetUp(netdev_idx); } +/** + * \ingroup click-tests + * Click interface ID from name test. + */ class ClickIfidFromNameTest : public TestCase { public: @@ -100,6 +123,10 @@ ClickIfidFromNameTest::DoRun() NS_TEST_EXPECT_MSG_EQ(ret, -1, "No eth1 on node"); } +/** + * \ingroup click-tests + * Click IP MAC address from name test. + */ class ClickIpMacAddressFromNameTest : public TestCase { public: @@ -160,6 +187,10 @@ ClickIpMacAddressFromNameTest::DoRun() delete[] buf; } +/** + * \ingroup click-tests + * Click trivial test. + */ class ClickTrivialTest : public TestCase { public: @@ -204,6 +235,10 @@ ClickTrivialTest::DoRun() delete[] buf; } +/** + * \ingroup click-tests + * Click interface ID from name test. + */ class ClickIfidFromNameTestSuite : public TestSuite { public: @@ -214,4 +249,7 @@ class ClickIfidFromNameTestSuite : public TestSuite AddTestCase(new ClickIfidFromNameTest, TestCase::QUICK); AddTestCase(new ClickIpMacAddressFromNameTest, TestCase::QUICK); } -} g_ipv4ClickRoutingTestSuite; +}; + +/// Static variable for test initialization +static ClickIfidFromNameTestSuite g_ipv4ClickRoutingTestSuite;