From 9284fe81da14628f26001536e22a66c1873517f3 Mon Sep 17 00:00:00 2001 From: "Robin.Mueller" Date: Wed, 15 Apr 2020 20:53:03 +0200 Subject: [PATCH] added override specifiers, some doc fixes --- container/FixedArrayList.h | 20 ++++++++-- serialize/EndianSwapper.h | 27 +++++++++++--- serialize/SerialArrayListAdapter.h | 8 ++-- serialize/SerialBufferAdapter.h | 4 +- serialize/SerialFixedArrayListAdapter.h | 33 ++++++++++------- serialize/SerialLinkedListAdapter.h | 49 +++++++++++++++---------- serialize/SerializeAdapterInternal.h | 5 ++- serialize/SerializeDoc.h | 16 -------- serialize/SerializeElement.h | 17 +++++---- serialize/SerializeIF.h | 27 +++++++------- 10 files changed, 117 insertions(+), 89 deletions(-) delete mode 100644 serialize/SerializeDoc.h diff --git a/container/FixedArrayList.h b/container/FixedArrayList.h index 12e292b4a..5d93db90c 100644 --- a/container/FixedArrayList.h +++ b/container/FixedArrayList.h @@ -12,14 +12,26 @@ class FixedArrayList: public ArrayList { private: T data[MAX_SIZE]; public: + /** + * (Robin) Maybe we should also implement move assignment and move ctor. + * Or at least delete them. + */ FixedArrayList() : ArrayList(data, MAX_SIZE) { } - //We could create a constructor to initialize the fixed array list with data and the known size field - //so it can be used for serialization too (with SerialFixedArrrayListAdapter) - //is this feasible? - FixedArrayList(T * data_, count_t count, bool swapArrayListEndianess = false): + // (Robin): We could create a constructor to initialize the fixed array list with data and the known size field + // so it can be used for serialization too (with SerialFixedArrrayListAdapter) + // is this feasible? + /** + * Initialize a fixed array list with data and number of data fields. + * Endianness of entries can be swapped optionally. + * @param data_ + * @param count + * @param swapArrayListEndianess + */ + FixedArrayList(T * data_, count_t count, + bool swapArrayListEndianess = false): ArrayList(data, MAX_SIZE) { memcpy(this->data, data_, count * sizeof(T)); this->size = count; diff --git a/serialize/EndianSwapper.h b/serialize/EndianSwapper.h index 9f621902f..5ba6fd324 100644 --- a/serialize/EndianSwapper.h +++ b/serialize/EndianSwapper.h @@ -13,6 +13,12 @@ class EndianSwapper { private: EndianSwapper() {}; public: + /** + * Swap the endianness of a variable with arbitrary type + * @tparam T Type of variable + * @param in variable + * @return Variable with swapped endianness + */ template static T swap(T in) { #ifndef BYTE_ORDER_SYSTEM @@ -31,7 +37,14 @@ public: #error Unknown Byte Order #endif } - static void swap(uint8_t* out, const uint8_t* in, uint32_t size) { + + /** + * Swap the endianness of a buffer. + * @param out + * @param in + * @param size + */ + static void swap(uint8_t* out, const uint8_t* in, size_t size) { #ifndef BYTE_ORDER_SYSTEM #error BYTE_ORDER_SYSTEM not defined #elif BYTE_ORDER_SYSTEM == LITTLE_ENDIAN @@ -47,21 +60,23 @@ public: /** * Swap endianness of buffer entries - * Template argument specifies buffer type + * Template argument specifies buffer type. The number of entries + * (not the buffer size!) must be supplied * @param out * @param in - * @param size + * @param size Number of buffer entries (not size of buffer in bytes!) */ template - static void swap(T * out, const T * in, uint32_t size) { + static void swap(T * out, const T * in, uint32_t entries) { #ifndef BYTE_ORDER_SYSTEM #error BYTE_ORDER_SYSTEM not defined #elif BYTE_ORDER_SYSTEM == LITTLE_ENDIAN const uint8_t * in_buffer = reinterpret_cast(in); uint8_t * out_buffer = reinterpret_cast(out); - for (uint8_t count = 0; count < size; count++) { + for (uint8_t count = 0; count < entries; count++) { for(uint8_t i = 0; i < sizeof(T);i++) { - out_buffer[sizeof(T)* (count + 1) - i - 1] = in_buffer[count * sizeof(T) + i]; + out_buffer[sizeof(T)* (count + 1) - i - 1] = + in_buffer[count * sizeof(T) + i]; } } return; diff --git a/serialize/SerialArrayListAdapter.h b/serialize/SerialArrayListAdapter.h index 6a3a276d9..4f3b82e68 100644 --- a/serialize/SerialArrayListAdapter.h +++ b/serialize/SerialArrayListAdapter.h @@ -13,7 +13,7 @@ /** * Also serializes length field ! - * \ingroup serialize + * @ingroup serialize */ template class SerialArrayListAdapter : public SerializeIF { @@ -22,7 +22,7 @@ public: } virtual ReturnValue_t serialize(uint8_t** buffer, size_t* size, - const size_t max_size, bool bigEndian) const { + const size_t max_size, bool bigEndian) const override { return serialize(adaptee, buffer, size, max_size, bigEndian); } @@ -41,7 +41,7 @@ public: return result; } - virtual size_t getSerializedSize() const { + virtual size_t getSerializedSize() const override { return getSerializedSize(adaptee); } @@ -57,7 +57,7 @@ public: } virtual ReturnValue_t deSerialize(const uint8_t** buffer, size_t* size, - bool bigEndian) { + bool bigEndian) override { return deSerialize(adaptee, buffer, size, bigEndian); } diff --git a/serialize/SerialBufferAdapter.h b/serialize/SerialBufferAdapter.h index 4421f3414..d414573cb 100644 --- a/serialize/SerialBufferAdapter.h +++ b/serialize/SerialBufferAdapter.h @@ -45,7 +45,7 @@ public: virtual ~SerialBufferAdapter(); virtual ReturnValue_t serialize(uint8_t** buffer, size_t* size, - const size_t max_size, bool bigEndian) const; + const size_t max_size, bool bigEndian) const override; virtual size_t getSerializedSize() const; @@ -62,7 +62,7 @@ public: * @return */ virtual ReturnValue_t deSerialize(const uint8_t** buffer, size_t* size, - bool bigEndian); + bool bigEndian) override; uint8_t * getBuffer(); const uint8_t * getConstBuffer(); diff --git a/serialize/SerialFixedArrayListAdapter.h b/serialize/SerialFixedArrayListAdapter.h index 22c4b3a8b..6e13ff6f4 100644 --- a/serialize/SerialFixedArrayListAdapter.h +++ b/serialize/SerialFixedArrayListAdapter.h @@ -5,19 +5,24 @@ #include /** - * @brief This adapter provides an interface for SerializeIF to serialize and deserialize - * buffers with a header containing the buffer length. + * @brief This adapter provides an interface for SerializeIF to serialize and + * deserialize buffers with a header containing the buffer length. * @details - * * Can be used by SerialLinkedListAdapter by declaring * as a linked element with SerializeElement>. - * The sequence of objects is defined in the constructor by using the setStart and setNext functions. + * The sequence of objects is defined in the constructor by + * using the setStart and setNext functions. * * 1. Buffers with a size header inside that class can be declared with - * SerialFixedArrayListAdapter. - * 2. MAX_BUFFER_LENGTH specifies the maximum allowed number of elements in FixedArrayList - * 3. LENGTH_FIELD_TYPE specifies the data type of the buffer header containing the buffer size - * (defaults to 1 byte length field) that follows + * @code + * SerialFixedArrayListAdapter mySerialFixedArrayList(...). + * @endcode + * 2. MAX_BUFFER_LENGTH specifies the maximum allowed number of elements + * in FixedArrayList. + * 3. LENGTH_FIELD_TYPE specifies the data type of the buffer header + * containing the buffer size (defaults to 1 byte length field) + * that follows. * * @ingroup serialize */ @@ -27,7 +32,8 @@ class SerialFixedArrayListAdapter : public SerializeIF { public: /** - * Constructor Arguments are forwarded to FixedArrayList constructor + * Constructor Arguments are forwarded to FixedArrayList constructor. + * Refer to the fixed array list constructors for different options. * @param args */ template @@ -35,8 +41,8 @@ public: FixedArrayList(std::forward(args)...) {} - ReturnValue_t serialize(uint8_t** buffer, size_t* size, - const size_t max_size, bool bigEndian) const { + virtual ReturnValue_t serialize(uint8_t** buffer, size_t* size, + const size_t max_size, bool bigEndian) const override { return SerialArrayListAdapter::serialize(this, buffer, size, max_size, bigEndian); } @@ -45,8 +51,9 @@ public: return SerialArrayListAdapter:: getSerializedSize(this); } - ReturnValue_t deSerialize(const uint8_t** buffer, size_t* size, - bool bigEndian) { + + virtual ReturnValue_t deSerialize(const uint8_t** buffer, size_t* size, + bool bigEndian) override { return SerialArrayListAdapter::deSerialize(this, buffer, size, bigEndian); } diff --git a/serialize/SerialLinkedListAdapter.h b/serialize/SerialLinkedListAdapter.h index 85f239b3c..8cb9afc8b 100644 --- a/serialize/SerialLinkedListAdapter.h +++ b/serialize/SerialLinkedListAdapter.h @@ -18,23 +18,25 @@ * or vice-versa, using linked lists. * @details * An alternative to the AutoSerializeAdapter functions - * - All object members with a datatype are declared as SerializeElement - * members inside the class implementing this adapter. - * - The element type can also be a SerialBufferAdapter to de-/serialize buffers, - * with a known size, where the size can also be serialized - * - The element type can also be a SerialFixedArrayListAdapter to de-/serialize buffers - * with a size header, which is scanned automatically + * - All object members with a datatype are declared as + * SerializeElement members inside the class + * implementing this adapter. + * - The element type can also be a SerialBufferAdapter to + * de-/serialize buffers with a known size + * - The element type can also be a SerialFixedArrayListAdapter to + * de-/serialize buffers with a size header, which is scanned automatically. * * The sequence of objects is defined in the constructor by using * the setStart and setNext functions. * - * - The serialization process is done by instantiating the class and - * calling serializ after all SerializeElement entries have been set by - * using the constructor or setter functions. An additional size variable can be supplied - * which is calculated/incremented automatically - * - The deserialization process is done by instantiating the class and supplying - * a buffer with the data which is converted into an object. The size of - * data to serialize can be supplied and is decremented in the function + * 1. The serialization process is done by instantiating the class and + * calling serialize after all SerializeElement entries have been set by + * using the constructor or setter functions. An additional size variable + * can be supplied which is calculated/incremented automatically. + * 2. The deserialization process is done by instantiating the class and + * supplying a buffer with the data which is converted into an object. + * The size of data to serialize can be supplied and is + * decremented in the function. Range checking is done internally. * * @ingroup serialize */ @@ -55,10 +57,12 @@ public: bool printCount = false) : SinglyLinkedList(start), printCount(printCount) { } + SerialLinkedListAdapter(LinkedElement* first, bool printCount = false) : SinglyLinkedList(first), printCount(printCount) { } + SerialLinkedListAdapter(bool printCount = false) : SinglyLinkedList(), printCount(printCount) { } @@ -66,15 +70,16 @@ public: /** * Serialize object implementing this adapter into the supplied buffer * and calculate the serialized size - * @param buffer [out] Object is serialized into this buffer. Note that the buffer pointer - * *buffer is incremented automatically inside the respective serialize functions + * @param buffer [out] Object is serialized into this buffer. + * Note that the buffer pointer *buffer is incremented automatically + * inside the respective serialize functions * @param size [out] Calculated serialized size. Don't forget to set to 0. * @param max_size * @param bigEndian Specify endianness * @return */ virtual ReturnValue_t serialize(uint8_t** buffer, size_t* size, - const size_t max_size, bool bigEndian) const { + const size_t max_size, bool bigEndian) const override{ if (printCount) { count_t mySize = SinglyLinkedList::getSize(); ReturnValue_t result = SerializeAdapter::serialize(&mySize, @@ -98,7 +103,9 @@ public: } return result; } - virtual size_t getSerializedSize() const { + + + virtual size_t getSerializedSize() const override { if (printCount) { return SerialLinkedListAdapter::getSerializedSize() + sizeof(count_t); @@ -106,6 +113,7 @@ public: return getSerializedSize(SinglyLinkedList::start); } } + static uint32_t getSerializedSize(const LinkedElement *element) { uint32_t size = 0; while (element != NULL) { @@ -115,15 +123,17 @@ public: return size; } + /** - * Deserialize supplied buffer with supplied size into object implementing this adapter + * Deserialize supplied buffer with supplied size into object + * implementing this adapter. * @param buffer * @param size Decremented in respective deSerialize functions automatically * @param bigEndian Specify endianness * @return */ virtual ReturnValue_t deSerialize(const uint8_t** buffer, size_t* size, - bool bigEndian) { + bool bigEndian) override { return deSerialize(SinglyLinkedList::start, buffer, size, bigEndian); } @@ -138,7 +148,6 @@ public: } bool printCount; - }; #endif /* SERIALLINKEDLISTADAPTER_H_ */ diff --git a/serialize/SerializeAdapterInternal.h b/serialize/SerializeAdapterInternal.h index 0caf67868..c57af0c95 100644 --- a/serialize/SerializeAdapterInternal.h +++ b/serialize/SerializeAdapterInternal.h @@ -12,8 +12,9 @@ #include /** - * This template specialization will be chosen for fundamental types, - * based on partial template specialization + * This template specialization will be chosen for fundamental types or + * anything else not implementing SerializeIF, based on partial + * template specialization. * @tparam T * @tparam */ diff --git a/serialize/SerializeDoc.h b/serialize/SerializeDoc.h deleted file mode 100644 index 6186b77b7..000000000 --- a/serialize/SerializeDoc.h +++ /dev/null @@ -1,16 +0,0 @@ -/** - * @page serialPage Serialization Tools - * This page refers to the serialization tools included in framework/serialize. - * The serialization tools are a useful tool to convert object data into raw - * buffers and vice-versa. Here is a rough overview which tool to use for - * which purpose. - * - * @section endSwapper Endian Swapper - * This header file includes tools to do simple serial order swapping - * - * @section serialiezIF SerializeIF - * - * @section serElement SerializeElement - * - */ - diff --git a/serialize/SerializeElement.h b/serialize/SerializeElement.h index 592968c1f..4717ae17f 100644 --- a/serialize/SerializeElement.h +++ b/serialize/SerializeElement.h @@ -24,17 +24,18 @@ public: * @param args */ template - SerializeElement(Args... args) : LinkedElement(this), entry(std::forward(args)...) { + SerializeElement(Args... args): + LinkedElement(this), + entry(std::forward(args)...) {} - } - SerializeElement() : LinkedElement(this) { - } + SerializeElement() : LinkedElement(this) {} T entry; - ReturnValue_t serialize(uint8_t** buffer, size_t* size, - const size_t max_size, bool bigEndian) const { - return SerializeAdapter::serialize(&entry, buffer, size, max_size, bigEndian); + virtual ReturnValue_t serialize(uint8_t** buffer, size_t* size, + const size_t max_size, bool bigEndian) const override { + return SerializeAdapter::serialize(&entry, buffer, size, + max_size, bigEndian); } size_t getSerializedSize() const { @@ -42,7 +43,7 @@ public: } virtual ReturnValue_t deSerialize(const uint8_t** buffer, size_t* size, - bool bigEndian) { + bool bigEndian) override { return SerializeAdapter::deSerialize(&entry, buffer, size, bigEndian); } diff --git a/serialize/SerializeIF.h b/serialize/SerializeIF.h index 6036518a8..5f8102c86 100644 --- a/serialize/SerializeIF.h +++ b/serialize/SerializeIF.h @@ -3,11 +3,6 @@ #include #include -#include - -#ifndef ssize_t -typedef std::make_signed::type ssize_t; -#endif /** * @defgroup serialize Serialization @@ -18,17 +13,21 @@ typedef std::make_signed::type ssize_t; * @brief An interface for alle classes which require * translation of objects data into data streams and vice-versa. * @details - * If the target architecture is little endian (e.g. ARM), any data types created might - * have the wrong endiness if they are to be used for the FSFW. - * There are three ways to retrieve data out of a buffer to be used in the FSFW to use - * regular aligned (big endian) data. This can also be applied to uint32_t and uint64_t: + * If the target architecture is little endian (e.g. ARM), any data types + * created might have the wrong endianess if they are to be used for the FSFW. + * Depending on the system architecture, endian correctness must be assured, + * This is important for incoming and outgoing data. The internal handling + * of data should be performed in the native system endianness. + * There are three ways to copy data (with different options to ensure + * endian correctness): * - * 1. Use the @c AutoSerializeAdapter::deSerialize function with @c bigEndian = true - * 2. Perform a bitshift operation - * 3. @c memcpy can be used when data is in little-endian format. Otherwise, @c EndianSwapper has to be used in conjuction. + * 1. Use the @c AutoSerializeAdapter::deSerialize function (with + * the endian flag) + * 2. Perform a bitshift operation (with correct order) + * 3. @c memcpy (with @c EndianSwapper if necessary) * - * When serializing for downlink, the packets are generally serialized assuming big endian data format - * like seen in TmPacketStored.cpp for example. + * When serializing for downlink, the packets are generally serialized + * assuming big endian data format like seen in TmPacketStored.cpp for example. * * @ingroup serialize */