--- a/src/network/helper/application-container.h +++ a/src/network/helper/application-container.h @@ -64,6 +64,7 @@ */ ApplicationContainer (std::string name); + /// Application container iterator typedef std::vector >::const_iterator Iterator; /** @@ -209,7 +210,7 @@ void Stop (Time stop); private: - std::vector > m_applications; + std::vector > m_applications; //!< Applications smart pointers }; } // namespace ns3 --- a/src/network/helper/delay-jitter-estimation.cc +++ a/src/network/helper/delay-jitter-estimation.cc @@ -25,10 +25,20 @@ namespace ns3 { +/** + * Tag to perform Delay and Jitter estimations + * + * The tag holds the packet's creation timestamp + */ class DelayJitterEstimationTimestampTag : public Tag { public: DelayJitterEstimationTimestampTag (); + + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); virtual TypeId GetInstanceTypeId (void) const; @@ -37,9 +47,13 @@ virtual void Deserialize (TagBuffer i); virtual void Print (std::ostream &os) const; + /** + * \brief Get the Transmission time stored in the tag + * \return the transmission time + */ Time GetTxTime (void) const; private: - uint64_t m_creationTime; + uint64_t m_creationTime; //!< The time stored in the tag }; DelayJitterEstimationTimestampTag::DelayJitterEstimationTimestampTag () --- a/src/network/helper/delay-jitter-estimation.h +++ a/src/network/helper/delay-jitter-estimation.h @@ -69,10 +69,10 @@ uint64_t GetLastJitter (void) const; private: - Time m_previousRx; - Time m_previousRxTx; - int64x64_t m_jitter; - Time m_delay; + Time m_previousRx; //!< Previous Rx time + Time m_previousRxTx; //!< Previous Rx or Tx time + int64x64_t m_jitter; //!< Jitter estimation + Time m_delay; //!< Delay estimation }; } // namespace ns3 --- a/src/network/helper/net-device-container.h +++ a/src/network/helper/net-device-container.h @@ -41,6 +41,7 @@ class NetDeviceContainer { public: + /// NetDevice container iterator typedef std::vector >::const_iterator Iterator; /** @@ -195,7 +196,7 @@ void Add (std::string deviceName); private: - std::vector > m_devices; + std::vector > m_devices; //!< NetDevices smart pointers }; } // namespace ns3 --- a/src/network/helper/node-container.h +++ a/src/network/helper/node-container.h @@ -38,6 +38,7 @@ class NodeContainer { public: + /// Node container iterator typedef std::vector >::const_iterator Iterator; /** @@ -288,7 +289,7 @@ static NodeContainer GetGlobal (void); private: - std::vector > m_nodes; + std::vector > m_nodes; //!< Nodes smart pointers }; } // namespace ns3 --- a/src/network/helper/trace-helper.h +++ a/src/network/helper/trace-helper.h @@ -71,6 +71,7 @@ * @param prefix prefix string * @param device NetDevice * @param useObjectNames use node and device names instead of indexes + * @returns file name */ std::string GetFilenameFromDevice (std::string prefix, Ptr device, bool useObjectNames = true); @@ -82,6 +83,7 @@ * @param object interface (such as Ipv4Interface or Ipv6Interface) * @param interface interface id * @param useObjectNames use node and device names instead of indexes + * @returns file name */ std::string GetFilenameFromInterfacePair (std::string prefix, Ptr object, uint32_t interface, bool useObjectNames = true); @@ -94,6 +96,7 @@ * @param dataLinkType data link type of packet data * @param snapLen maximum length of packet data stored in records * @param tzCorrection time zone correction to be applied to timestamps of packets + * @returns a smart pointer to the Pcap file */ Ptr CreateFile (std::string filename, std::ios::openmode filemode, uint32_t dataLinkType, uint32_t snapLen = 65535, int32_t tzCorrection = 0); @@ -107,6 +110,15 @@ template void HookDefaultSink (Ptr object, std::string traceName, Ptr file); private: + /** + * The basic default trace sink. + * + * This one just writes the packet to the pcap + * file which is good enough for most kinds of captures. + * + * @param file the file to write to + * @param p the packet to write + */ static void DefaultSink (Ptr file, Ptr p); }; @@ -145,6 +157,7 @@ * @param prefix prefix string * @param device NetDevice * @param useObjectNames use node and device names instead of indexes + * @returns file name */ std::string GetFilenameFromDevice (std::string prefix, Ptr device, bool useObjectNames = true); @@ -156,6 +169,7 @@ * @param object interface (such as Ipv4Interface or Ipv6Interface) * @param interface interface id * @param useObjectNames use node and device names instead of indexes + * @returns file name */ std::string GetFilenameFromInterfacePair (std::string prefix, Ptr object, uint32_t interface, bool useObjectNames = true); @@ -182,6 +196,7 @@ * * @param filename file name * @param filemode file mode + * @returns a smart pointer to the output stream */ Ptr CreateFileStream (std::string filename, std::ios::openmode filemode = std::ios::out); @@ -282,16 +297,142 @@ void HookDefaultReceiveSinkWithContext (Ptr object, std::string context, std::string traceName, Ptr stream); + /** + * @brief Basic Enqueue default trace sink. + * + * When a packet has been sent to a device for transmission, the device is + * expected to place the packet onto a transmit queue even if it does not + * have to delay the packet at all, if only to trigger this event. This + * event will eventually translate into a '+' operation in the trace file. + * + * This is typically implemented by hooking the "TxQueue/Enqueue" trace hook + * in the device (actually the Queue in the device). + * + * @param file the output file + * @param p the packet + */ static void DefaultEnqueueSinkWithoutContext (Ptr file, Ptr p); + + /** + * @brief Basic Enqueue default trace sink. + * + * When a packet has been sent to a device for transmission, the device is + * expected to place the packet onto a transmit queue even if it does not + * have to delay the packet at all, if only to trigger this event. This + * event will eventually translate into a '+' operation in the trace file. + * + * This is typically implemented by hooking the "TxQueue/Enqueue" trace hook + * in the device (actually the Queue in the device). + * + * @param file the output file + * @param context the context + * @param p the packet + */ static void DefaultEnqueueSinkWithContext (Ptr file, std::string context, Ptr p); + /** + * @brief Basic Drop default trace sink. + * + * When a packet has been sent to a device for transmission, the device is + * expected to place the packet onto a transmit queue. If this queue is + * full the packet will be dropped. The device is expected to trigger an + * event to indicate that an outbound packet is being dropped. This event + * will eventually translate into a 'd' operation in the trace file. + * + * This is typically implemented by hooking the "TxQueue/Drop" trace hook + * in the device (actually the Queue in the device). + * + * @param file the output file + * @param p the packet + */ static void DefaultDropSinkWithoutContext (Ptr file, Ptr p); + + /** + * @brief Basic Drop default trace sink. + * + * When a packet has been sent to a device for transmission, the device is + * expected to place the packet onto a transmit queue. If this queue is + * full the packet will be dropped. The device is expected to trigger an + * event to indicate that an outbound packet is being dropped. This event + * will eventually translate into a 'd' operation in the trace file. + * + * This is typically implemented by hooking the "TxQueue/Drop" trace hook + * in the device (actually the Queue in the device). + * + * @param file the output file + * @param context the context + * @param p the packet + */ static void DefaultDropSinkWithContext (Ptr file, std::string context, Ptr p); + /** + * @brief Basic Dequeue default trace sink. + * + * When a packet has been sent to a device for transmission, the device is + * expected to place the packet onto a transmit queue even if it does not + * have to delay the packet at all. The device removes the packet from the + * transmit queue when the packet is ready to send, and this dequeue will + * fire a corresponding event. This event will eventually translate into a + * '-' operation in the trace file. + * + * This is typically implemented by hooking the "TxQueue/Dequeue" trace hook + * in the device (actually the Queue in the device). + * + * @param file the output file + * @param p the packet + */ static void DefaultDequeueSinkWithoutContext (Ptr file, Ptr p); + + /** + * @brief Basic Dequeue default trace sink. + * + * When a packet has been sent to a device for transmission, the device is + * expected to place the packet onto a transmit queue even if it does not + * have to delay the packet at all. The device removes the packet from the + * transmit queue when the packet is ready to send, and this dequeue will + * fire a corresponding event. This event will eventually translate into a + * '-' operation in the trace file. + * + * This is typically implemented by hooking the "TxQueue/Dequeue" trace hook + * in the device (actually the Queue in the device). + * + * @param file the output file + * @param context the context + * @param p the packet + */ static void DefaultDequeueSinkWithContext (Ptr file, std::string context, Ptr p); + /** + * @brief Basic Receive default trace sink. + * + * When a packet is received by a device for transmission, the device is + * expected to trigger this event to indicate the reception has occurred. + * This event will eventually translate into an 'r' operation in the trace + * file. + * + * This is typically implemented by hooking the "MacRx" trace hook in the + * device. + * + * @param file the output file + * @param p the packet + */ static void DefaultReceiveSinkWithoutContext (Ptr file, Ptr p); + + /** + * @brief Basic Receive default trace sink. + * + * When a packet is received by a device for transmission, the device is + * expected to trigger this event to indicate the reception has occurred. + * This event will eventually translate into an 'r' operation in the trace + * file. + * + * This is typically implemented by hooking the "MacRx" trace hook in the + * device. + * + * @param file the output file + * @param context the context + * @param p the packet + */ static void DefaultReceiveSinkWithContext (Ptr file, std::string context, Ptr p); }; @@ -562,7 +703,7 @@ * of the appropriate type. * * @param prefix Filename prefix to use for ascii files. - * @param d container of devices of type ns3::CsmaNetDevice + * @param d container of devices */ void EnableAscii (std::string prefix, NetDeviceContainer d); @@ -572,7 +713,7 @@ * * @param stream An OutputStreamWrapper representing an existing file to use * when writing trace data. - * @param d container of devices of type ns3::CsmaNetDevice + * @param d container of devices */ void EnableAscii (Ptr stream, NetDeviceContainer d); @@ -640,6 +781,19 @@ private: /** + * @brief Enable ascii trace output on the device specified by a global + * node-id (of a previously created node) and associated device-id (implementation) + * + * @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 nodeid The node identifier/number of the node on which to enable + * ascii tracing + * @param deviceid The device identifier/index of the device on which to enable + * ascii tracing + * @param explicitFilename Treat the prefix as an explicit filename if true + */ + /** * @internal Avoid code duplication. */ void EnableAsciiImpl (Ptr stream, @@ -649,22 +803,47 @@ bool explicitFilename); /** - * @internal Avoid code duplication. + * @brief Enable ascii trace output on each device (which is of the + * appropriate type) in the nodes provided in the container (implementation). + * + * @param stream An OutputStreamWrapper representing an existing file to use + * when writing trace data. + * @param prefix Filename prefix to use for ascii files. + * @param n container of nodes. */ void EnableAsciiImpl (Ptr stream, std::string prefix, NodeContainer n); /** - * @internal Avoid code duplication. + * @brief Enable ascii trace output on each device in the container which is + * of the appropriate type (implementation). + * + * @param stream An OutputStreamWrapper representing an existing file to use + * when writing trace data. + * @param prefix Filename prefix to use for ascii files. + * @param d container of devices */ void EnableAsciiImpl (Ptr stream, std::string prefix, NetDeviceContainer d); /** - * @internal Avoid code duplication. + * @brief Enable ascii trace output the indicated net device using a device + * previously named using the ns-3 object name service (implementation). + * + * @param stream An OutputStreamWrapper representing an existing file to use + * when writing trace data. + * @param prefix filename prefix to use for ascii files. + * @param ndName The name of the net device in which you want to enable tracing. + * @param explicitFilename Treat the prefix as an explicit filename if true */ void EnableAsciiImpl (Ptr stream, std::string prefix, std::string ndName, bool explicitFilename); /** - * @internal Avoid code duplication. + * @brief Enable ascii trace output the indicated net device (implementation). + * + * @param stream An OutputStreamWrapper representing an existing file to use + * when writing trace data. + * @param prefix filename prefix to use for ascii files. + * @param nd Net device for which you want to enable tracing + * @param explicitFilename Treat the prefix as an explicit filename if true */ void EnableAsciiImpl (Ptr stream, std::string prefix, Ptr nd, bool explicitFilename); }; --- a/src/network/model/address.cc +++ a/src/network/model/address.cc @@ -169,7 +169,7 @@ buffer.Read (m_data, m_len); } -ATTRIBUTE_HELPER_CPP (Address); /// Macro to make help make class an ns-3 attribute +ATTRIBUTE_HELPER_CPP (Address); //!< Macro to make help make class an ns-3 attribute bool operator == (const Address &a, const Address &b) @@ -248,14 +248,17 @@ return os; } +/** + * \brief Converts a string representing an hex number [0x0, 0xFF] into its value. + * + * \param v a string + * \returns the value + */ static uint8_t AsInt (std::string v) { NS_LOG_FUNCTION_NOARGS (); - std::istringstream iss; - iss.str (v); - uint8_t retval; - iss >> std::hex >> retval >> std::dec; + uint8_t retval = strtoul (v.c_str(), 0, 16); return retval; } --- a/src/network/model/address.h +++ a/src/network/model/address.h @@ -99,19 +99,29 @@ */ Address (); /** + * \brief Create an address from a type and a buffer. + * + * This constructor is typically invoked from the conversion + * functions of various address types when they have to + * convert themselves to an Address instance. + * * \param type the type of the Address to create * \param buffer a pointer to a buffer of bytes which hold * a serialized representation of the address in network * byte order. * \param len the length of the buffer. - * - * Create an address from a type and a buffer. This constructor - * is typically invoked from the conversion functions of various - * address types when they have to convert themselves to an - * Address instance. */ Address (uint8_t type, const uint8_t *buffer, uint8_t len); + /** + * \brief Create an address from another address. + * \param address the address to copy + */ Address (const Address & address); + /** + * \brief Basic assignment operator. + * \param address the address to copy + * \returns the address + */ Address &operator = (const Address &address); /** @@ -123,10 +133,12 @@ */ bool IsInvalid (void) const; /** + * \brief Get the length of the underlying address. * \returns the length of the underlying address. */ uint8_t GetLength (void) const; /** + * \brief Copy the address bytes into a buffer. * \param buffer buffer to copy the address bytes to. * \returns the number of bytes copied. */ @@ -209,14 +221,54 @@ void Deserialize (TagBuffer buffer); private: + /** + * \brief Equal to operator. + * + * \param a the first operand + * \param b the first operand + * \returns true if the operands are equal + */ friend bool operator == (const Address &a, const Address &b); + + /** + * \brief Not equal to operator. + * + * \param a the first operand + * \param b the first operand + * \returns true if the operands are not equal + */ + friend bool operator != (const Address &a, const Address &b); + + /** + * \brief Less than operator. + * + * \param a the first operand + * \param b the first operand + * \returns true if the operand a is less than operand b + */ friend bool operator < (const Address &a, const Address &b); + + /** + * \brief Stream insertion operator. + * + * \param os the stream + * \param address the address + * \returns a reference to the stream + */ friend std::ostream& operator<< (std::ostream& os, const Address & address); + + /** + * \brief Stream extraction operator. + * + * \param is the stream + * \param address the address + * \returns a reference to the stream + */ friend std::istream& operator>> (std::istream& is, Address & address); - uint8_t m_type; - uint8_t m_len; - uint8_t m_data[MAX_SIZE]; + uint8_t m_type; //!< Type of the address + uint8_t m_len; //!< Length of the address + uint8_t m_data[MAX_SIZE]; //!< The address value }; /** @@ -224,7 +276,7 @@ * \brief hold objects of type ns3::Address */ -ATTRIBUTE_HELPER_HEADER (Address); /// Macro to make help make class an ns-3 attribute +ATTRIBUTE_HELPER_HEADER (Address); //!< Macro to make help make class an ns-3 attribute bool operator == (const Address &a, const Address &b); bool operator != (const Address &a, const Address &b); --- a/src/network/model/application.h +++ a/src/network/model/application.h @@ -61,6 +61,10 @@ class Application : public Object { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); Application (); virtual ~Application (); @@ -123,11 +127,11 @@ virtual void DoDispose (void); virtual void DoInitialize (void); - Ptr m_node; /// The node that this application is installed on - Time m_startTime; /// The simulation time that the appliacation will start - Time m_stopTime; /// The simulation time that the appliacation will end - EventId m_startEvent; /// The event that will fire at m_startTime to start the application - EventId m_stopEvent; /// The event that will fire at m_stopTime to end the application + Ptr m_node; //!< The node that this application is installed on + Time m_startTime; //!< The simulation time that the application will start + Time m_stopTime; //!< The simulation time that the application will end + EventId m_startEvent; //!< The event that will fire at m_startTime to start the application + EventId m_stopEvent; //!< The event that will fire at m_stopTime to end the application }; } // namespace ns3 --- a/src/network/model/buffer.cc +++ a/src/network/model/buffer.cc @@ -30,6 +30,10 @@ namespace { +/** + * \ingroup packet + * \brief Zero-filled buffer. + */ static struct Zeroes { Zeroes () @@ -37,9 +41,9 @@ { memset (buffer, 0, size); } - char buffer[1000]; - const uint32_t size; -} g_zeroes; + char buffer[1000]; //!< buffer containing zero values + const uint32_t size; //!< buffer size +} g_zeroes; //!< Zero-filled buffer } --- a/src/network/model/buffer.h +++ a/src/network/model/buffer.h @@ -25,7 +25,7 @@ #include #include "ns3/assert.h" -#define noBUFFER_FREE_LIST 1 +#define BUFFER_FREE_LIST 1 namespace ns3 { @@ -80,7 +80,7 @@ * |--------^ m_start * |-------------------^ m_zeroAreaStart * |-----------------------------^ m_end - (m_zeroAreaEnd - m_zeroAreaStart) - * virtual byte buffer: |xxxxxxxxxxxx0000000000000.........| + * Virtual byte buffer: |xxxxxxxxxxxx0000000000000.........| * |--------^ m_start * |--------------------^ m_zeroAreaStart * |---------------------------------^ m_zeroAreaEnd @@ -378,37 +378,101 @@ private: friend class Buffer; + /** + * Constructor - initializes the iterator to point to the buffer start + * + * \param buffer the buffer this iterator refers to + */ inline Iterator (Buffer const*buffer); - inline Iterator (Buffer const*buffer, bool); + /** + * Constructor - initializes the iterator to point to the buffer end + * + * \param buffer the buffer this iterator refers to + * \param dummy not used param + */ + inline Iterator (Buffer const*buffer, bool dummy); + /** + * Initializes the iterator values + * + * \param buffer the buffer this iterator refers to + */ inline void Construct (const Buffer *buffer); + /** + * Checks that the [start, end) is not in the "virtual zero area". + * + * \param start start buffer position + * \param end end buffer position + * \returns true if [start, end) is not in the "virtual zero area". + */ bool CheckNoZero (uint32_t start, uint32_t end) const; + /** + * Checks that the buffer position is not in the "virtual zero area". + * + * \param i buffer position + * \returns true if not in the "virtual zero area". + */ bool Check (uint32_t i) const; + /** + * \return the two bytes read in the buffer. + * + * Read data and advance the Iterator by the number of bytes + * read. + * The data is read in network format and return in host format. + * + * \warning this is the slow version, please use ReadNtohU16 (void) + */ uint16_t SlowReadNtohU16 (void); + /** + * \return the four bytes read in the buffer. + * + * Read data and advance the Iterator by the number of bytes + * read. + * The data is read in network format and return in host format. + * + * \warning this is the slow version, please use ReadNtohU32 (void) + */ uint32_t SlowReadNtohU32 (void); + /** + * \brief Returns an appropriate message indicating a read error + * \returns the error message + */ std::string GetReadErrorMessage (void) const; + /** + * \brief Returns an appropriate message indicating a write error + * + * The message depends on the actual Buffer::Iterator status. + * + * \returns the error message + */ std::string GetWriteErrorMessage (void) const; - /* offset in virtual bytes from the start of the data buffer to the + /** + * offset in virtual bytes from the start of the data buffer to the * start of the "virtual zero area". */ uint32_t m_zeroStart; - /* offset in virtual bytes from the start of the data buffer to the + /** + * offset in virtual bytes from the start of the data buffer to the * end of the "virtual zero area". */ uint32_t m_zeroEnd; - /* offset in virtual bytes from the start of the data buffer to the + /** + * offset in virtual bytes from the start of the data buffer to the * start of the data which can be read by this iterator */ uint32_t m_dataStart; - /* offset in virtual bytes from the start of the data buffer to the + /** + * offset in virtual bytes from the start of the data buffer to the * end of the data which can be read by this iterator */ uint32_t m_dataEnd; - /* offset in virtual bytes from the start of the data buffer to the + /** + * offset in virtual bytes from the start of the data buffer to the * current position represented by this iterator. */ uint32_t m_current; - /* a pointer to the underlying byte buffer. All offsets are relative + /** + * a pointer to the underlying byte buffer. All offsets are relative * to this pointer. */ uint8_t *m_data; @@ -498,10 +562,17 @@ */ inline Buffer::Iterator End (void) const; + /** + * \brief Create a full copy of the buffer, including + * all the internal structures. + * + * \returns a copy of the buffer + */ Buffer CreateFullCopy (void) const; /** - * \return the number of bytes required for serialization + * \brief Return the number of bytes required for serialization. + * \return the number of bytes. */ uint32_t GetSerializedSize (void) const; @@ -527,7 +598,15 @@ */ uint32_t Deserialize (const uint8_t* buffer, uint32_t size); + /** + * \brief Returns the current buffer start offset + * \return the offset + */ int32_t GetCurrentStartOffset (void) const; + /** + * \brief Returns the current buffer end offset + * \return the offset + */ int32_t GetCurrentEndOffset (void) const; /** @@ -538,12 +617,44 @@ */ void CopyData (std::ostream *os, uint32_t size) const; + /** + * Copy the specified amount of data from the buffer to the given buffer. + * + * @param buffer the output buffer + * @param size the maximum amount of bytes to copy. If zero, nothing is copied. + * @returns the amount of bytes copied + */ uint32_t CopyData (uint8_t *buffer, uint32_t size) const; + /** + * \brief Copy constructor + * \param o the buffer to copy + */ inline Buffer (Buffer const &o); + /** + * \brief Assignment operator + * \param o the buffer to copy + * \return a reference to the buffer + */ Buffer &operator = (Buffer const &o); Buffer (); + /** + * \brief Constructor + * + * The buffer will be initialized with zeroes up to its size. + * + * \param dataSize the buffer size + */ Buffer (uint32_t dataSize); + /** + * \brief Constructor + * + * If initialize is set to true, the buffer will be initialized + * with zeroes up to its size. + * + * \param dataSize the buffer size. + * \param initialize initialize the buffer with zeroes. + */ Buffer (uint32_t dataSize, bool initialize); ~Buffer (); private: @@ -563,40 +674,92 @@ */ struct Data { - /* The reference count of an instance of this data structure. + /** + * The reference count of an instance of this data structure. * Each buffer which references an instance holds a count. - */ + */ uint32_t m_count; - /* the size of the m_data field below. + /** + * the size of the m_data field below. */ uint32_t m_size; - /* offset from the start of the m_data field below to the + /** + * offset from the start of the m_data field below to the * start of the area in which user bytes were written. */ uint32_t m_dirtyStart; - /* offset from the start of the m_data field below to the + /** + * offset from the start of the m_data field below to the * end of the area in which user bytes were written. */ uint32_t m_dirtyEnd; - /* The real data buffer holds _at least_ one byte. + /** + * The real data buffer holds _at least_ one byte. * Its real size is stored in the m_size field. */ uint8_t m_data[1]; }; + /** + * \brief Transform a "Virtual byte buffer" into a "Real byte buffer" + */ void TransformIntoRealBuffer (void) const; + /** + * \brief Checks the internal buffer structures consistency + * + * Used only for debugging purposes. + * + * \returns true if the buffer status is consistent. + */ bool CheckInternalState (void) const; + + /** + * \brief Initializes the buffer with a number of zeroes. + * + * \param zeroSize the zeroes size + */ void Initialize (uint32_t zeroSize); + + /** + * \brief Get the buffer real size. + * \warning The real size is the actual memory used by the buffer. + * \returns the memory used by the buffer. + */ uint32_t GetInternalSize (void) const; + + /** + * \brief Get the buffer end position. + * \returns the buffer end index. + */ uint32_t GetInternalEnd (void) const; + + /** + * \brief Recycle the buffer memory + * \param data the buffer data storage + */ static void Recycle (struct Buffer::Data *data); + /** + * \brief Create a buffer data storage + * \param size the storage size to create + * \returns a pointer to the created buffer storage + */ static struct Buffer::Data *Create (uint32_t size); + /** + * \brief Allocate a buffer data storage + * \param reqSize the storage size to create + * \returns a pointer to the allocated buffer storage + */ static struct Buffer::Data *Allocate (uint32_t reqSize); + /** + * \brief Deallocate the buffer memory + * \param data the buffer data storage + */ static void Deallocate (struct Buffer::Data *data); - struct Data *m_data; + struct Data *m_data; //!< the buffer data storage - /* keep track of the maximum value of m_zeroAreaStart across + /** + * keep track of the maximum value of m_zeroAreaStart across * the lifetime of a Buffer instance. This variable is used * purely as a source of information for the heuristics which * decide on the position of the zero area in new buffers. @@ -613,32 +776,38 @@ */ static uint32_t g_recommendedStart; - /* offset to the start of the virtual zero area from the start + /** + * offset to the start of the virtual zero area from the start * of m_data->m_data */ uint32_t m_zeroAreaStart; - /* offset to the end of the virtual zero area from the start + /** + * offset to the end of the virtual zero area from the start * of m_data->m_data */ uint32_t m_zeroAreaEnd; - /* offset to the start of the data referenced by this Buffer + /** + * offset to the start of the data referenced by this Buffer * instance from the start of m_data->m_data */ uint32_t m_start; - /* offset to the end of the data referenced by this Buffer + /** + * offset to the end of the data referenced by this Buffer * instance from the start of m_data->m_data */ uint32_t m_end; #ifdef BUFFER_FREE_LIST + /// Container for buffer data typedef std::vector FreeList; + /// Local static destructor structure struct LocalStaticDestructor { ~LocalStaticDestructor (); }; - static uint32_t g_maxSize; - static FreeList *g_freeList; - static struct LocalStaticDestructor g_localStaticDestructor; + static uint32_t g_maxSize; //!< Max observed data size + static FreeList *g_freeList; //!< Buffer data container + static struct LocalStaticDestructor g_localStaticDestructor; //!< Local static destructor #endif }; --- a/src/network/model/byte-tag-list.cc +++ a/src/network/model/byte-tag-list.cc @@ -30,20 +30,34 @@ namespace ns3 { +/** + * \ingroup packet + * + * \brief Internal representation of the byte tags stored in a packet. + * + * This structure is only used by ByteTagList and should not be accessed directly. + */ struct ByteTagListData { - uint32_t size; - uint32_t count; - uint32_t dirty; - uint8_t data[4]; + uint32_t size; //!< size of the data + uint32_t count; //!< use counter (for smart deallocation) + uint32_t dirty; //!< number of bytes actually in use + uint8_t data[4]; //!< data }; #ifdef USE_FREE_LIST +/** + * \ingroup packet + * + * \brief Container class for struct ByteTagListData + * + * Internal use only. + */ static class ByteTagListDataFreeList : public std::vector { public: ~ByteTagListDataFreeList (); -} g_freeList; -static uint32_t g_maxSize = 0; +} g_freeList; //!< Container for struct ByteTagListData +static uint32_t g_maxSize = 0; //!< maximum data size (used for allocation) ByteTagListDataFreeList::~ByteTagListDataFreeList () { --- a/src/network/model/byte-tag-list.h +++ a/src/network/model/byte-tag-list.h @@ -68,7 +68,7 @@ class ByteTagList { public: - /* + /** * \brief An iterator for iterating through a byte tag list * * An iterator for iterating through a byte tag list @@ -77,7 +77,7 @@ class Iterator { public: - /* + /** * \brief An item specifies an individual tag within a byte buffer * * An item specifies an individual tag within a byte buffer @@ -85,32 +85,32 @@ */ struct Item { - TypeId tid; /// type of the tag - uint32_t size; /// size of tag data - int32_t start; /// offset to the start of the tag from the virtual byte buffer - int32_t end; /// offset to the end of the tag from the virtual byte buffer - TagBuffer buf; /// the data for the tag as generated by Tag::Serialize - Item (TagBuffer buf); /// constructs an item with the given TagBuffer + TypeId tid; //!< type of the tag + uint32_t size; //!< size of tag data + int32_t start; //!< offset to the start of the tag from the virtual byte buffer + int32_t end; //!< offset to the end of the tag from the virtual byte buffer + TagBuffer buf; //!< the data for the tag as generated by Tag::Serialize + Item (TagBuffer buf); //!< constructs an item with the given TagBuffer private: friend class ByteTagList; friend class ByteTagList::Iterator; }; - /* + /** * \brief Used to determine if the iterator is at the end of the byteTagList * * \returns true if there are more Items in the list */ bool HasNext (void) const; - /* + /** * \brief Returns the next Item from the ByteTagList * * \returns the next Item in the ByteTagList */ struct ByteTagList::Iterator::Item Next (void); - /* + /** * \brief Returns the offset from the start of the virtual byte buffer to the ByteTagList * * \returns offset to the start of this ByteTagList @@ -118,16 +118,28 @@ uint32_t GetOffsetStart (void) const; private: friend class ByteTagList; + + /** + * \brief Constructor + * \param start Starting tag + * \param end End tag + * \param offsetStart offset to the start of the tag from the virtual byte buffer + * \param offsetEnd offset to the end of the tag from the virtual byte buffer + */ Iterator (uint8_t *start, uint8_t *end, int32_t offsetStart, int32_t offsetEnd); + + /** + * \brief Prepare the iterator for the next tag + */ void PrepareForNext (void); - uint8_t *m_current; - uint8_t *m_end; - int32_t m_offsetStart; - int32_t m_offsetEnd; - uint32_t m_nextTid; - uint32_t m_nextSize; - int32_t m_nextStart; - int32_t m_nextEnd; + uint8_t *m_current; //!< Current tag + uint8_t *m_end; //!< End tag + int32_t m_offsetStart; //!< Offset to the start of the tag from the virtual byte buffer + int32_t m_offsetEnd; //!< Offset to the end of the tag from the virtual byte buffer + uint32_t m_nextTid; //!< TypeId of the next tag + uint32_t m_nextSize; //!< Size of the next tag + int32_t m_nextStart; //!< Start of the next tag + int32_t m_nextEnd; //!< End of the next tag }; ByteTagList (); @@ -214,15 +226,41 @@ void AddAtStart (int32_t adjustment, int32_t prependOffset); private: + /** + * \brief Check that all offsets are smaller than appendOffset + * \param appendOffset the append offset to check + * \returns true if the check is false + */ bool IsDirtyAtEnd (int32_t appendOffset); + /** + * \brief Check that all offsets are bigger than prependOffset + * \param prependOffset the prepend offset to check + * \returns true if the check is false + */ bool IsDirtyAtStart (int32_t prependOffset); + + /** + * Returns an iterator pointing to the very first tag in this list + * + * \returns an iterator + */ ByteTagList::Iterator BeginAll (void) const; + /** + * \brief Allocate the memory for the ByteTagListData + * \param size the memory to allocate + * \returns the ByteTagListData structure + */ struct ByteTagListData *Allocate (uint32_t size); + + /** + * \brief Deallocates a ByteTagListData + * \param data the ByteTagListData to deallocate + */ void Deallocate (struct ByteTagListData *data); - uint16_t m_used; - struct ByteTagListData *m_data; + uint16_t m_used; //!< the number of used bytes in the buffer + struct ByteTagListData *m_data; //!< the ByteTagListData structure }; } // namespace ns3 --- a/src/network/model/channel-list.cc +++ a/src/network/model/channel-list.cc @@ -30,30 +30,76 @@ ; /** + * \ingroup network + * * \brief private implementation detail of the ChannelList API. */ class ChannelListPriv : public Object { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); ChannelListPriv (); ~ChannelListPriv (); + /** + * \param channel channel to add + * \returns index of channel in list. + * + * This method is called automatically from Channel::Channel so + * the user has little reason to call it himself. + */ uint32_t Add (Ptr channel); + /** + * \returns a C++ iterator located at the beginning of this + * list. + */ ChannelList::Iterator Begin (void) const; + /** + * \returns a C++ iterator located at the end of this + * list. + */ ChannelList::Iterator End (void) const; + /** + * \param n index of requested channel. + * \returns the Channel associated to index n. + */ Ptr GetChannel (uint32_t n); + + /** + * \returns the number of channels currently in the list. + */ uint32_t GetNChannels (void); + /** + * \brief Get the channel list object + * \returns the channel list + */ static Ptr Get (void); private: + /** + * \brief Get the channel list object + * \returns the channel list + */ static Ptr *DoGet (void); + + /** + * \brief Delete the channel list object + */ static void Delete (void); + + /** + * \brief Dispose the channels in the list + */ virtual void DoDispose (void); - std::vector > m_channels; + + std::vector > m_channels; //!< channel objects container }; NS_OBJECT_ENSURE_REGISTERED (ChannelListPriv) --- a/src/network/model/channel-list.h +++ a/src/network/model/channel-list.h @@ -38,6 +38,7 @@ class ChannelList { public: + /// Channel container iterator typedef std::vector< Ptr >::const_iterator Iterator; /** --- a/src/network/model/channel.h +++ a/src/network/model/channel.h @@ -43,6 +43,10 @@ class Channel : public Object { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); Channel (); @@ -71,7 +75,7 @@ virtual Ptr GetDevice (uint32_t i) const = 0; private: - uint32_t m_id; // Channel id for this channel + uint32_t m_id; //!< Channel id for this channel }; } // namespace ns3 --- a/src/network/model/chunk.h +++ a/src/network/model/chunk.h @@ -14,9 +14,23 @@ class Chunk : public ObjectBase { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); + /** + * \brief Deserialize the object from a buffer iterator + * \param start the buffer iterator + * \returns the number of deserialized bytes + */ virtual uint32_t Deserialize (Buffer::Iterator start) = 0; + + /** + * \brief Print the object contents + * \param os the output stream + */ virtual void Print (std::ostream &os) const = 0; }; --- a/src/network/model/header.h +++ a/src/network/model/header.h @@ -42,6 +42,10 @@ class Header : public Chunk { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); virtual ~Header (); /** @@ -91,6 +95,14 @@ virtual void Print (std::ostream &os) const = 0; }; + +/** + * \brief Stream insertion operator. + * + * \param os the stream + * \param header the header + * \returns a reference to the stream + */ std::ostream & operator << (std::ostream &os, const Header &header); } // namespace ns3 --- a/src/network/model/net-device.h +++ a/src/network/model/net-device.h @@ -75,6 +75,10 @@ class NetDevice : public Object { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); virtual ~NetDevice(); --- a/src/network/model/nix-vector.cc +++ a/src/network/model/nix-vector.cc @@ -27,7 +27,7 @@ namespace ns3 { -typedef std::vector NixBits_t; ///typedef for the nixVector +typedef std::vector NixBits_t; //!< typedef for the nixVector NixVector::NixVector () : m_nixVector (0), --- a/src/network/model/nix-vector.h +++ a/src/network/model/nix-vector.h @@ -152,38 +152,58 @@ private: + /// Typedef: the NixVector bits storage. typedef std::vector NixBits_t; + /** + * \brief Print the NixVector. + * + * \param os the output stream + */ /* for printing of nix-vector */ void DumpNixVector (std::ostream &os) const; - /* for printing of nix-vector */ - friend std::ostream & operator << ( std::ostream &outs, const NixVector &nix); - /* the actual nix-vector */ - NixBits_t m_nixVector; + /** + * \brief Stream insertion operator. + * + * \param os the stream + * \param nix the Nixvector + * \returns a reference to the stream + */ + friend std::ostream & operator << ( std::ostream &os, const NixVector &nix); - /* for tracking where we are - * in the nix-vector - */ - uint32_t m_used; + NixBits_t m_nixVector; //!< the actual nix-vector + uint32_t m_used; //!< For tracking where we are in the nix-vector - /* for tracking how many bits we + /** + * For tracking how many bits we * have used in the current vector * entry. need this in order to * expand the vector passed 32bits */ uint32_t m_currentVectorBitSize; - /* a counter of how total bits are in + /** + * A counter of how total bits are in * the nix-vector */ uint32_t m_totalBitSize; - /* internal for pretty printing of nix-vector */ - void PrintDec2BinNixFill (uint32_t, uint32_t, std::ostream &os) const; + /** + * Internal for pretty printing of nix-vector (fill) + * \param decimalNum decimal divider + * \param bitCount bit counter + * \param os output stream + */ + void PrintDec2BinNixFill (uint32_t decimalNum, uint32_t bitCount, std::ostream &os) const; - /* internal for pretty printing of nix-vector */ - void PrintDec2BinNix (uint32_t, uint32_t, std::ostream &os) const; + /** + * Internal for pretty printing of nix-vector (no fill) + * \param decimalNum decimal divider + * \param bitCount bit counter + * \param os output stream + */ + void PrintDec2BinNix (uint32_t decimalNum, uint32_t bitCount, std::ostream &os) const; }; } // namespace ns3 --- a/src/network/model/node-list.cc +++ a/src/network/model/node-list.cc @@ -33,28 +33,76 @@ ; /** + * \ingroup network * \brief private implementation detail of the NodeList API. */ class NodeListPriv : public Object { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); NodeListPriv (); ~NodeListPriv (); + /** + * \param node node to add + * \returns index of node in list. + * + * This method is called automatically from Node::Node so + * the user has little reason to call it himself. + */ uint32_t Add (Ptr node); + + /** + * \returns a C++ iterator located at the beginning of this + * list. + */ NodeList::Iterator Begin (void) const; + + /** + * \returns a C++ iterator located at the end of this + * list. + */ NodeList::Iterator End (void) const; + + /** + * \param n index of requested node. + * \returns the Node associated to index n. + */ Ptr GetNode (uint32_t n); + + /** + * \returns the number of nodes currently in the list. + */ uint32_t GetNNodes (void); + /** + * \brief Get the node list object + * \returns the node list + */ static Ptr Get (void); private: + /** + * \brief Get the node list object + * \returns the node list + */ + static Ptr *DoGet (void); + + /** + * \brief Delete the nodes list object + */ + static void Delete (void); + + /** + * \brief Dispose the nodes in the list + */ virtual void DoDispose (void); - static Ptr *DoGet (void); - static void Delete (void); - std::vector > m_nodes; + + std::vector > m_nodes; //!< node objects container }; NS_OBJECT_ENSURE_REGISTERED (NodeListPriv) --- a/src/network/model/node-list.h +++ a/src/network/model/node-list.h @@ -40,6 +40,7 @@ class NodeList { public: + /// Node container iterator typedef std::vector< Ptr >::const_iterator Iterator; /** --- a/src/network/model/node.cc +++ a/src/network/model/node.cc @@ -39,6 +39,9 @@ NS_OBJECT_ENSURE_REGISTERED (Node) ; +/** + * \brief A global switch to enable all checksums for all protocols. + */ GlobalValue g_checksumEnabled = GlobalValue ("ChecksumEnabled", "A global switch to enable all checksums for all protocols", BooleanValue (false), --- a/src/network/model/node.h +++ a/src/network/model/node.h @@ -55,6 +55,10 @@ class Node : public Object { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); Node(); @@ -175,7 +179,7 @@ * \param listener the listener to add * * Add a new listener to the list of listeners for the device-added - * event. When a new listener is added, it is notified of the existance + * event. When a new listener is added, it is notified of the existence * of all already-added devices to make discovery of devices easier. */ void RegisterDeviceAdditionListener (DeviceAdditionListener listener); @@ -204,30 +208,75 @@ virtual void DoDispose (void); virtual void DoInitialize (void); private: + + /** + * \brief Notifies all the DeviceAdditionListener about the new device added. + * \param device the added device to notify. + */ void NotifyDeviceAdded (Ptr device); - bool NonPromiscReceiveFromDevice (Ptr device, Ptr, uint16_t protocol, const Address &from); - bool PromiscReceiveFromDevice (Ptr device, Ptr, uint16_t protocol, + + /** + * \brief Receive a packet from a device in non-promiscuous mode. + * \param device the device + * \param packet the packet + * \param protocol the protocol + * \param from the sender + * \returns true if the packet has been delivered to a protocol handler. + */ + bool NonPromiscReceiveFromDevice (Ptr device, Ptr packet, uint16_t protocol, const Address &from); + /** + * \brief Receive a packet from a device in promiscuous mode. + * \param device the device + * \param packet the packet + * \param protocol the protocol + * \param from the sender + * \param to the destination + * \param packetType the packet type + * \returns true if the packet has been delivered to a protocol handler. + */ + bool PromiscReceiveFromDevice (Ptr device, Ptr packet, uint16_t protocol, const Address &from, const Address &to, NetDevice::PacketType packetType); + /** + * \brief Receive a packet from a device. + * \param device the device + * \param packet the packet + * \param protocol the protocol + * \param from the sender + * \param to the destination + * \param packetType the packet type + * \param promisc true if received in promiscuous mode + * \returns true if the packet has been delivered to a protocol handler. + */ bool ReceiveFromDevice (Ptr device, Ptr, uint16_t protocol, const Address &from, const Address &to, NetDevice::PacketType packetType, bool promisc); + /** + * \brief Finish node's construction by setting the correct node ID. + */ void Construct (void); + /** + * \brief Protocol handler entry. + * This structure is used to demultiplex all the protocols. + */ struct ProtocolHandlerEntry { - ProtocolHandler handler; - Ptr device; - uint16_t protocol; - bool promiscuous; + ProtocolHandler handler; //!< the protocol handler + Ptr device; //!< the NetDevice + uint16_t protocol; //!< the protocol number + bool promiscuous; //!< true if it is a promiscuous handler }; + + /// Typedef for protocol handlers container typedef std::vector ProtocolHandlerList; + /// Typedef for NetDevice addition listeners container typedef std::vector DeviceAdditionListenerList; - uint32_t m_id; // Node id for this node - uint32_t m_sid; // System id for this node - std::vector > m_devices; - std::vector > m_applications; - ProtocolHandlerList m_handlers; - DeviceAdditionListenerList m_deviceAdditionListeners; + uint32_t m_id; //!< Node id for this node + uint32_t m_sid; //!< System id for this node + std::vector > m_devices; //!< Devices associated to this node + std::vector > m_applications; //!< Applications associated to this node + ProtocolHandlerList m_handlers; //!< Protocol handlers in the node + DeviceAdditionListenerList m_deviceAdditionListeners; //!< Device addition listeners in the node }; } // namespace ns3 --- a/src/network/model/packet-metadata.cc +++ a/src/network/model/packet-metadata.cc @@ -447,12 +447,6 @@ return n; } -/** - * \param item the item data to write - * \param extraItem the extra item data to write - * \param available the number of bytes which can - * be written without having to rewrite the buffer entirely. - */ void PacketMetadata::ReplaceTail (PacketMetadata::SmallItem *item, PacketMetadata::ExtraItem *extraItem, @@ -530,12 +524,7 @@ *this = h; } -/** - * \param current the offset we should start reading the data from - * \param item pointer to where we should store the data to return to the caller - * \param extraItem pointer to where we should store the data to return to the caller - * \returns the number of bytes read. - */ + uint32_t PacketMetadata::ReadItems (uint16_t current, struct PacketMetadata::SmallItem *item, --- a/src/network/model/packet-metadata.h +++ a/src/network/model/packet-metadata.h @@ -79,132 +79,311 @@ class PacketMetadata { public: + + /** + * \brief structure describing a packet metadata item + */ struct Item { enum { PAYLOAD, HEADER, TRAILER - } type; - /* true: this is a fragmented header, trailer, or, payload. + } type; //!< metadata type + /** + * true: this is a fragmented header, trailer, or, payload. * false: this is a whole header, trailer, or, payload. */ bool isFragment; - /* TypeId of Header or Trailer. Valid only if type is + /** + * TypeId of Header or Trailer. Valid only if type is * header or trailer. */ TypeId tid; - /* size of item. If fragment, size of fragment. Otherwise, + /** + * size of item. If fragment, size of fragment. Otherwise, * size of original item. */ uint32_t currentSize; - /* how many bytes were trimed from the start of a fragment. + /** + * how many bytes were trimed from the start of a fragment. * if isFragment is true, this field is zero. */ uint32_t currentTrimedFromStart; - /* how many bytes were trimed from the end of a fragment. + /** + * how many bytes were trimed from the end of a fragment. * if isFragment is true, this field is zero. */ uint32_t currentTrimedFromEnd; - /* an iterator which can be fed to Deserialize. Valid only + /** + * an iterator which can be fed to Deserialize. Valid only * if isFragment and isPayload are false. */ Buffer::Iterator current; }; + + /** + * \brief Iterator class for metadata items. + */ class ItemIterator { public: + /** + * Constructor + * \param metadata a pointer to the metadata + * \param buffer the buffer the metadata refers to + */ ItemIterator (const PacketMetadata *metadata, Buffer buffer); + /** + * \brief Checks if there is another metadata item + * \returns true if there is another item + */ bool HasNext (void) const; + /** + * \brief Retrieve the next metadata item + * \returns the next metadata item + */ Item Next (void); private: - const PacketMetadata *m_metadata; - Buffer m_buffer; - uint16_t m_current; - uint32_t m_offset; - bool m_hasReadTail; + const PacketMetadata *m_metadata; //!< pointer to the metadata + Buffer m_buffer; //!< buffer the metadata refers to + uint16_t m_current; //!< current position + uint32_t m_offset; //!< offset + bool m_hasReadTail; //!< true if the metadata tail has been read }; + /** + * \brief Enable the packet metadata + */ static void Enable (void); + /** + * \brief Enable the packet metadata checking + */ static void EnableChecking (void); + /** + * Constructor + * \param uid packet uid + * \param size size of the header + */ inline PacketMetadata (uint64_t uid, uint32_t size); + /** + * Copy constructor + * \param o the object to copy + */ inline PacketMetadata (PacketMetadata const &o); + /** + * Basic assignment + * \param o the object to copy + * \return a copied object + */ inline PacketMetadata &operator = (PacketMetadata const& o); inline ~PacketMetadata (); + /** + * Add an header + * \param header header to add + * \param size header serialized size + */ void AddHeader (Header const &header, uint32_t size); + /** + * Remove an header + * \param header header to remove + * \param size header serialized size + */ void RemoveHeader (Header const &header, uint32_t size); + /** + * Add a trailer + * \param trailer trailer to add + * \param size trailer serialized size + */ void AddTrailer (Trailer const &trailer, uint32_t size); + /** + * Remove a trailer + * \param trailer trailer to remove + * \param size trailer serialized size + */ void RemoveTrailer (Trailer const &trailer, uint32_t size); /** * \param start the amount of stuff to remove from the start * \param end the amount of stuff to remove from the end + * \return the fragment's metadata * * Calling this method is equivalent to calling RemoveAtStart (start) * and then, RemoveAtEnd (end). */ PacketMetadata CreateFragment (uint32_t start, uint32_t end) const; + + /** + * Add a metadata at the metadata start + * \param o the metadata to add + */ void AddAtEnd (PacketMetadata const&o); + /** + * Add some padding at the end + * \param end size of padding + */ void AddPaddingAtEnd (uint32_t end); + /** + * Remove a chunk of metadata at the metadata start + * \param start the size of metadata to remove + */ void RemoveAtStart (uint32_t start); + /** + * Remove a chunk of metadata at the metadata end + * \param end the size of metadata to remove + */ void RemoveAtEnd (uint32_t end); + /** + * Get the packet Uid + * \return the packet Uid + */ uint64_t GetUid (void) const; + /** + * Get the metadata serialized size + * \return the seralized size + */ uint32_t GetSerializedSize (void) const; + /** + * Initialize the item iterator to the buffer begin + */ ItemIterator BeginItem (Buffer buffer) const; - // Serialization to/from raw uint8_t* + /** + * Serialization to raw uint8_t* + * \param buffer the buffer to serialize to + * \param maxSize the maximum serialization size + * \return 1 on success, 0 on failure + */ uint32_t Serialize (uint8_t* buffer, uint32_t maxSize) const; + /** + * Deserialization from raw uint8_t* + * \param buffer the buffer to deserialize from + * \param size the size + * \return 1 on success, 0 on failure + */ uint32_t Deserialize (const uint8_t* buffer, uint32_t size); private: - // Helper for the raw serilization/deserialization + /** + * Helper for the raw serilization + * \param data the buffer to write to + * \param start start index + * \param current current index + * \param maxSize maximum size + * \return updated current index + */ static uint8_t* AddToRawU8 (const uint8_t& data, uint8_t* start, uint8_t* current, uint32_t maxSize); + /** + * Helper for the raw serilization + * \param data the buffer to write to + * \param start start index + * \param current current index + * \param maxSize maximum size + * \return updated current index + */ static uint8_t* AddToRawU16 (const uint16_t& data, uint8_t* start, uint8_t* current, uint32_t maxSize); + /** + * Helper for the raw serilization + * \param data the buffer to write to + * \param start start index + * \param current current index + * \param maxSize maximum size + * \return updated current index + */ static uint8_t* AddToRawU32 (const uint32_t& data, uint8_t* start, uint8_t* current, uint32_t maxSize); + /** + * Helper for the raw serilization + * \param data the buffer to write to + * \param start start index + * \param current current index + * \param maxSize maximum size + * \return updated current index + */ static uint8_t* AddToRawU64 (const uint64_t& data, uint8_t* start, uint8_t* current, uint32_t maxSize); + /** + * Helper for the raw serilization + * \param data the buffer to write to + * \param dataSize the data size to write to + * \param start start index + * \param current current index + * \param maxSize maximum size + * \return updated current index + */ static uint8_t* AddToRaw (const uint8_t* data, uint32_t dataSize, uint8_t* start, uint8_t* current, uint32_t maxSize); + /** + * Helper for the raw deserilization + * \param data the buffer to read from + * \param start start index + * \param current current index + * \param maxSize maximum size + * \return updated current index + */ static uint8_t* ReadFromRawU8 (uint8_t& data, const uint8_t* start, const uint8_t* current, uint32_t maxSize); + /** + * Helper for the raw deserilization + * \param data the buffer to read from + * \param start start index + * \param current current index + * \param maxSize maximum size + * \return updated current index + */ static uint8_t* ReadFromRawU16 (uint16_t& data, const uint8_t* start, const uint8_t* current, uint32_t maxSize); + /** + * Helper for the raw deserilization + * \param data the buffer to read from + * \param start start index + * \param current current index + * \param maxSize maximum size + * \return updated current index + */ static uint8_t* ReadFromRawU32 (uint32_t& data, const uint8_t* start, const uint8_t* current, uint32_t maxSize); + /** + * Helper for the raw deserilization + * \param data the buffer to read from + * \param start start index + * \param current current index + * \param maxSize maximum size + * \return updated current index + */ static uint8_t* ReadFromRawU64 (uint64_t& data, const uint8_t* start, const uint8_t* current, @@ -216,15 +395,18 @@ */ #define PACKET_METADATA_DATA_M_DATA_SIZE 8 + /** + * Data structure + */ struct Data { - /* number of references to this struct Data instance. */ + /** number of references to this struct Data instance. */ uint32_t m_count; - /* size (in bytes) of m_data buffer below */ + /** size (in bytes) of m_data buffer below */ uint16_t m_size; - /* max of the m_used field over all objects which + /** max of the m_used field over all objects which * reference this struct Data instance */ uint16_t m_dirtyEnd; - /* variable-sized buffer of bytes */ + /** variable-sized buffer of bytes */ uint8_t m_data[PACKET_METADATA_DATA_M_DATA_SIZE]; }; /* Note that since the next and prev fields are 16 bit integers @@ -233,20 +415,23 @@ only a limited number of elements can be stored in a m_data byte buffer. */ + /** + * SmallItem structure + */ struct SmallItem { - /* offset (in bytes) from start of m_data buffer + /** offset (in bytes) from start of m_data buffer to next element in linked list. value is 0xffff if next element does not exist. stored as a fixed-size 16 bit integer. */ uint16_t next; - /* offset (in bytes) from start of m_data buffer + /** offset (in bytes) from start of m_data buffer to previous element in linked list. value is 0xffff if previous element does not exist. stored as a fixed-size 16 bit integer. */ uint16_t prev; - /* the high 31 bits of this field identify the + /** the high 31 bits of this field identify the type of the header or trailer represented by this item: the value zero represents payload. If the low bit of this uid is one, an ExtraItem @@ -254,12 +439,12 @@ stored as a variable-size 32 bit integer. */ uint32_t typeUid; - /* the size (in bytes) of the header or trailer represented + /** the size (in bytes) of the header or trailer represented by this element. stored as a variable-size 32 bit integer. */ uint32_t size; - /* this field tries to uniquely identify each header or + /** this field tries to uniquely identify each header or trailer _instance_ while the typeUid field uniquely identifies each header or trailer _type_. This field is used to test whether two items are equal in the sense @@ -273,18 +458,22 @@ */ uint16_t chunkUid; }; + + /** + * ExtraItem structure + */ struct ExtraItem { - /* offset (in bytes) from start of original header to + /** offset (in bytes) from start of original header to the start of the fragment still present. stored as a variable-size 32 bit integer. */ uint32_t fragmentStart; - /* offset (in bytes) from start of original header to + /** offset (in bytes) from start of original header to the end of the fragment still present. stored as a variable-size 32 bit integer. */ uint32_t fragmentEnd; - /* the packetUid of the packet in which this header or trailer + /** the packetUid of the packet in which this header or trailer was first added. It could be different from the m_packetUid field if the user has aggregated multiple packets into one. stored as a fixed-size 64 bit integer. @@ -292,6 +481,9 @@ uint64_t packetUid; }; + /** + * Class to hold all the metadata + */ class DataFreeList : public std::vector { public: @@ -303,60 +495,181 @@ PacketMetadata (); + /** + * Add a SmallItem + * \param item the SmallItem to add + * \return added size + */ inline uint16_t AddSmall (const PacketMetadata::SmallItem *item); + /** + * Add a "Big" Item (a SmallItem plus an ExtraItem) + * \param head the head + * \param tail the tail + * \param item the SmallItem to add + * \param extraItem the ExtraItem to add + * \return added size + */ uint16_t AddBig (uint32_t head, uint32_t tail, const PacketMetadata::SmallItem *item, const PacketMetadata::ExtraItem *extraItem); + /** + * Replace the tail + * \param item the item data to write + * \param extraItem the extra item data to write + * \param available the number of bytes which can + * be written without having to rewrite the buffer entirely. + */ void ReplaceTail (PacketMetadata::SmallItem *item, PacketMetadata::ExtraItem *extraItem, uint32_t available); + /** + * Update the head + * \param written the used bytes + */ inline void UpdateHead (uint16_t written); + /** + * Update the tail + * \param written the used bytes + */ inline void UpdateTail (uint16_t written); + + /** + * Get the ULEB128 (Unsigned Little Endian Base 128) size + * \param value the value + * \returns the value's ULEB128 size + */ inline uint32_t GetUleb128Size (uint32_t value) const; + /** + * Read a ULEB128 (Unsigned Little Endian Base 128) coded number + * \param pBuffer the buffer to read from + * \returns the value + */ uint32_t ReadUleb128 (const uint8_t **pBuffer) const; + /** + * Append a 16-bit value to the buffer + * \param value the value to add + * \param buffer the buffer to write to + */ inline void Append16 (uint16_t value, uint8_t *buffer); + /** + * Append a 32-bit value to the buffer + * \param value the value to add + * \param buffer the buffer to write to + */ inline void Append32 (uint32_t value, uint8_t *buffer); + /** + * Append a value to the buffer + * \param value the value to add + * \param buffer the buffer to write to + */ inline void AppendValue (uint32_t value, uint8_t *buffer); + /** + * \brief Append a value to the buffer - extra + * + * This function is called by AppendValue + * + * \param value the value to add + * \param buffer the buffer to write to + */ void AppendValueExtra (uint32_t value, uint8_t *buffer); + + /** + * Reserve space + * \param n space to reserve + */ inline void Reserve (uint32_t n); + /** + * Reserve space and make a metadata copy + * \param n space to reserve + */ void ReserveCopy (uint32_t n); + + /** + * Get the total size used by the metadata + */ uint32_t GetTotalSize (void) const; + + /** + * Read items + * \param current the offset we should start reading the data from + * \param item pointer to where we should store the data to return to the caller + * \param extraItem pointer to where we should store the data to return to the caller + * \returns the number of bytes read. + */ uint32_t ReadItems (uint16_t current, struct PacketMetadata::SmallItem *item, struct PacketMetadata::ExtraItem *extraItem) const; + /** + * Add an header + * \param uid header's uid to add + * \param size header serialized size + */ void DoAddHeader (uint32_t uid, uint32_t size); + /** + * Check if the metadata state is ok + * \returns true if the internal state is ok + */ bool IsStateOk (void) const; + /** + * Check if the position is valid + * \param pointer the position to check + * \returns true if the position is valid + */ bool IsPointerOk (uint16_t pointer) const; + /** + * Check if the position is valid + * \param pointer the position to check + * \returns true if the position is valid + */ bool IsSharedPointerOk (uint16_t pointer) const; - + /** + * \brief Recycle the buffer memory + * \param data the buffer data storage + */ + static void Recycle (struct PacketMetadata::Data *data); + /** + * \brief Create a buffer data storage + * \param size the storage size to create + * \returns a pointer to the created buffer storage + */ static struct PacketMetadata::Data *Create (uint32_t size); - static void Recycle (struct PacketMetadata::Data *data); + /** + * \brief Allocate a buffer data storage + * \param n the storage size to create + * \returns a pointer to the allocated buffer storage + */ static struct PacketMetadata::Data *Allocate (uint32_t n); + /** + * \brief Deallocate the buffer memory + * \param data the buffer data storage + */ static void Deallocate (struct PacketMetadata::Data *data); - static DataFreeList m_freeList; - static bool m_enable; - static bool m_enableChecking; + static DataFreeList m_freeList; //!< the metadata data storage + static bool m_enable; //!< Enable the packet metadata + static bool m_enableChecking; //!< Enable the packet metadata checking - // set to true when adding metadata to a packet is skipped because - // m_enable is false; used to detect enabling of metadata in the - // middle of a simulation, which isn't allowed. + /** + * Set to true when adding metadata to a packet is skipped because + * m_enable is false; used to detect enabling of metadata in the + * middle of a simulation, which isn't allowed. + */ static bool m_metadataSkipped; - static uint32_t m_maxSize; - static uint16_t m_chunkUid; + static uint32_t m_maxSize; //!< maximum metadata size + static uint16_t m_chunkUid; //!< Chunk Uid - struct Data *m_data; - /** + struct Data *m_data; //!< Metadata storage + /* head -(next)-> tail ^ | \---(prev)---| */ - uint16_t m_head; - uint16_t m_tail; - uint16_t m_used; - uint64_t m_packetUid; + uint16_t m_head; //!< list head + uint16_t m_tail; //!< list tail + uint16_t m_used; //!< used portion + uint64_t m_packetUid; //!< packet Uid }; } // namespace ns3 --- a/src/network/model/packet-tag-list.h +++ a/src/network/model/packet-tag-list.h @@ -184,6 +184,7 @@ * Assignment * * \param [in] o The PacketTagList to copy. + * \returns the copied object * * This makes a light-weight copy by #RemoveAll, then * pointing to the same \ref TagData as \pname{o}. --- a/src/network/model/packet.h +++ a/src/network/model/packet.h @@ -84,11 +84,19 @@ void GetTag (Tag &tag) const; private: friend class ByteTagIterator; + /** + * Constructor + * \param tid the ns3::TypeId associated to this tag. + * \param start the index of the first byte tagged by this tag. + * \param end the index of the last byte tagged by this tag. + * \param buffer the buffer associated with this tag. + */ Item (TypeId tid, uint32_t start, uint32_t end, TagBuffer buffer); - TypeId m_tid; - uint32_t m_start; - uint32_t m_end; - TagBuffer m_buffer; + + TypeId m_tid; //!< the ns3::TypeId associated to this tag. + uint32_t m_start; //!< the index of the first byte tagged by this tag. + uint32_t m_end; //!< the index of the last byte tagged by this tag. + TagBuffer m_buffer; //!< the buffer associated with this tag. }; /** * \returns true if calling Next is safe, false otherwise. @@ -100,8 +108,12 @@ Item Next (void); private: friend class Packet; + /** + * Copy Constructor + * \param i object to copy + */ ByteTagIterator (ByteTagList::Iterator i); - ByteTagList::Iterator m_current; + ByteTagList::Iterator m_current; //!< actual position over the set of byte tags in a packet }; /** @@ -134,8 +146,12 @@ void GetTag (Tag &tag) const; private: friend class PacketTagIterator; + /** + * Constructor + * \param data the data to copy. + */ Item (const struct PacketTagList::TagData *data); - const struct PacketTagList::TagData *m_data; + const struct PacketTagList::TagData *m_data; //!< the tag data }; /** * \returns true if calling Next is safe, false otherwise. @@ -147,8 +163,12 @@ Item Next (void); private: friend class Packet; + /** + * Constructor + * \param head head of the items + */ PacketTagIterator (const struct PacketTagList::TagData *head); - const struct PacketTagList::TagData *m_current; + const struct PacketTagList::TagData *m_current; //!< actual position over the set of tags in a packet }; /** @@ -209,7 +229,16 @@ * by getUid). */ Packet (); + /** + * Copy constructor + * \param o object to copy + */ Packet (const Packet &o); + /** + * Basic assignment + * \param o object to copy + * \return the copied object + */ Packet &operator = (const Packet &o); /** * Create a packet with a zero-filled payload. @@ -569,32 +598,50 @@ * with a packet. This design methodology * should _not_ be followed, and is only here as an * impetus to fix this general issue. + * + * \param nixVector the nix vector */ - void SetNixVector (Ptr); + void SetNixVector (Ptr nixVector); /** * Get the packet nix-vector. * * See the comment on SetNixVector + * + * \returns the Nix vector */ Ptr GetNixVector (void) const; private: + /** + * Constructor + * \param buffer the packet buffer + * \param byteTagList the ByteTag list + * \param packetTagList the packet's Tag list + * \param metadata the packet's metadata + */ Packet (const Buffer &buffer, const ByteTagList &byteTagList, const PacketTagList &packetTagList, const PacketMetadata &metadata); uint32_t Deserialize (uint8_t const*buffer, uint32_t size); - Buffer m_buffer; - ByteTagList m_byteTagList; - PacketTagList m_packetTagList; - PacketMetadata m_metadata; + Buffer m_buffer; //!< the packet buffer (it's actual contents) + ByteTagList m_byteTagList; //!< the ByteTag list + PacketTagList m_packetTagList; //!< the packet's Tag list + PacketMetadata m_metadata; //!< the packet's metadata /* Please see comments above about nix-vector */ - Ptr m_nixVector; + Ptr m_nixVector; //!< the packet's Nix vector - static uint32_t m_globalUid; + static uint32_t m_globalUid; //!< Global counter of packets Uid }; +/** + * \brief Stream insertion operator. + * + * \param os the stream + * \param packet the packet + * \returns a reference to the stream + */ std::ostream& operator<< (std::ostream& os, const Packet &packet); /** --- a/src/network/model/socket-factory.h +++ a/src/network/model/socket-factory.h @@ -48,6 +48,10 @@ class SocketFactory : public Object { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); SocketFactory (); --- a/src/network/model/tag-buffer.h +++ a/src/network/model/tag-buffer.h @@ -51,8 +51,24 @@ class TagBuffer { public: + + /** + * \brief Constructor + * \param start start position + * \param end end position + */ TagBuffer (uint8_t *start, uint8_t *end); + + /** + * \brief Trim some space from the end + * \param trim space to remove + */ void TrimAtEnd (uint32_t trim); + + /** + * \brief Copy the nternal structure of another TagBuffer + * \param o the TagBuffer to copy from + */ void CopyFrom (TagBuffer o); /** @@ -140,8 +156,8 @@ void Read (uint8_t *buffer, uint32_t size); private: - uint8_t *m_current; - uint8_t *m_end; + uint8_t *m_current; //!< current TagBuffer position + uint8_t *m_end; //!< end TagBuffer position }; } // namespace ns3 --- a/src/network/model/tag.h +++ a/src/network/model/tag.h @@ -36,6 +36,10 @@ class Tag : public ObjectBase { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); /** --- a/src/network/model/trailer.h +++ a/src/network/model/trailer.h @@ -40,6 +40,10 @@ class Trailer : public Chunk { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); virtual ~Trailer (); /** @@ -93,6 +97,13 @@ virtual void Print (std::ostream &os) const = 0; }; +/** + * \brief Stream insertion operator. + * + * \param os the stream + * \param trailer the trailer + * \returns a reference to the stream + */ std::ostream & operator << (std::ostream &os, const Trailer &trailer); } // namespace ns3 --- a/src/network/utils/ascii-file.h +++ a/src/network/utils/ascii-file.h @@ -85,8 +85,8 @@ uint64_t & lineNumber); private: - std::string m_filename; - std::fstream m_file; + std::string m_filename; //!< output file name + std::fstream m_file; //!< output file }; } // namespace ns3 --- a/src/network/utils/crc32.cc +++ a/src/network/utils/crc32.cc @@ -29,6 +29,9 @@ namespace ns3 { +/** + * Table of CRC-32 values. + */ static uint32_t crc32table[256] = { 0x00000000,0x77073096,0xEE0E612C,0x990951BA,0x076DC419,0x706AF48F,0xE963A535,0x9E6495A3, 0x0EDB8832,0x79DCB8A4,0xE0D5E91E,0x97D2D988,0x09B64C2B,0x7EB17CBD,0xE7B82D07,0x90BF1D91, --- a/src/network/utils/crc32.h +++ a/src/network/utils/crc32.h @@ -24,9 +24,11 @@ namespace ns3 { /** + * Calculates the CRC-32 for a given input + * * \param data buffer to calculate the checksum for * \param length the length of the buffer (bytes) - * \returns the computed crc. + * \returns the computed crc-32. * */ uint32_t CRC32Calculate (const uint8_t *data, int length); --- a/src/network/utils/data-rate.cc +++ a/src/network/utils/data-rate.cc @@ -182,7 +182,7 @@ namespace ns3 { -ATTRIBUTE_HELPER_CPP (DataRate); /// Macro to make help make data-rate an ns-3 attribute +ATTRIBUTE_HELPER_CPP (DataRate); //!< Macro to make help make data-rate an ns-3 attribute DataRate::DataRate () : m_bps (0) @@ -269,26 +269,11 @@ return is; } -/** - * \brief Multiply datarate by a time value - * - * Calculates the number of bits that have been transmitted over a period of time - * \param lhs rate - * \param rhs time - * \return the number of bits over the period of time - */ double operator* (const DataRate& lhs, const Time& rhs) { return rhs.GetSeconds ()*lhs.GetBitRate (); } -/** - * \brief Multiply time value by a data rate - * - * Calculates the number of bits that have been transmitted over a period of time - * \param lhs time - * \param rhs rate - * \return the number of bits over the period of time - */ + double operator* (const Time& lhs, const DataRate& rhs) { return lhs.GetSeconds ()*rhs.GetBitRate (); --- a/src/network/utils/data-rate.h +++ a/src/network/utils/data-rate.h @@ -159,11 +159,25 @@ uint64_t GetBitRate () const; private: - uint64_t m_bps; - static uint64_t Parse (const std::string); + uint64_t m_bps; //!< data rate [bps] }; +/** + * \brief Stream insertion operator. + * + * \param os the stream + * \param rate the data rate + * \returns a reference to the stream + */ std::ostream &operator << (std::ostream &os, const DataRate &rate); + +/** + * \brief Stream extraction operator. + * + * \param is the stream + * \param rate the data rate + * \returns a reference to the stream + */ std::istream &operator >> (std::istream &is, DataRate &rate); /** @@ -172,16 +186,29 @@ */ -ATTRIBUTE_HELPER_HEADER (DataRate); /// Macro to make help make data-rate an ns-3 attribute +ATTRIBUTE_HELPER_HEADER (DataRate); //!< Macro to make help make data-rate an ns-3 attribute + /** - * \param lhs - * \param rhs - * \return Bits transmitted in rhs seconds at lhs b/s + * \brief Multiply datarate by a time value + * + * Calculates the number of bits that have been transmitted over a period of time + * \param lhs rate + * \param rhs time + * \return the number of bits over the period of time */ double operator* (const DataRate& lhs, const Time& rhs); +/** + * \brief Multiply time value by a data rate + * + * Calculates the number of bits that have been transmitted over a period of time + * \param lhs time + * \param rhs rate + * \return the number of bits over the period of time + */ double operator* (const Time& lhs, const DataRate& rhs); + } // namespace ns3 #endif /* DATA_RATE_H */ --- a/src/network/utils/drop-tail-queue.h +++ a/src/network/utils/drop-tail-queue.h @@ -34,6 +34,10 @@ */ class DropTailQueue : public Queue { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); /** * \brief DropTailQueue Constructor @@ -64,11 +68,11 @@ virtual Ptr DoDequeue (void); virtual Ptr DoPeek (void) const; - std::queue > m_packets; - uint32_t m_maxPackets; - uint32_t m_maxBytes; - uint32_t m_bytesInQueue; - QueueMode m_mode; + std::queue > m_packets; //!< the packets in the queue + uint32_t m_maxPackets; //!< max packets in the queue + uint32_t m_maxBytes; //!< max bytes in the queue + uint32_t m_bytesInQueue; //!< actual bytes in the queue + QueueMode m_mode; //!< queue mode (packets or bytes limited) }; } // namespace ns3 --- a/src/network/utils/error-model.h +++ a/src/network/utils/error-model.h @@ -115,6 +115,10 @@ class ErrorModel : public Object { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); ErrorModel (); @@ -146,13 +150,18 @@ bool IsEnabled (void) const; private: - /* - * These methods must be implemented by subclasses + /** + * Corrupt a packet according to the specified model. + * \param p the packet to corrupt + * \returns true if the packet is corrupted */ - virtual bool DoCorrupt (Ptr) = 0; + virtual bool DoCorrupt (Ptr p) = 0; + /** + * Re-initialize any state + */ virtual void DoReset (void) = 0; - bool m_enable; + bool m_enable; //!< True if the error model is enabled }; /** @@ -173,11 +182,18 @@ class RateErrorModel : public ErrorModel { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); RateErrorModel (); virtual ~RateErrorModel (); + /** + * Error unit. The error model can be packet, Byte or bit based. + */ enum ErrorUnit { ERROR_UNIT_BIT, @@ -220,15 +236,30 @@ private: virtual bool DoCorrupt (Ptr p); + /** + * Corrupt a packet (packet unit). + * \param p the packet to corrupt + * \returns true if the packet is corrupted + */ virtual bool DoCorruptPkt (Ptr p); + /** + * Corrupt a packet (Byte unit). + * \param p the packet to corrupt + * \returns true if the packet is corrupted + */ virtual bool DoCorruptByte (Ptr p); + /** + * Corrupt a packet (bit unit). + * \param p the packet to corrupt + * \returns true if the packet is corrupted + */ virtual bool DoCorruptBit (Ptr p); virtual void DoReset (void); - enum ErrorUnit m_unit; - double m_rate; + enum ErrorUnit m_unit; //!< Error rate unit + double m_rate; //!< Error rate - Ptr m_ranvar; + Ptr m_ranvar; //!< rng stream }; @@ -267,6 +298,10 @@ class BurstErrorModel : public ErrorModel { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); BurstErrorModel (); @@ -305,16 +340,16 @@ virtual bool DoCorrupt (Ptr p); virtual void DoReset (void); - double m_burstRate; //the burst error event + double m_burstRate; //!< the burst error event + Ptr m_burstStart; //!< the error decision variable + Ptr m_burstSize; //!< the number of packets being flagged as errored - Ptr m_burstStart; //the error decision variable - - Ptr m_burstSize; //the number of packets being flagged as errored - - uint32_t m_counter; //keep track of the number of packets being errored - //until it reaches m_burstSize - - uint32_t m_currentBurstSz; //the current burst size + /** + * keep track of the number of packets being errored + * until it reaches m_burstSize + */ + uint32_t m_counter; + uint32_t m_currentBurstSz; //!< the current burst size }; @@ -344,6 +379,10 @@ class ListErrorModel : public ErrorModel { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); ListErrorModel (); virtual ~ListErrorModel (); @@ -363,10 +402,12 @@ virtual bool DoCorrupt (Ptr p); virtual void DoReset (void); + /// Typedef: packet Uid list typedef std::list PacketList; + /// Typedef: packet Uid list const iterator typedef std::list::const_iterator PacketListCI; - PacketList m_packetList; + PacketList m_packetList; //!< container of Uid of packets to corrupt }; @@ -385,6 +426,10 @@ class ReceiveListErrorModel : public ErrorModel { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); ReceiveListErrorModel (); virtual ~ReceiveListErrorModel (); @@ -404,11 +449,13 @@ virtual bool DoCorrupt (Ptr p); virtual void DoReset (void); + /// Typedef: packet sequence number list typedef std::list PacketList; + /// Typedef: packet sequence number list const iterator typedef std::list::const_iterator PacketListCI; - PacketList m_packetList; - uint32_t m_timesInvoked; + PacketList m_packetList; //!< container of sequence number of packets to corrupt + uint32_t m_timesInvoked; //!< number of times the error model has been invoked }; --- a/src/network/utils/ethernet-header.h +++ a/src/network/utils/ethernet-header.h @@ -103,6 +103,10 @@ */ uint32_t GetHeaderSize () const; + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); virtual TypeId GetInstanceTypeId (void) const; virtual void Print (std::ostream &os) const; @@ -110,18 +114,18 @@ virtual void Serialize (Buffer::Iterator start) const; virtual uint32_t Deserialize (Buffer::Iterator start); private: - static const int PREAMBLE_SIZE = 8; /// size of the preamble_sfd header field - static const int LENGTH_SIZE = 2; /// size of the length_type header field - static const int MAC_ADDR_SIZE = 6; /// size of src/dest addr header fields + static const int PREAMBLE_SIZE = 8; //!< size of the preamble_sfd header field + static const int LENGTH_SIZE = 2; //!< size of the length_type header field + static const int MAC_ADDR_SIZE = 6; //!< size of src/dest addr header fields /** * If false, the preamble/sfd are not serialised/deserialised. */ bool m_enPreambleSfd; - uint64_t m_preambleSfd; /// Value of the Preamble/SFD fields - uint16_t m_lengthType; /// Length or type of the packet - Mac48Address m_source; /// Source address - Mac48Address m_destination; /// Destination address + uint64_t m_preambleSfd; //!< Value of the Preamble/SFD fields + uint16_t m_lengthType; //!< Length or type of the packet + Mac48Address m_source; //!< Source address + Mac48Address m_destination; //!< Destination address }; } // namespace ns3 --- a/src/network/utils/ethernet-trailer.h +++ a/src/network/utils/ethernet-trailer.h @@ -90,6 +90,10 @@ */ uint32_t GetTrailerSize () const; + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); virtual TypeId GetInstanceTypeId (void) const; virtual void Print (std::ostream &os) const; @@ -102,7 +106,7 @@ * returns true. */ bool m_calcFcs; - uint32_t m_fcs; /// Value of the fcs contained in the trailer + uint32_t m_fcs; //!< Value of the fcs contained in the trailer }; --- a/src/network/utils/flow-id-tag.h +++ a/src/network/utils/flow-id-tag.h @@ -27,6 +27,10 @@ class FlowIdTag : public Tag { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); virtual TypeId GetInstanceTypeId (void) const; virtual uint32_t GetSerializedSize (void) const; @@ -57,7 +61,7 @@ */ static uint32_t AllocateFlowId (void); private: - uint32_t m_flowId; + uint32_t m_flowId; //!< Flow ID }; } // namespace ns3 --- a/src/network/utils/inet-socket-address.h +++ a/src/network/utils/inet-socket-address.h @@ -99,18 +99,27 @@ operator Address () const; /** + * \brief Returns an InetSocketAddress which corresponds to the input + * Address. + * * \param address the Address instance to convert from. - * - * Returns an InetSocketAddress which corresponds to the input - * Address + * \returns an InetSocketAddress */ static InetSocketAddress ConvertFrom (const Address &address); private: + /** + * \brief Convert to an Address type + */ Address ConvertTo (void) const; + /** + * \brief Get the underlying address type (automatically assigned). + * + * \returns the address type + */ static uint8_t GetType (void); - Ipv4Address m_ipv4; - uint16_t m_port; + Ipv4Address m_ipv4; //!< the IPv4 address + uint16_t m_port; //!< the port }; } // namespace ns3 --- a/src/network/utils/ipv4-address.cc +++ a/src/network/utils/ipv4-address.cc @@ -31,6 +31,11 @@ #define ASCII_ZERO (0x30) #define ASCII_SLASH (0x2f) +/** + * \brief Converts a string representing an IP address into the address + * \param address the address string + * \returns the address + */ static uint32_t AsciiToIpv4Host (char const *address) { @@ -417,7 +422,7 @@ return !a.IsEqual (b); } -ATTRIBUTE_HELPER_CPP (Ipv4Address); /// Macro to make help make class an ns-3 attribute -ATTRIBUTE_HELPER_CPP (Ipv4Mask); /// Macro to make help make class an ns-3 attribute +ATTRIBUTE_HELPER_CPP (Ipv4Address); //!< Macro to make help make class an ns-3 attribute +ATTRIBUTE_HELPER_CPP (Ipv4Mask); //!< Macro to make help make class an ns-3 attribute } // namespace ns3 --- a/src/network/utils/ipv4-address.h +++ a/src/network/utils/ipv4-address.h @@ -123,6 +123,7 @@ * address. * * \param mask a network mask + * \returns the address combined with the mask */ Ipv4Address CombineMask (Ipv4Mask const &mask) const; /** @@ -134,6 +135,7 @@ * there is no subnet associated with a /32 address. * * \param mask a network mask + * \returns a broadcast address for the subnet. */ Ipv4Address GetSubnetDirectedBroadcast (Ipv4Mask const &mask) const; /** @@ -189,13 +191,23 @@ static Ipv4Address GetLoopback (void); private: + + /** + * \brief Convert to an Address type + */ Address ConvertTo (void) const; + + /** + * \brief Get the underlying address type (automatically assigned). + * + * \returns the address type + */ static uint8_t GetType (void); - uint32_t m_address; + uint32_t m_address; //!< IPv4 address friend bool operator == (Ipv4Address const &a, Ipv4Address const &b); friend bool operator != (Ipv4Address const &a, Ipv4Address const &b); - friend bool operator < (Ipv4Address const &addrA, Ipv4Address const &addrB); + friend bool operator < (Ipv4Address const &a, Ipv4Address const &b); }; /** @@ -274,7 +286,7 @@ static Ipv4Mask GetOnes (void); private: - uint32_t m_mask; + uint32_t m_mask; //!< IP mask }; /** @@ -286,34 +298,106 @@ * \brief hold objects of type ns3::Ipv4Mask */ -ATTRIBUTE_HELPER_HEADER (Ipv4Address); /// Macro to make help make class an ns-3 attribute -ATTRIBUTE_HELPER_HEADER (Ipv4Mask); /// Macro to make help make class an ns-3 attribute +ATTRIBUTE_HELPER_HEADER (Ipv4Address); //!< Macro to make help make class an ns-3 attribute +ATTRIBUTE_HELPER_HEADER (Ipv4Mask); //!< Macro to make help make class an ns-3 attribute +/** + * \brief Stream insertion operator. + * + * \param os the stream + * \param address the address + * \returns a reference to the stream + */ std::ostream& operator<< (std::ostream& os, Ipv4Address const& address); +/** + * \brief Stream insertion operator. + * + * \param os the stream + * \param mask the mask + * \returns a reference to the stream + */ std::ostream& operator<< (std::ostream& os, Ipv4Mask const& mask); +/** + * \brief Stream extraction operator. + * + * \param is the stream + * \param address the address + * \returns a reference to the stream + */ std::istream & operator >> (std::istream &is, Ipv4Address &address); +/** + * \brief Stream extraction operator. + * + * \param is the stream + * \param mask the mask + * \returns a reference to the stream + */ std::istream & operator >> (std::istream &is, Ipv4Mask &mask); +/** + * \brief Equal to operator. + * + * \param a the first operand + * \param b the first operand + * \returns true if the operands are equal + */ inline bool operator == (const Ipv4Address &a, const Ipv4Address &b) { return (a.m_address == b.m_address); } +/** + * \brief Not equal to operator. + * + * \param a the first operand + * \param b the first operand + * \returns true if the operands are not equal + */ inline bool operator != (const Ipv4Address &a, const Ipv4Address &b) { return (a.m_address != b.m_address); } +/** + * \brief Less than operator. + * + * \param a the first operand + * \param b the first operand + * \returns true if the operand a is less than operand b + */ inline bool operator < (const Ipv4Address &a, const Ipv4Address &b) { return (a.m_address < b.m_address); } - +/** + * \ingroup address + * + * \brief Class providing an hash for IPv4 addresses + */ class Ipv4AddressHash : public std::unary_function { public: + /** + * Returns the hash of the address + * \param x the address + * \return the hash + */ size_t operator() (Ipv4Address const &x) const; }; +/** + * \brief Equal to operator. + * + * \param a the first operand + * \param b the first operand + * \returns true if the operands are equal + */ bool operator == (Ipv4Mask const &a, Ipv4Mask const &b); +/** + * \brief Not equal to operator. + * + * \param a the first operand + * \param b the first operand + * \returns true if the operands are not equal + */ bool operator != (Ipv4Mask const &a, Ipv4Mask const &b); } // namespace ns3 --- a/src/network/utils/ipv6-address.cc +++ a/src/network/utils/ipv6-address.cc @@ -1011,8 +1011,8 @@ return lookuphash (buf, sizeof (buf), 0); } -ATTRIBUTE_HELPER_CPP (Ipv6Address); /// Macro to make help make class an ns-3 attribute -ATTRIBUTE_HELPER_CPP (Ipv6Prefix); /// Macro to make help make class an ns-3 attribute +ATTRIBUTE_HELPER_CPP (Ipv6Address); //!< Macro to make help make class an ns-3 attribute +ATTRIBUTE_HELPER_CPP (Ipv6Prefix); //!< Macro to make help make class an ns-3 attribute } /* namespace ns3 */ --- a/src/network/utils/ipv6-address.h +++ a/src/network/utils/ipv6-address.h @@ -510,13 +510,13 @@ * \class ns3::Ipv6AddressValue * \brief Hold objects of type ns3::Ipv6Address */ -ATTRIBUTE_HELPER_HEADER (Ipv6Address); /// Macro to make help make class an ns-3 attribute +ATTRIBUTE_HELPER_HEADER (Ipv6Address); //!< Macro to make help make class an ns-3 attribute /** * \class ns3::Ipv6PrefixValue * \brief Hold objects of type ns3::Ipv6Prefix */ -ATTRIBUTE_HELPER_HEADER (Ipv6Prefix); /// Macro to make help make class an ns-3 attribute +ATTRIBUTE_HELPER_HEADER (Ipv6Prefix); //!< Macro to make help make class an ns-3 attribute /** * \brief Stream insertion operator. --- a/src/network/utils/llc-snap-header.h +++ a/src/network/utils/llc-snap-header.h @@ -36,15 +36,29 @@ * \ingroup network * * \brief Header for the LLC/SNAP encapsulation + * + * For a list of EtherTypes, see http://www.iana.org/assignments/ieee-802-numbers/ieee-802-numbers.xhtml */ class LlcSnapHeader : public Header { public: LlcSnapHeader (); + /** + * \brief Set the Ethertype. + * \param type the Ethertype + */ void SetType (uint16_t type); + /** + * \brief Return the Ethertype. + * \return Ethertype + */ uint16_t GetType (void); + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); virtual TypeId GetInstanceTypeId (void) const; virtual void Print (std::ostream &os) const; @@ -52,7 +66,7 @@ virtual void Serialize (Buffer::Iterator start) const; virtual uint32_t Deserialize (Buffer::Iterator start); private: - uint16_t m_etherType; + uint16_t m_etherType; //!< the Ethertype }; } // namespace ns3 --- a/src/network/utils/mac16-address.cc +++ a/src/network/utils/mac16-address.cc @@ -30,7 +30,7 @@ namespace ns3 { -ATTRIBUTE_HELPER_CPP (Mac16Address); /// Macro to make help make class an ns-3 attribute +ATTRIBUTE_HELPER_CPP (Mac16Address); //!< Macro to make help make class an ns-3 attribute #define ASCII_a (0x41) #define ASCII_z (0x5a) @@ -39,6 +39,11 @@ #define ASCII_COLON (0x3a) #define ASCII_ZERO (0x30) +/** + * Converts a char to lower case. + * \param c the char + * \returns the lower case + */ static char AsciiToLowCase (char c) { @@ -169,6 +174,12 @@ return os; } +/** + * \brief Converts a string representing an hex number [0x0, 0xFF] into its value. + * + * \param v a string + * \returns the value + */ static uint8_t AsInt (std::string v) { --- a/src/network/utils/mac16-address.h +++ a/src/network/utils/mac16-address.h @@ -91,13 +91,59 @@ * Convert an instance of this class to a polymorphic Address instance. */ Address ConvertTo (void) const; + + /** + * \brief Return the Type of address. + * \return type of address + */ static uint8_t GetType (void); + + /** + * \brief Equal to operator. + * + * \param a the first operand + * \param b the first operand + * \returns true if the operands are equal + */ + friend bool operator == (const Mac16Address &a, const Mac16Address &b); + + /** + * \brief Not equal to operator. + * + * \param a the first operand + * \param b the first operand + * \returns true if the operands are not equal + */ + friend bool operator != (const Mac16Address &a, const Mac16Address &b); + + /** + * \brief Less than operator. + * + * \param a the first operand + * \param b the first operand + * \returns true if the operand a is less than operand b + */ friend bool operator < (const Mac16Address &a, const Mac16Address &b); - friend bool operator == (const Mac16Address &a, const Mac16Address &b); - friend bool operator != (const Mac16Address &a, const Mac16Address &b); + + /** + * \brief Stream insertion operator. + * + * \param os the stream + * \param address the address + * \returns a reference to the stream + */ + friend std::ostream& operator<< (std::ostream& os, const Mac16Address & address); + + /** + * \brief Stream extraction operator. + * + * \param is the stream + * \param address the address + * \returns a reference to the stream + */ friend std::istream& operator>> (std::istream& is, Mac16Address & address); - uint8_t m_address[2]; + uint8_t m_address[2]; //!< address value }; /** @@ -105,7 +151,7 @@ * \brief hold objects of type ns3::Mac16Address */ -ATTRIBUTE_HELPER_HEADER (Mac16Address); /// Macro to make help make class an ns-3 attribute +ATTRIBUTE_HELPER_HEADER (Mac16Address); //!< Macro to make help make class an ns-3 attribute inline bool operator == (const Mac16Address &a, const Mac16Address &b) { --- a/src/network/utils/mac48-address.cc +++ a/src/network/utils/mac48-address.cc @@ -29,7 +29,7 @@ namespace ns3 { -ATTRIBUTE_HELPER_CPP (Mac48Address); /// Macro to make help make class an ns-3 attribute +ATTRIBUTE_HELPER_CPP (Mac48Address); //!< Macro to make help make class an ns-3 attribute #define ASCII_a (0x41) #define ASCII_z (0x5a) @@ -38,6 +38,11 @@ #define ASCII_COLON (0x3a) #define ASCII_ZERO (0x30) +/** + * Converts a char to lower case. + * \param c the char + * \returns the lower case + */ static char AsciiToLowCase (char c) { @@ -259,6 +264,12 @@ return os; } +/** + * \brief Converts a string representing an hex number [0x0, 0xFF] into its value. + * + * \param v a string + * \returns the value + */ static uint8_t AsInt (std::string v) { --- a/src/network/utils/mac48-address.h +++ a/src/network/utils/mac48-address.h @@ -133,13 +133,59 @@ * Convert an instance of this class to a polymorphic Address instance. */ Address ConvertTo (void) const; + + /** + * \brief Return the Type of address. + * \return type of address + */ static uint8_t GetType (void); + + /** + * \brief Equal to operator. + * + * \param a the first operand + * \param b the first operand + * \returns true if the operands are equal + */ + friend bool operator == (const Mac48Address &a, const Mac48Address &b); + + /** + * \brief Not equal to operator. + * + * \param a the first operand + * \param b the first operand + * \returns true if the operands are not equal + */ + friend bool operator != (const Mac48Address &a, const Mac48Address &b); + + /** + * \brief Less than operator. + * + * \param a the first operand + * \param b the first operand + * \returns true if the operand a is less than operand b + */ friend bool operator < (const Mac48Address &a, const Mac48Address &b); - friend bool operator == (const Mac48Address &a, const Mac48Address &b); - friend bool operator != (const Mac48Address &a, const Mac48Address &b); + + /** + * \brief Stream insertion operator. + * + * \param os the stream + * \param address the address + * \returns a reference to the stream + */ + friend std::ostream& operator<< (std::ostream& os, const Mac48Address & address); + + /** + * \brief Stream extraction operator. + * + * \param is the stream + * \param address the address + * \returns a reference to the stream + */ friend std::istream& operator>> (std::istream& is, Mac48Address & address); - uint8_t m_address[6]; + uint8_t m_address[6]; //!< address value }; /** @@ -147,7 +193,7 @@ * \brief hold objects of type ns3::Mac48Address */ -ATTRIBUTE_HELPER_HEADER (Mac48Address); /// Macro to make help make class an ns-3 attribute +ATTRIBUTE_HELPER_HEADER (Mac48Address); //!< Macro to make help make class an ns-3 attribute inline bool operator == (const Mac48Address &a, const Mac48Address &b) { --- a/src/network/utils/mac64-address.cc +++ a/src/network/utils/mac64-address.cc @@ -29,7 +29,7 @@ namespace ns3 { -ATTRIBUTE_HELPER_CPP (Mac64Address); /// Macro to make help make class an ns-3 attribute +ATTRIBUTE_HELPER_CPP (Mac64Address); //!< Macro to make help make class an ns-3 attribute #define ASCII_a (0x41) #define ASCII_z (0x5a) @@ -38,6 +38,11 @@ #define ASCII_COLON (0x3a) #define ASCII_ZERO (0x30) +/** + * Converts a char to lower case. + * \param c the char + * \returns the lower case + */ static char AsciiToLowCase (char c) { @@ -171,6 +176,12 @@ return os; } +/** + * \brief Converts a string representing an hex number [0x0, 0xFF] into its value. + * + * \param v a string + * \returns the value + */ static uint8_t AsInt (std::string v) { --- a/src/network/utils/mac64-address.h +++ a/src/network/utils/mac64-address.h @@ -93,13 +93,59 @@ * Convert an instance of this class to a polymorphic Address instance. */ Address ConvertTo (void) const; + + /** + * \brief Return the Type of address. + * \return type of address + */ static uint8_t GetType (void); + + /** + * \brief Equal to operator. + * + * \param a the first operand + * \param b the first operand + * \returns true if the operands are equal + */ + friend bool operator == (const Mac64Address &a, const Mac64Address &b); + + /** + * \brief Not equal to operator. + * + * \param a the first operand + * \param b the first operand + * \returns true if the operands are not equal + */ + friend bool operator != (const Mac64Address &a, const Mac64Address &b); + + /** + * \brief Less than operator. + * + * \param a the first operand + * \param b the first operand + * \returns true if the operand a is less than operand b + */ friend bool operator < (const Mac64Address &a, const Mac64Address &b); - friend bool operator == (const Mac64Address &a, const Mac64Address &b); - friend bool operator != (const Mac64Address &a, const Mac64Address &b); + + /** + * \brief Stream insertion operator. + * + * \param os the stream + * \param address the address + * \returns a reference to the stream + */ + friend std::ostream& operator<< (std::ostream& os, const Mac64Address & address); + + /** + * \brief Stream extraction operator. + * + * \param is the stream + * \param address the address + * \returns a reference to the stream + */ friend std::istream& operator>> (std::istream& is, Mac64Address & address); - uint8_t m_address[8]; + uint8_t m_address[8]; //!< address value }; /** @@ -107,7 +153,7 @@ * \brief hold objects of type ns3::Mac64Address */ -ATTRIBUTE_HELPER_HEADER (Mac64Address); /// Macro to make help make class an ns-3 attribute +ATTRIBUTE_HELPER_HEADER (Mac64Address); //!< Macro to make help make class an ns-3 attribute inline bool operator == (const Mac64Address &a, const Mac64Address &b) { --- a/src/network/utils/output-stream-wrapper.h +++ a/src/network/utils/output-stream-wrapper.h @@ -26,8 +26,8 @@ namespace ns3 { -/* - * @brief A class encapsulating an STL output stream. +/** + * @brief A class encapsulating an output stream. * * This class wraps a pointer to a C++ std::ostream and provides * reference counting of the object. This class is recommended for users @@ -70,7 +70,16 @@ class OutputStreamWrapper : public SimpleRefCount { public: + /** + * Constructor + * \param filename file name + * \param filemode std::ios::openmode flags + */ OutputStreamWrapper (std::string filename, std::ios::openmode filemode); + /** + * Constructor + * \param os output stream + */ OutputStreamWrapper (std::ostream* os); ~OutputStreamWrapper (); @@ -84,8 +93,8 @@ std::ostream *GetStream (void); private: - std::ostream *m_ostream; - bool m_destroyable; + std::ostream *m_ostream; //!< The output stream + bool m_destroyable; //!< Can be destroyed }; } // namespace ns3 --- a/src/network/utils/packet-burst.h +++ a/src/network/utils/packet-burst.h @@ -29,12 +29,16 @@ class Packet; +/** + * \brief this class implement a burst as a list of packets + */ class PacketBurst : public Object { +public: /** - * \brief this class implement a burst as a list of packets + * \brief Get the type ID. + * \return the object TypeId */ -public: static TypeId GetTypeId (void); PacketBurst (void); virtual ~PacketBurst (void); @@ -60,11 +64,19 @@ */ uint32_t GetSize (void) const; + /** + * \brief Returns an iterator to the begin of the burst + * \return iterator to the burst list start + */ std::list >::const_iterator Begin (void) const; + /** + * \brief Returns an iterator to the end of the burst + * \return iterator to the burst list end + */ std::list >::const_iterator End (void) const; private: void DoDispose (void); - std::list > m_packets; + std::list > m_packets; //!< the list of packets in the burst }; } // namespace ns3 --- a/src/network/utils/packet-probe.h +++ a/src/network/utils/packet-probe.h @@ -47,6 +47,10 @@ class PacketProbe : public Probe { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (); PacketProbe (); virtual ~PacketProbe (); @@ -96,7 +100,9 @@ */ void TraceSink (Ptr packet); + /// Traced callback: packet received TracedCallback > m_output; + /// Traced callback: size of previous packet receive, size of actual packet received TracedCallback m_outputBytes; /// The traced packet. --- a/src/network/utils/packet-socket-address.h +++ a/src/network/utils/packet-socket-address.h @@ -39,15 +39,52 @@ { public: PacketSocketAddress (); + + /** + * \brief Set the protocol + * \param protocol the protocol + */ void SetProtocol (uint16_t protocol); + /** + * \brief Set the address to match all the outgoing NetDevice + */ void SetAllDevices (void); + + /** + * \brief Set the address to match only a specified NetDevice + * \param device the NetDevice index + */ void SetSingleDevice (uint32_t device); + + /** + * \brief Set the destination address + * \param address the destination address + */ void SetPhysicalAddress (const Address address); + /** + * \brief Get the protocol + * \return the protocol + */ uint16_t GetProtocol (void) const; + + /** + * \brief Get the device this address is bound to + * \return the device index + */ uint32_t GetSingleDevice (void) const; + + /** + * \brief Checks if the address is bound to a specified NetDevice + * \return true if the address is bound to a NetDevice + */ bool IsSingleDevice (void) const; + + /** + * \brief Get the destination address + * \returns The destination address + */ Address GetPhysicalAddress (void) const; /** @@ -56,25 +93,38 @@ * Convert an instance of this class to a polymorphic Address instance. */ operator Address () const; + /** * \param address a polymorphic address - * + * \returns an Address * Convert a polymorphic address to an Mac48Address instance. * The conversion performs a type check. */ static PacketSocketAddress ConvertFrom (const Address &address); + /** * \param address address to test * \returns true if the address matches, false otherwise. */ static bool IsMatchingType (const Address &address); private: + + /** + * \brief Return the Type of address. + * \return type of address + */ static uint8_t GetType (void); + + /** + * \brief Convert an instance of this class to a polymorphic Address instance. + * \returns a new Address instance + */ Address ConvertTo (void) const; - uint16_t m_protocol; - bool m_isSingleDevice; - uint32_t m_device; - Address m_address; + + uint16_t m_protocol; //!< Protocol + bool m_isSingleDevice; //!< True if directed to a specific outgoing NetDevice + uint32_t m_device; //!< Outgoing NetDevice index + Address m_address; //!< Destination address }; --- a/src/network/utils/packet-socket-factory.h +++ a/src/network/utils/packet-socket-factory.h @@ -35,6 +35,10 @@ class PacketSocketFactory : public SocketFactory { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); PacketSocketFactory (); --- a/src/network/utils/packet-socket.h +++ a/src/network/utils/packet-socket.h @@ -43,7 +43,7 @@ * * A PacketSocket can be used to connect an application to a net * device. The application provides the buffers of data, the socket - * conserts them to a raw packet and the net device then adds the + * converts them to a raw packet and the net device then adds the * protocol specific headers and trailers. This socket type * is very similar to the linux and BSD "packet" sockets. * @@ -78,18 +78,47 @@ class PacketSocket : public Socket { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); PacketSocket (); virtual ~PacketSocket (); + /** + * \brief Set the associated node. + * \param node the node + */ void SetNode (Ptr node); virtual enum SocketErrno GetErrno (void) const; virtual enum SocketType GetSocketType (void) const; virtual Ptr GetNode (void) const; + /** + * \brief Bind the socket to the NetDevice and register the protocol handler. + * + * \warning this will actually bind protocol "0". + * + * \returns 0 on success, -1 on failure. + */ virtual int Bind (void); + /** + * \brief Bind the socket to the NetDevice and register the protocol handler. + * + * \warning this will actually bind protocol "0". + * + * \returns 0 on success, -1 on failure. + */ virtual int Bind6 (void); + /** + * \brief Bind the socket to the NetDevice and register the + * protocol handler specified in the address. + * + * \param address the packet socket address + * \returns 0 on success, -1 on failure. + */ virtual int Bind (const Address & address); virtual int Close (void); virtual int ShutdownSend (void); @@ -108,42 +137,68 @@ virtual bool GetAllowBroadcast () const; private: + /** + * \brief Called by the L3 protocol when it received a packet to pass on to TCP. + * + * \param device the incoming NetDevice + * \param packet the incoming packet + * \param protocol the protocol + * \param from sender address + * \param to destination address + * \param packetType packet type + */ void ForwardUp (Ptr device, Ptr packet, uint16_t protocol, const Address &from, const Address &to, NetDevice::PacketType packetType); + /** + * \brief Bind the socket to the NetDevice and register the + * protocol handler specified in the address. + * \param address the packet socket address + * \returns 0 on success, -1 on failure. + */ int DoBind (const PacketSocketAddress &address); + + /** + * \brief Get the minimum MTU supported by the NetDevices bound to a specific address + * \param ad the socket address to check for + * \returns The minimum MTU + */ uint32_t GetMinMtu (PacketSocketAddress ad) const; virtual void DoDispose (void); + /** + * \brief States of the socket + */ enum State { STATE_OPEN, STATE_BOUND, // open and bound STATE_CONNECTED, // open, bound and connected STATE_CLOSED }; - Ptr m_node; - enum SocketErrno m_errno; - bool m_shutdownSend; - bool m_shutdownRecv; - enum State m_state; - uint16_t m_protocol; - bool m_isSingleDevice; - uint32_t m_device; - Address m_destAddr; /// Default destination address - std::queue > m_deliveryQueue; - uint32_t m_rxAvailable; + Ptr m_node; //!< the associated node + enum SocketErrno m_errno; //!< Socket error code + bool m_shutdownSend; //!< Send no longer allowed + bool m_shutdownRecv; //!< Receive no longer allowed + enum State m_state; //!< Socket state + uint16_t m_protocol; //!< Socket protocol + bool m_isSingleDevice; //!< Is bound to a single netDevice + uint32_t m_device; //!< index of the bound NetDevice + Address m_destAddr; //!< Default destination address + std::queue > m_deliveryQueue; //!< Rx queue + uint32_t m_rxAvailable; //!< Rx queue size [Bytes] + + /// Traced callback: dropped packets TracedCallback > m_dropTrace; // Socket options (attributes) - uint32_t m_rcvBufSize; + uint32_t m_rcvBufSize; //!< Rx buffer size [Bytes] }; /** * \brief This class implements a tag that carries the dest address of a packet and the packet type. - * */ class PacketSocketTag : public Tag { @@ -173,6 +228,10 @@ */ Address GetDestAddress (void) const; + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); virtual TypeId GetInstanceTypeId (void) const; virtual uint32_t GetSerializedSize (void) const; @@ -181,13 +240,11 @@ virtual void Print (std::ostream &os) const; private: - std::string m_deviceName; - NetDevice::PacketType m_packetType; - Address m_destAddr; + NetDevice::PacketType m_packetType; //!< Packet type + Address m_destAddr; //!< Destination address }; /** * \brief This class implements a tag that carries the ns3 device name from where a packet is coming. - * */ class DeviceNameTag : public Tag { @@ -206,6 +263,10 @@ * @return the device name from where the corresponding packet is coming. */ std::string GetDeviceName (void) const; + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); virtual TypeId GetInstanceTypeId (void) const; virtual uint32_t GetSerializedSize (void) const; @@ -214,7 +275,7 @@ virtual void Print (std::ostream &os) const; private: - std::string m_deviceName; + std::string m_deviceName; //!< Device name }; } // namespace ns3 --- a/src/network/utils/packetbb.h +++ a/src/network/utils/packetbb.h @@ -55,8 +55,10 @@ class PbbTlvBlock { public: - typedef std::list< Ptr >::iterator Iterator; /// this is an iterator - typedef std::list< Ptr >::const_iterator ConstIterator; /// this is a const iterator + /// PbbTlv container iterator + typedef std::list< Ptr >::iterator Iterator; + /// PbbTlv container const iterator + typedef std::list< Ptr >::const_iterator ConstIterator; PbbTlvBlock (void); ~PbbTlvBlock (void); @@ -206,7 +208,7 @@ bool operator!= (const PbbTlvBlock &other) const; private: - std::list< Ptr > m_tlvList; + std::list< Ptr > m_tlvList; //!< PbbTlv container }; /** @@ -217,8 +219,10 @@ class PbbAddressTlvBlock { public: - typedef std::list< Ptr >::iterator Iterator; /// This is a PbbAddressTlv iterator for PbbAddressTlvBlock - typedef std::list< Ptr >::const_iterator ConstIterator; /// This is a const PbbAddressTlv iterator for PbbAddressTlvBlock + /// PbbAddressTlv iterator for PbbAddressTlvBlock + typedef std::list< Ptr >::iterator Iterator; + /// PbbAddressTlv const iterator for PbbAddressTlvBlock + typedef std::list< Ptr >::const_iterator ConstIterator; PbbAddressTlvBlock (void); ~PbbAddressTlvBlock (void); @@ -371,7 +375,7 @@ bool operator!= (const PbbAddressTlvBlock &other) const; private: - std::list< Ptr > m_tlvList; + std::list< Ptr > m_tlvList; //!< PbbAddressTlv container }; /** @@ -385,10 +389,14 @@ class PbbPacket : public SimpleRefCount { public: - typedef std::list< Ptr >::iterator TlvIterator; /// This is a PbbTlv iterator for PbbPacket - typedef std::list< Ptr >::const_iterator ConstTlvIterator; /// This is a const PbbTlv iterator for PbbPacket - typedef std::list< Ptr >::iterator MessageIterator; /// This is a PbbMessageIterator for PbbPacket - typedef std::list< Ptr >::const_iterator ConstMessageIterator; /// This is a const PbbMessageIterator for PbbPacket + /// PbbTlv iterator for PbbPacket + typedef std::list< Ptr >::iterator TlvIterator; + /// PbbTlv const iterator for PbbPacket + typedef std::list< Ptr >::const_iterator ConstTlvIterator; + /// PbbMessage Iterator for PbbPacket + typedef std::list< Ptr >::iterator MessageIterator; + /// PbbMessage Const Iterator for PbbPacket + typedef std::list< Ptr >::const_iterator ConstMessageIterator; PbbPacket (void); ~PbbPacket (void); @@ -617,7 +625,10 @@ */ void MessageClear (void); - /* Methods implemented by all headers */ + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); virtual TypeId GetInstanceTypeId (void) const; @@ -665,13 +676,13 @@ protected: private: - PbbTlvBlock m_tlvList; - std::list< Ptr > m_messageList; + PbbTlvBlock m_tlvList; //!< PbbTlv container + std::list< Ptr > m_messageList; //!< PbbTlvBlock container - uint8_t m_version; + uint8_t m_version; //!< version - bool m_hasseqnum; - uint16_t m_seqnum; + bool m_hasseqnum; //!< Sequence number present + uint16_t m_seqnum; //!< Sequence number }; /** @@ -684,10 +695,14 @@ class PbbMessage : public SimpleRefCount { public: - typedef std::list< Ptr >::iterator TlvIterator; /// This is a PbbTlv iterator for PbbMessage - typedef std::list< Ptr >::const_iterator ConstTlvIterator; /// This is a const PbbTlv iterator for PbbMessage - typedef std::list< Ptr >::iterator AddressBlockIterator; /// This is a PbbAddressBlock iterator for PbbMessage - typedef std::list< Ptr >::const_iterator ConstAddressBlockIterator; /// This is a const PbbAddressBlock iterator for PbbMessage + /// PbbTlv iterator + typedef std::list< Ptr >::iterator TlvIterator; + /// PbbTlv const iterator + typedef std::list< Ptr >::const_iterator ConstTlvIterator; + /// PbbAddressBlock iterator + typedef std::list< Ptr >::iterator AddressBlockIterator; + /// PbbAddressBlock const iterator + typedef std::list< Ptr >::const_iterator ConstAddressBlockIterator; PbbMessage (); virtual ~PbbMessage (); @@ -1060,30 +1075,48 @@ */ virtual PbbAddressLength GetAddressLength (void) const = 0; + /** + * \brief Serialize the originator address + * \param start the buffer iterator start + */ virtual void SerializeOriginatorAddress (Buffer::Iterator &start) const = 0; + /** + * \brief Deserialize the originator address + * \param start the buffer iterator start + * \returns the deserialized address + */ virtual Address DeserializeOriginatorAddress (Buffer::Iterator &start) const = 0; + /** + * \brief Print the originator address + * \param os the output stream + */ virtual void PrintOriginatorAddress (std::ostream &os) const = 0; + /** + * \brief Deserialize an address block + * \param start the buffer iterator start + * \returns the deserialized address block + */ virtual Ptr AddressBlockDeserialize (Buffer::Iterator &start) const = 0; private: - PbbTlvBlock m_tlvList; - std::list< Ptr > m_addressBlockList; + PbbTlvBlock m_tlvList; //!< PbbTlvBlock + std::list< Ptr > m_addressBlockList; //!< PbbAddressBlock container - uint8_t m_type; - PbbAddressLength m_addrSize; + uint8_t m_type; //!< the type for this message + PbbAddressLength m_addrSize; //!< the address size - bool m_hasOriginatorAddress; - Address m_originatorAddress; + bool m_hasOriginatorAddress; //!< Originator address present + Address m_originatorAddress; //!< originator address - bool m_hasHopLimit; - uint8_t m_hopLimit; + bool m_hasHopLimit; //!< Hop limit present + uint8_t m_hopLimit; //!< Hop limit - bool m_hasHopCount; - uint8_t m_hopCount; + bool m_hasHopCount; //!< Hop count present + uint8_t m_hopCount; //!< Hop count - bool m_hasSequenceNumber; - uint16_t m_sequenceNumber; + bool m_hasSequenceNumber; //!< Sequence number present + uint16_t m_sequenceNumber; //!< Sequence number }; /** @@ -1151,14 +1184,20 @@ class PbbAddressBlock : public SimpleRefCount { public: - typedef std::list< Address >::iterator AddressIterator; /// this is an address iterator for PbbAddressBlock - typedef std::list< Address >::const_iterator ConstAddressIterator; /// this is an const address iterator for PbbAddressBlock + /// Address iterator + typedef std::list< Address >::iterator AddressIterator; + /// Address const iterator + typedef std::list< Address >::const_iterator ConstAddressIterator; - typedef std::list::iterator PrefixIterator; /// this is a prefix iterator for PbbAddressBlock - typedef std::list::const_iterator ConstPrefixIterator; /// this is a const prefix iterator for PbbAddressBlock + /// Prefix iterator + typedef std::list::iterator PrefixIterator; + /// Prefix const iterator + typedef std::list::const_iterator ConstPrefixIterator; - typedef PbbAddressTlvBlock::Iterator TlvIterator; /// this is a tlvblock iterator for PbbAddressBlock - typedef PbbAddressTlvBlock::ConstIterator ConstTlvIterator; /// this is a const tlvblock iterator for PbbAddressBlock + /// tlvblock iterator + typedef PbbAddressTlvBlock::Iterator TlvIterator; + /// tlvblock const iterator + typedef PbbAddressTlvBlock::ConstIterator ConstTlvIterator; PbbAddressBlock (); virtual ~PbbAddressBlock (); @@ -1522,19 +1561,52 @@ * \returns Address length */ virtual uint8_t GetAddressLength (void) const = 0; + /** + * \brief Serialize one or more addresses + * \param buffer the buffer to serialize to + * \param iter the iterator to the addresses + */ virtual void SerializeAddress (uint8_t *buffer, ConstAddressIterator iter) const = 0; + /** + * \brief Deserialize one address + * \param buffer the buffer to deserialize from + * \returns the address + */ virtual Address DeserializeAddress (uint8_t *buffer) const = 0; + /** + * \brief Print one or more addresses + * \param os the output stream + * \param iter the iterator to the addresses + */ virtual void PrintAddress (std::ostream &os, ConstAddressIterator iter) const = 0; private: + /** + * \brief Get the prefix flags + * \return the prefix flags + */ uint8_t GetPrefixFlags (void) const; + /** + * \brief Get head and tail + * \param head the head + * \param headlen the head length + * \param tail the tail + * \param taillen the tail length + */ void GetHeadTail (uint8_t *head, uint8_t &headlen, uint8_t *tail, uint8_t &taillen) const; + + /** + * \brief Check if the tail is empty + * \param tail the tail + * \param taillen the tail length + * \returns true if the tail is empty + */ bool HasZeroTail (const uint8_t *tail, uint8_t taillen) const; - std::list
m_addressList; - std::list m_prefixList; - PbbAddressTlvBlock m_addressTlvList; + std::list
m_addressList; //!< Addreses container + std::list m_prefixList; //!< Prefixes container + PbbAddressTlvBlock m_addressTlvList; //!< PbbAddressTlv container }; /** @@ -1717,32 +1789,64 @@ bool operator!= (const PbbTlv &other) const; protected: + /** + * \brief Set an index as starting point + * \param index the starting index + */ void SetIndexStart (uint8_t index); + /** + * \brief Get the starting point index + * \returns the starting index + */ uint8_t GetIndexStart (void) const; + /** + * \brief Checks if there is a starting index + * \returns true if the start index has been set + */ bool HasIndexStart (void) const; + /** + * \brief Set an index as stop point + * \param index the stop index + */ void SetIndexStop (uint8_t index); + /** + * \brief Get the stop point index + * \returns the stop index + */ uint8_t GetIndexStop (void) const; + /** + * \brief Checks if there is a stop index + * \returns true if the stop index has been set + */ bool HasIndexStop (void) const; + /** + * \brief Set the multivalue parameter + * \param isMultivalue the multivalue status + */ void SetMultivalue (bool isMultivalue); + /** + * \brief Check the multivalue parameter + * \returns the multivalue status + */ bool IsMultivalue (void) const; private: - uint8_t m_type; + uint8_t m_type; //!< Type of this TLV. - bool m_hasTypeExt; - uint8_t m_typeExt; + bool m_hasTypeExt; //!< Extended type present. + uint8_t m_typeExt; //!< Extended type. - bool m_hasIndexStart; - uint8_t m_indexStart; + bool m_hasIndexStart; //!< Start index present. + uint8_t m_indexStart; //!< Start index. - bool m_hasIndexStop; - uint8_t m_indexStop; + bool m_hasIndexStop; //!< Stop index present. + uint8_t m_indexStop; //!< Stop index. - bool m_isMultivalue; - bool m_hasValue; - Buffer m_value; + bool m_isMultivalue; //!< Is multivalue. + bool m_hasValue; //!< Has value. + Buffer m_value; //!< Value. }; /** --- a/src/network/utils/pcap-file-wrapper.h +++ a/src/network/utils/pcap-file-wrapper.h @@ -30,7 +30,7 @@ namespace ns3 { -/* +/** * A class that wraps a PcapFile as an ns3::Object and provides a higher-layer * ns-3 interface to the low-level public methods of PcapFile. Users are * encouraged to use this object instead of class ns3::PcapFile in ns-3 @@ -39,6 +39,10 @@ class PcapFileWrapper : public Object { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); PcapFileWrapper (); @@ -138,65 +142,79 @@ */ void Write (Time t, uint8_t const *buffer, uint32_t length); - /* + /** * \brief Returns the magic number of the pcap file as defined by the magic_number * field in the pcap global header. * * See http://wiki.wireshark.org/Development/LibpcapFileFormat + * + * \returns magic number */ uint32_t GetMagic (void); - /* + /** * \brief Returns the major version of the pcap file as defined by the version_major * field in the pcap global header. * * See http://wiki.wireshark.org/Development/LibpcapFileFormat + * + * \returns major version */ uint16_t GetVersionMajor (void); - /* + /** * \brief Returns the minor version of the pcap file as defined by the version_minor * field in the pcap global header. * * See http://wiki.wireshark.org/Development/LibpcapFileFormat + * + * \returns minor version */ uint16_t GetVersionMinor (void); - /* + /** * \brief Returns the time zone offset of the pcap file as defined by the thiszone * field in the pcap global header. * * See http://wiki.wireshark.org/Development/LibpcapFileFormat + * + * \returns time zone offset */ int32_t GetTimeZoneOffset (void); - /* + /** * \brief Returns the accuracy of timestamps field of the pcap file as defined * by the sigfigs field in the pcap global header. * * See http://wiki.wireshark.org/Development/LibpcapFileFormat + * + * \returns accuracy of timestamps */ uint32_t GetSigFigs (void); - /* + /** * \brief Returns the max length of saved packets field of the pcap file as * defined by the snaplen field in the pcap global header. * * See http://wiki.wireshark.org/Development/LibpcapFileFormat + * + * \returns max length of saved packets field */ uint32_t GetSnapLen (void); - /* + /** * \brief Returns the data link type field of the pcap file as defined by the * network field in the pcap global header. * * See http://wiki.wireshark.org/Development/LibpcapFileFormat + * + * \returns data link type field */ uint32_t GetDataLinkType (void); private: - PcapFile m_file; - uint32_t m_snapLen; + PcapFile m_file; //!< Pcap file + uint32_t m_snapLen; //!< max length of saved packets }; } // namespace ns3 --- a/src/network/utils/pcap-file.h +++ a/src/network/utils/pcap-file.h @@ -186,62 +186,78 @@ * byteswapped. Used primarily for testing the class itself, but may be * useful as a flag indicating a difference in endianness of the writing * system. + * + * \returns swap mode of the file */ bool GetSwapMode (void); - /* + /** * \brief Returns the magic number of the pcap file as defined by the magic_number * field in the pcap global header. * * See http://wiki.wireshark.org/Development/LibpcapFileFormat + * + * \returns magic number */ uint32_t GetMagic (void); - /* + /** * \brief Returns the major version of the pcap file as defined by the version_major * field in the pcap global header. * * See http://wiki.wireshark.org/Development/LibpcapFileFormat + * + * \returns major version */ uint16_t GetVersionMajor (void); - /* + /** * \brief Returns the minor version of the pcap file as defined by the version_minor * field in the pcap global header. * * See http://wiki.wireshark.org/Development/LibpcapFileFormat + * + * \returns minor version */ uint16_t GetVersionMinor (void); - /* + /** * \brief Returns the time zone offset of the pcap file as defined by the thiszone * field in the pcap global header. * * See http://wiki.wireshark.org/Development/LibpcapFileFormat + * + * \returns time zone offset */ int32_t GetTimeZoneOffset (void); - /* + /** * \brief Returns the accuracy of timestamps field of the pcap file as defined * by the sigfigs field in the pcap global header. * * See http://wiki.wireshark.org/Development/LibpcapFileFormat + * + * \returns accuracy of timestamps */ uint32_t GetSigFigs (void); - /* + /** * \brief Returns the max length of saved packets field of the pcap file as * defined by the snaplen field in the pcap global header. * * See http://wiki.wireshark.org/Development/LibpcapFileFormat + * + * \returns max length of saved packets field */ uint32_t GetSnapLen (void); - /* + /** * \brief Returns the data link type field of the pcap file as defined by the * network field in the pcap global header. * * See http://wiki.wireshark.org/Development/LibpcapFileFormat + * + * \returns data link type field */ uint32_t GetDataLinkType (void); @@ -261,6 +277,9 @@ uint32_t snapLen = SNAPLEN_DEFAULT); private: + /** + * \brief Pcap file header + */ typedef struct { uint32_t m_magicNumber; /**< Magic number identifying this as a pcap file */ uint16_t m_versionMajor; /**< Major version identifying the version of pcap used in this file */ @@ -271,6 +290,9 @@ uint32_t m_type; /**< Data link type of packet data */ } PcapFileHeader; + /** + * \brief Pcap record header + */ typedef struct { uint32_t m_tsSec; /**< seconds part of timestamp */ uint32_t m_tsUsec; /**< microseconds part of timestamp (nsecs for PCAP_NSEC_MAGIC) */ @@ -278,20 +300,59 @@ uint32_t m_origLen; /**< actual length of original packet */ } PcapRecordHeader; + /** + * \brief Swap a value byte order + * \param val the value + * \returns the value with byte order swapped + */ uint8_t Swap (uint8_t val); + /** + * \brief Swap a value byte order + * \param val the value + * \returns the value with byte order swapped + */ uint16_t Swap (uint16_t val); + /** + * \brief Swap a value byte order + * \param val the value + * \returns the value with byte order swapped + */ uint32_t Swap (uint32_t val); + /** + * \brief Swap the byte order of a Pcap file header + * \param from original file header + * \param to swapped file header + */ void Swap (PcapFileHeader *from, PcapFileHeader *to); + /** + * \brief Swap the byte order of a Pcap record header + * \param from original record header + * \param to swapped record header + */ void Swap (PcapRecordHeader *from, PcapRecordHeader *to); + /** + * \brief Write a Pcap file header + */ void WriteFileHeader (void); + /** + * \brief Write a Pcap packet header + * \param tsSec Time stamp (seconds part) + * \param tsUsec Time stamp (microseconds part) + * \param totalLen total packet length + * \returns the length of the packet to write in the Pcap file + */ uint32_t WritePacketHeader (uint32_t tsSec, uint32_t tsUsec, uint32_t totalLen); + + /** + * \brief Read and verify a Pcap file header + */ void ReadAndVerifyFileHeader (void); - std::string m_filename; - std::fstream m_file; - PcapFileHeader m_fileHeader; - bool m_swapMode; + std::string m_filename; //!< file name + std::fstream m_file; //!< file stream + PcapFileHeader m_fileHeader; //!< file header + bool m_swapMode; //!< swap mode }; } // namespace ns3 --- a/src/network/utils/queue.h +++ a/src/network/utils/queue.h @@ -45,6 +45,10 @@ class Queue : public Object { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); Queue (); @@ -151,8 +155,21 @@ private: + /** + * Push a packet in the queue + * \param p the packet to enqueue + * \return true if success, false if the packet has been dropped. + */ virtual bool DoEnqueue (Ptr p) = 0; + /** + * Pull a packet from the queue + * \return the packet. + */ virtual Ptr DoDequeue (void) = 0; + /** + * Peek the front packet in the queue + * \return the packet. + */ virtual Ptr DoPeek (void) const = 0; protected: @@ -164,16 +181,19 @@ void Drop (Ptr packet); private: + /// Traced callback: fired when a packet is enqueued TracedCallback > m_traceEnqueue; + /// Traced callback: fired when a packet is dequeued TracedCallback > m_traceDequeue; + /// Traced callback: fired when a packet is dropped TracedCallback > m_traceDrop; - uint32_t m_nBytes; - uint32_t m_nTotalReceivedBytes; - uint32_t m_nPackets; - uint32_t m_nTotalReceivedPackets; - uint32_t m_nTotalDroppedBytes; - uint32_t m_nTotalDroppedPackets; + uint32_t m_nBytes; //!< Number of bytes in the queue + uint32_t m_nTotalReceivedBytes; //!< Total received bytes + uint32_t m_nPackets; //!< Number of packets in the queue + uint32_t m_nTotalReceivedPackets; //!< Total received packets + uint32_t m_nTotalDroppedBytes; //!< Total dropped bytes + uint32_t m_nTotalDroppedPackets; //!< Total dropped packets }; } // namespace ns3 --- a/src/network/utils/radiotap-header.h +++ a/src/network/utils/radiotap-header.h @@ -35,7 +35,7 @@ * from a userspace application to the driver for transmission. * * @warning the radiotap header specification says that the fields included in - * the header should be aligned to their natural ize (e.g., 16-bit fields + * the header should be aligned to their natural size (e.g., 16-bit fields * aligned to 16-bit boundaries, 32-bit fields aligned to 32-bit boundaries, * and so on. This implementation does not enforce this. However, the radiotap * specification enforces an order in which fields have to appear (if they @@ -49,6 +49,10 @@ { public: RadiotapHeader(); + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); virtual TypeId GetInstanceTypeId (void) const; @@ -242,18 +246,16 @@ RADIOTAP_EXT = 0x10000000 }; - void CheckAddChannelField (); + uint16_t m_length; //!< entire length of radiotap data + header + uint32_t m_present; //!< bits describing which fields follow header - uint16_t m_length; - uint32_t m_present; - - uint64_t m_tsft; - uint8_t m_flags; - uint8_t m_rate; - uint16_t m_channelFreq; - uint16_t m_channelFlags; - int8_t m_antennaSignal; - int8_t m_antennaNoise; + uint64_t m_tsft; //!< Time Synchronization Function Timer (when the first bit of the MPDU arrived at the MAC) + uint8_t m_flags; //!< Properties of transmitted and received frames. + uint8_t m_rate; //!< TX/RX data rate in units of 500 kbps + uint16_t m_channelFreq; //!< Tx/Rx frequency in MHz. + uint16_t m_channelFlags; //!< Tx/Rx channel flags. + int8_t m_antennaSignal; //!< RF signal power at the antenna, dB difference from an arbitrary, fixed reference. + int8_t m_antennaNoise; //!< RF noise power at the antenna, dB difference from an arbitrary, fixed reference. }; } // namespace ns3 --- a/src/network/utils/red-queue.h +++ a/src/network/utils/red-queue.h @@ -74,7 +74,7 @@ class TraceContainer; class UniformRandomVariable; -/* +/** * \ingroup queue * * \brief A RED packet queue @@ -82,6 +82,10 @@ class RedQueue : public Queue { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); /** * \brief RedQueue Constructor @@ -99,24 +103,22 @@ /** * \brief Stats - * */ typedef struct { - uint32_t unforcedDrop; /// Early probability drops - uint32_t forcedDrop; /// Forced drops, qavg > max threshold - uint32_t qLimDrop; /// Drops due to queue limits + uint32_t unforcedDrop; //!< Early probability drops + uint32_t forcedDrop; //!< Forced drops, qavg > max threshold + uint32_t qLimDrop; //!< Drops due to queue limits } Stats; /** * \brief Drop types - * */ enum { - DTYPE_NONE, /// Ok, no drop - DTYPE_FORCED, /// A "forced" drop - DTYPE_UNFORCED, /// An "unforced" (random) drop + DTYPE_NONE, //!< Ok, no drop + DTYPE_FORCED, //!< A "forced" drop + DTYPE_UNFORCED, //!< An "unforced" (random) drop }; /** @@ -179,90 +181,103 @@ virtual Ptr DoDequeue (void); virtual Ptr DoPeek (void) const; - // ... + /** + * \brief Initialize the queue parameters. + * + * Note: if the link bandwidth changes in the course of the + * simulation, the bandwidth-dependent RED parameters do not change. + * This should be fixed, but it would require some extra parameters, + * and didn't seem worth the trouble... + */ void InitializeParams (void); - // Compute the average queue size + /** + * \brief Compute the average queue size + * \param nQueued number of queued packets + * \param m simulated number of packets arrival during idle period + * \param qAvg average queue size + * \param qW queue weight given to cur q size sample + * \returns new average queue size + */ double Estimator (uint32_t nQueued, uint32_t m, double qAvg, double qW); - // Check if packet p needs to be dropped due to probability mark + /** + * \brief Check if packet p needs to be dropped due to probability mark + * \param p packet + * \param qSize queue size + * \returns 0 for no drop/mark, 1 for drop + */ uint32_t DropEarly (Ptr p, uint32_t qSize); - // Returns a probability using these function parameters for the DropEarly funtion - double CalculatePNew (double qAvg, double maxTh, bool gentle, double vA, + /** + * \brief Returns a probability using these function parameters for the DropEarly function + * \param qAvg Average queue length + * \param maxTh Max avg length threshold + * \param gentle "gentle" algorithm + * \param vA vA + * \param vB vB + * \param vC vC + * \param vD vD + * \param maxP max_p + * \returns Prob. of packet drop before "count" + */ + double CalculatePNew (double qAvg, double , bool gentle, double vA, double vB, double vC, double vD, double maxP); - // Returns a probability using these function parameters for the DropEarly funtion + /** + * \brief Returns a probability using these function parameters for the DropEarly function + * \param p Prob. of packet drop before "count" + * \param count number of packets since last random number generation + * \param countBytes number of bytes since last drop + * \param meanPktSize Avg pkt size + * \param wait True for waiting between dropped packets + * \param size packet size + * \returns Prob. of packet drop + */ double ModifyP (double p, uint32_t count, uint32_t countBytes, uint32_t meanPktSize, bool wait, uint32_t size); - std::list > m_packets; + std::list > m_packets; //!< packets in the queue - uint32_t m_bytesInQueue; - bool m_hasRedStarted; - Stats m_stats; + uint32_t m_bytesInQueue; //!< bytes in the queue + bool m_hasRedStarted; //!< True if RED has started + Stats m_stats; //!< RED statistics // ** Variables supplied by user - // Bytes or packets? - QueueMode m_mode; - // Avg pkt size - uint32_t m_meanPktSize; - // Avg pkt size used during idle times - uint32_t m_idlePktSize; - // True for waiting between dropped packets - bool m_isWait; - // True to increases dropping prob. slowly when ave queue exceeds maxthresh - bool m_isGentle; - // Min avg length threshold (bytes) - double m_minTh; - // Max avg length threshold (bytes), should be >= 2*minTh - double m_maxTh; - // Queue limit in bytes / packets - uint32_t m_queueLimit; - // Queue weight given to cur q size sample - double m_qW; - // The max probability of dropping a packet - double m_lInterm; - // Ns-1 compatibility - bool m_isNs1Compat; - // Link bandwidth - DataRate m_linkBandwidth; - // Link delay - Time m_linkDelay; + QueueMode m_mode; //!< Mode (Bytes or packets) + uint32_t m_meanPktSize; //!< Avg pkt size + uint32_t m_idlePktSize; //!< Avg pkt size used during idle times + bool m_isWait; //!< True for waiting between dropped packets + bool m_isGentle; //!< True to increases dropping prob. slowly when ave queue exceeds maxthresh + double m_minTh; //!< Min avg length threshold (bytes) + double m_maxTh; //!< Max avg length threshold (bytes), should be >= 2*minTh + uint32_t m_queueLimit; //!< Queue limit in bytes / packets + double m_qW; //!< Queue weight given to cur queue size sample + double m_lInterm; //!< The max probability of dropping a packet + bool m_isNs1Compat; //!< Ns-1 compatibility + DataRate m_linkBandwidth; //!< Link bandwidth + Time m_linkDelay; //!< Link delay // ** Variables maintained by RED - // Prob. of packet drop before "count" - double m_vProb1; - // v_prob = v_a * v_ave + v_b - double m_vA; - double m_vB; - // Used for "gentle" mode - double m_vC; - // Used for "gentle" mode - double m_vD; - // Current max_p - double m_curMaxP; - // Prob. of packet drop - double m_vProb; - // # of bytes since last drop - uint32_t m_countBytes; - // 0 when average queue first exceeds thresh - uint32_t m_old; - // 0/1 idle status - uint32_t m_idle; - // packet time constant in packets/second - double m_ptc; - // Average queue length - double m_qAvg; - // number of packets since last random number generation - uint32_t m_count; - /* + double m_vProb1; //!< Prob. of packet drop before "count" + double m_vA; //!< 1.0 / (m_maxTh - m_minTh) + double m_vB; //!< -m_minTh / (m_maxTh - m_minTh) + double m_vC; //!< (1.0 - m_curMaxP) / m_maxTh - used in "gentle" mode + double m_vD; //!< 2.0 * m_curMaxP - 1.0 - used in "gentle" mode + double m_curMaxP; //!< Current max_p + double m_vProb; //!< Prob. of packet drop + uint32_t m_countBytes; //!< Number of bytes since last drop + uint32_t m_old; //!< 0 when average queue first exceeds threshold + uint32_t m_idle; //!< 0/1 idle status + double m_ptc; //!< packet time constant in packets/second + double m_qAvg; //!< Average queue length + uint32_t m_count; //!< Number of packets since last random number generation + /** * 0 for default RED * 1 experimental (see red-queue.cc) * 2 experimental (see red-queue.cc) * 3 use Idle packet size in the ptc */ uint32_t m_cautious; - // Start of current idle period - Time m_idleTime; + Time m_idleTime; //!< Start of current idle period - Ptr m_uv; + Ptr m_uv; //!< rng stream }; }; // namespace ns3 --- a/src/network/utils/sequence-number.h +++ a/src/network/utils/sequence-number.h @@ -341,27 +341,107 @@ friend std::istream & operator >> (std::istream &is, const SequenceNumber &val); private: // unimplemented operators + /** + * \brief Plus equals operator - unimplemented + * \param value value + * \returns sequence number + */ SequenceNumber& operator+= (SequenceNumber const &value); + /** + * \brief Minus equals operator - unimplemented + * \param value value + * \returns sequence number + */ SequenceNumber& operator-= (SequenceNumber const &value); + /** + * \brief Multiplication operator - unimplemented + * \param b value + * \returns sequence number + */ SequenceNumber operator* (const SequenceNumber& b) const; + /** + * \brief Division operator - unimplemented + * \param b value + * \returns sequence number + */ SequenceNumber operator/ (const SequenceNumber& b) const; + /** + * \brief Modulo operator - unimplemented + * \param b value + * \returns sequence number + */ SequenceNumber operator% (const SequenceNumber& b) const; + /** + * \brief Logical NOT operator - unimplemented + * \returns condition + */ bool operator ! () const; + /** + * \brief Logical AND operator - unimplemented + * \param b value + * \returns condition + */ bool operator && (const SequenceNumber& b) const; + /** + * \brief Logical OR operator - unimplemented + * \param b value + * \returns condition + */ bool operator || (const SequenceNumber& b) const; + /** + * \brief Bitwise NOT operator - unimplemented + * \returns sequence number + */ SequenceNumber operator~ () const; + /** + * \brief Bitwise AND operator - unimplemented + * \param b value + * \returns sequence number + */ SequenceNumber operator& (const SequenceNumber& b) const; + /** + * \brief Bitwise OR operator - unimplemented + * \param b value + * \returns sequence number + */ SequenceNumber operator| (const SequenceNumber& b) const; + /** + * \brief Bitwise XOR operator - unimplemented + * \param b value + * \returns sequence number + */ SequenceNumber operator^ (const SequenceNumber& b) const; + /** + * \brief Bitwise left shift operator - unimplemented + * \param b value + * \returns sequence number + */ SequenceNumber operator<< (const SequenceNumber& b) const; + /** + * \brief Bitwise right shift operator - unimplemented + * \param b value + * \returns sequence number + */ SequenceNumber operator>> (const SequenceNumber& b) const; + /** + * \brief Indirection operator - unimplemented + * \returns integer + */ int operator* (); //SequenceNumber* operator& (); private: - NUMERIC_TYPE m_value; + NUMERIC_TYPE m_value; //!< Sequence number value }; + +/** + * \brief Stream insertion operator. + * + * \param os the stream + * \param val the value + * \returns a reference to the stream + */ template std::ostream & operator<< (std::ostream& os, const SequenceNumber &val) @@ -370,6 +450,14 @@ return os; } + +/** + * \brief Stream extraction operator. + * + * \param is the stream + * \param val the value + * \returns a reference to the stream + */ template std::istream & operator >> (std::istream &is, const SequenceNumber &val) { @@ -377,8 +465,9 @@ return is; } - +/// 32 bit Sequence number typedef SequenceNumber SequenceNumber32; +/// 16 bit Sequence number typedef SequenceNumber SequenceNumber16; } // namespace ns3 --- a/src/network/utils/simple-channel.h +++ a/src/network/utils/simple-channel.h @@ -36,6 +36,10 @@ class SimpleChannel : public Channel { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); SimpleChannel (); @@ -66,7 +70,7 @@ virtual Ptr GetDevice (uint32_t i) const; private: - std::vector > m_devices; + std::vector > m_devices; //!< devices connected by the channel }; } // namespace ns3 --- a/src/network/utils/simple-net-device.h +++ a/src/network/utils/simple-net-device.h @@ -45,6 +45,10 @@ class SimpleNetDevice : public NetDevice { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); SimpleNetDevice (); @@ -112,14 +116,14 @@ protected: virtual void DoDispose (void); private: - Ptr m_channel; - NetDevice::ReceiveCallback m_rxCallback; - NetDevice::PromiscReceiveCallback m_promiscCallback; - Ptr m_node; - uint16_t m_mtu; - uint32_t m_ifIndex; - Mac48Address m_address; - Ptr m_receiveErrorModel; + Ptr m_channel; //!< the channel the device is connected to + NetDevice::ReceiveCallback m_rxCallback; //!< Receive callback + NetDevice::PromiscReceiveCallback m_promiscCallback; //!< Promiscuous receive callback + Ptr m_node; //!< Node this netDevice is associated to + uint16_t m_mtu; //!< MTU + uint32_t m_ifIndex; //!< Interface index + Mac48Address m_address; //!< MAC address + Ptr m_receiveErrorModel; //!< Receive error model. /** * The trace source fired when the phy layer drops a packet it has received * due to the error model being active. Although SimpleNetDevice doesn't