Serialization documentation update

This commit is contained in:
Robin Müller 2019-12-08 22:57:03 +01:00
parent 3159ccbc40
commit 8168885dd9
6 changed files with 70 additions and 39 deletions

View File

@ -5,6 +5,10 @@
#include <cstring>
#include <iostream>
/**
* @brief Can be used to swap endianness of data
* into big endian
*/
class EndianSwapper {
private:
EndianSwapper() {

View File

@ -5,18 +5,18 @@
#include <framework/serialize/SerialArrayListAdapter.h>
/**
* This adapter provides an interface for SerializeIF to serialize and deserialize
* buffers with a header containing the buffer length.
*
* Can be used by SerialLinkedListAdapter.
*
* @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 using this type in
* SerializeElement<>
* Buffers with a size header inside that class can be declared with
* SerialFixedArrayListAdapter<uint8_t,MAX_BUFFER_LENGTH,typeOfMaxData>.
* SerialFixedArrayListAdapter<bufferType,MAX_BUFFER_LENGTH,typeOfMaxData>.
* typeOfMaxData specifies the data type of the buffer header containing the buffer size that follows
* and MAX_BUFFER_LENGTH specifies the maximum allowed value for the buffer size.
* The sequence of objects is defined in the constructor by using the setStart and setNext functions.
*
* \ingroup serialize
* @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 {

View File

@ -14,29 +14,30 @@
//This is where we need the SerializeAdapter!
/**
* An alternative to the AutoSerializeAdapter functions to implement the conversion
* of object data to data streams or vice-versa, using linked lists.
* @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>
* 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<element_type> inside the class
* implementing this adapter.
* The sequence of objects is defined in the constructor by using
* the setStart and setNext functions.
*
* Buffers with a size header inside that class can be declared with
* SerialFixedArrayListAdapter<uint8_t,MAX_BUFFER_LENGTH,typeOfMaxData>.
* typeOfMaxData specifies the data type of the buffer header containing the buffer size that follows
* and MAX_BUFFER_LENGTH specifies the maximum allowed value for the buffer size.
* Please note that a direct link from a linked element to a SerialFixedArrayListAdapter element is not possible and a
* helper needs to be used by calling <LinkedElement>.setNext(&linkHelper)
* and initialising the link helper as linkHelper(&SerialFixedArrayListAdapterElement).
* - The serialization process is done by instantiating the class and
* calling the serialize after all SerializeElement entries have been set by
* using a 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
*
* For buffers with no size header, declare
* SerializeElement<SerializeBufferAdapter<T>> and initialise the buffer adapter in the constructor.
*
* The sequence of objects is defined in the constructor by using the setStart and setNext functions.
*
* The serialization and deserialization process is done by instantiating the class and
* calling the serialize or deserialize function.
*
* \ingroup serialize
* @ingroup serialize
*/
template<typename T, typename count_t = uint8_t>
class SerialLinkedListAdapter: public SinglyLinkedList<T>, public SerializeIF {
@ -53,6 +54,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) {
@ -95,6 +106,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);

View File

@ -8,10 +8,10 @@
#include <string.h>
/**
* 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 vice-versa.
*
* @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 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.
@ -49,7 +49,7 @@
* When serializing for downlink, the packets are generally serialized assuming big endian data format
* like seen in TmPacketStored.cpp for example.
*
* \ingroup serialize
* @ingroup serialize
*/
template<typename T, int>
class SerializeAdapter_ {
@ -141,7 +141,7 @@ public:
}
};
// No type specification necessary here.
class AutoSerializeAdapter {
public:
template<typename T>

View File

@ -6,7 +6,15 @@
#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> {

View File

@ -4,17 +4,18 @@
#include <framework/returnvalues/HasReturnvaluesIF.h>
/**
* \defgroup serialize Serialization
* @defgroup serialize Serialization
* Contains serialisation services.
*/
/**
* An interface for alle classes which require translation of objects data into data streams and vice-versa.
*
* @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:
* 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
@ -23,7 +24,7 @@
* When serializing for downlink, the packets are generally serialized assuming big endian data format
* like seen in TmPacketStored.cpp for example.
*
* \ingroup serialize
* @ingroup serialize
*/
class SerializeIF {
public: