documentation related stuff

serialize/SerialBufferAdapter.h

@@ -5,14 +5,46 @@
 #include <framework/serialize/SerializeAdapter.h>
 
 /**
+ * This adapter provides an interface for SerializeIF to serialize or deserialize
+ * buffers with no length header but a known size.
+ *
+ * Additionally, the buffer length can be serialized too and will be put in front of the serialized buffer.
+ *
+ * Can be used with SerialLinkedListAdapter by declaring a SerializeElement with
+ * SerialElement<SerialBufferAdapter<bufferLengthType(will be uint8_t mostly)>> serialBufferElement.
+ * Right now, the SerialBufferAdapter must always be initialized with the buffer and size !
+ *
  * \ingroup serialize
  */
 template<typename T>
 class SerialBufferAdapter: public SerializeIF {
 public:
-	SerialBufferAdapter(const uint8_t * buffer, T bufferLength, bool serializeLenght = false);
-	SerialBufferAdapter(uint8_t* buffer, T bufferLength,
-			bool serializeLenght = false);
+	/**
+	 * Constructor for constant uint8_t buffer. Length field can be serialized optionally.
+	 * Type of length can be supplied as template type.
+	 * @param buffer
+	 * @param bufferLength
+	 * @param serializeLength
+	 */
+	SerialBufferAdapter(const uint8_t * buffer, T bufferLength, bool serializeLength = false);
+
+	/**
+	 * Constructor for non-constant uint8_t buffer. Length field can be serialized optionally.
+	 * Type of length can be supplied as template type.
+	 * @param buffer
+	 * @param bufferLength
+	 * @param serializeLength
+	 */
+	SerialBufferAdapter(uint8_t* buffer, T bufferLength, bool serializeLength = false);
+
+	/**
+	 * Constructoor for non-constant uint32_t buffer. Length field can be serialized optionally.
+	 * Type of length can be supplied as template type.
+	 * @param buffer
+	 * @param bufferLength
+	 * @param serializeLength
+	 */
+	SerialBufferAdapter(uint32_t* buffer,T bufferLength, bool serializeLength = false);
 
 	virtual ~SerialBufferAdapter();
 
@@ -23,7 +55,19 @@ public:
 
 	virtual ReturnValue_t deSerialize(const uint8_t** buffer, int32_t* size,
 			bool bigEndian);
+
+	uint8_t * getBuffer();
+	const uint8_t * getConstBuffer();
+	void setBuffer(uint8_t * buffer_, T bufferLength_);
+	void setBuffer(uint32_t * buffer_, T bufferLength_);
 private:
+
+	enum bufferType {
+		NORMAL,
+		CONST
+	};
+	bufferType currentBufferType;
+
 	bool serializeLength;
 	const uint8_t *constBuffer;
 	uint8_t *buffer;

serialize/SerialFixedArrayListAdapter.h

@@ -5,24 +5,48 @@
 #include <framework/serialize/SerialArrayListAdapter.h>
 
 /**
- * \ingroup serialize
+ * @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<SerialFixedArrayListAdapter<...>>.
+ * 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<BUFFER_TYPE, MAX_BUFFER_LENGTH, LENGTH_FIELD_TYPE>.
+ *  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
  */
-template<typename T, uint32_t MAX_SIZE, typename count_t = uint8_t>
-class SerialFixedArrayListAdapter : public FixedArrayList<T, MAX_SIZE, count_t>, public SerializeIF {
+template<typename BUFFER_TYPE, uint32_t MAX_SIZE, typename count_t = uint8_t>
+class SerialFixedArrayListAdapter : public FixedArrayList<BUFFER_TYPE, MAX_SIZE, count_t>, public SerializeIF {
 public:
+	/**
+	 * Constructor Arguments are forwarded to FixedArrayList constructor
+	 * @param args
+	 */
 	template<typename... Args>
-	SerialFixedArrayListAdapter(Args... args) : FixedArrayList<T, MAX_SIZE, count_t>(std::forward<Args>(args)...) {
+	SerialFixedArrayListAdapter(Args... args) : FixedArrayList<BUFFER_TYPE, MAX_SIZE, count_t>(std::forward<Args>(args)...) {
 	}
+
 	ReturnValue_t serialize(uint8_t** buffer, uint32_t* size,
 			const uint32_t max_size, bool bigEndian) const {
-		return SerialArrayListAdapter<T, count_t>::serialize(this, buffer, size, max_size, bigEndian);
+		return SerialArrayListAdapter<BUFFER_TYPE, count_t>::serialize(this, buffer, size, max_size, bigEndian);
 	}
+
 	uint32_t getSerializedSize() const {
-		return SerialArrayListAdapter<T, count_t>::getSerializedSize(this);
+		return SerialArrayListAdapter<BUFFER_TYPE, count_t>::getSerializedSize(this);
 	}
 	ReturnValue_t deSerialize(const uint8_t** buffer, int32_t* size,
 			bool bigEndian) {
-		return SerialArrayListAdapter<T, count_t>::deSerialize(this, buffer, size, bigEndian);
+		return SerialArrayListAdapter<BUFFER_TYPE, count_t>::deSerialize(this, buffer, size, bigEndian);
+	}
+
+	void swapArrayListEndianness() {
+		SerialArrayListAdapter<BUFFER_TYPE, count_t>::swapArrayListEndianness(this);
 	}
 };
 

serialize/SerialLinkedListAdapter.h

@@ -13,8 +13,30 @@
 #include <framework/serialize/SerializeIF.h>
 //This is where we need the SerializeAdapter!
 
-/**
- * \ingroup serialize
+ /**
+ * @brief  	Implement the conversion of object data to data streams
+ * 		   	or vice-versa, using linked lists.
+ * @details
+ * An alternative to the AutoSerializeAdapter functions
+ *   - All object members with a datatype are declared as SerializeElement<element_type>
+ * 	   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
+ *
+ * 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
+ *
+ * @ingroup serialize
  */
 template<typename T, typename count_t = uint8_t>
 class SerialLinkedListAdapter: public SinglyLinkedList<T>, public SerializeIF {
@@ -31,6 +53,16 @@ public:
 			SinglyLinkedList<T>(), printCount(printCount) {
 	}
 
+	/**
+	 * 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 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, uint32_t* size,
 			const uint32_t max_size, bool bigEndian) const {
 		if (printCount) {
@@ -73,6 +105,13 @@ public:
 		return size;
 	}
 
+	/**
+	 * 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, int32_t* size,
 			bool bigEndian) {
 		return deSerialize(SinglyLinkedList<T>::start, buffer, size, bigEndian);

serialize/SerializeAdapter.h

@@ -7,8 +7,53 @@
 #include <framework/serialize/SerializeIF.h>
 #include <string.h>
 
-/**
- * \ingroup serialize
+ /**
+ * @brief This adapter provides an interface to use the SerializeIF functions
+ * 		  with arbitrary template objects to facilitate and simplify the serialization of classes
+ * 		  with different multiple different data types into buffers and vice-versa.
+ * @details
+ * Examples:
+ * A report class is converted into a TM buffer. The report class implements a serialize functions and calls
+ * the AutoSerializeAdapter::serialize function repeatedly on all object data fields.
+ * The getSerializedSize function is implemented by calling the
+ * AutoSerializeAdapter::getSerializedSize function repeatedly on all data fields.
+ *
+ * The AutoSerializeAdapter functions can also be used as an alternative to memcpy
+ * to retrieve data out of a buffer directly into a class variable with data type T while being able to specify endianness.
+ * The boolean bigEndian specifies whether an endian swap is performed on the data before
+ * serialization or deserialization.
+ *
+ * If the target architecture is little endian (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:
+ *
+ *   1. Use the AutoSerializeAdapter::deSerialize function
+ *		The pointer *buffer will be incremented automatically by the typeSize of the object,
+ *		so this function can be called on &buffer repeatedly without adjusting pointer position.
+ *		Set bigEndian parameter to true to perform endian swapping.
+ *
+ *   	uint16_t data;
+ *   	int32_t dataLen = sizeof(data);
+ *   	ReturnValue_t result = AutoSerializeAdapter::deSerialize(&data,&buffer,&dataLen,true);
+ *
+ *   2. Perform a bitshift operation. Perform endian swapping if necessary:
+ *
+ *   	uint16_t data;
+ *   	data = buffer[targetByte1] << 8 | buffer[targetByte2];
+ *   	data = EndianSwapper::swap(data);
+ *
+ *   3. Memcpy can be used when data is little-endian. Perform endian-swapping if necessary.
+ *
+ *   	uint16_t data;
+ *   	memcpy(&data,buffer + positionOfTargetByte1,sizeof(data));
+ *   	data = EndianSwapper::swap(data);
+ *
+ * When serializing for downlink, the packets are generally serialized assuming big endian data format
+ * like seen in TmPacketStored.cpp for example.
+ *
+ * @ingroup serialize
  */
 template<typename T, int>
 class SerializeAdapter_ {
@@ -35,6 +80,14 @@ public:
 		}
 	}
 
+	/**
+	 * Deserialize buffer into object
+	 * @param object [out] Object to be deserialized with buffer data
+	 * @param buffer buffer containing the data. Non-Const pointer to non-const pointer to const buffer.
+	 * @param size int32_t type to allow value to be values smaller than 0, needed for range/size checking
+	 * @param bigEndian Specify endianness
+	 * @return
+	 */
 	ReturnValue_t deSerialize(T* object, const uint8_t** buffer, int32_t* size,
 			bool bigEndian) {
 		T tmp;
@@ -100,7 +153,7 @@ public:
 	}
 };
 
-
+// No type specification necessary here.
 class AutoSerializeAdapter {
 public:
 	template<typename T>

serialize/SerializeElement.h

@@ -6,11 +6,23 @@
 #include <utility>
 
 /**
- * \ingroup serialize
+ * @brief This class is used to mark datatypes for serialization with the
+ *        SerialLinkedListAdapter
+ * @details
+ * Used by declaring any arbitrary datatype with SerializeElement<T> myVariable,
+ * inside a SerialLinkedListAdapter implementation and setting the sequence
+ * of objects with setNext() and setStart().
+ * Serilization and Deserialization is then performed automatically in
+ * specified sequence order.
+ * @ingroup serialize
  */
 template<typename T>
 class SerializeElement : public SerializeIF, public LinkedElement<SerializeIF> {
 public:
+	/**
+	 * Arguments are forwarded to the element datatype constructor
+	 * @param args
+	 */
 	template<typename... Args>
 	SerializeElement(Args... args) : LinkedElement<SerializeIF>(this), entry(std::forward<Args>(args)...) {
 

serialize/SerializeIF.h

@@ -4,13 +4,27 @@
 #include <framework/returnvalues/HasReturnvaluesIF.h>
 
 /**
- * \defgroup serialize Serialization
+ * @defgroup serialize Serialization
  * Contains serialisation services.
  */
 
 /**
- * Translation of objects into data streams.
- * \ingroup serialize
+ * @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:
+ *
+ *   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.
+ *
+ * When serializing for downlink, the packets are generally serialized assuming big endian data format
+ * like seen in TmPacketStored.cpp for example.
+ *
+ * @ingroup serialize
  */
 class SerializeIF {
 public: