Serialization documentation update
This commit is contained in:
parent
3159ccbc40
commit
8168885dd9
@ -5,6 +5,10 @@
|
||||
#include <cstring>
|
||||
#include <iostream>
|
||||
|
||||
/**
|
||||
* @brief Can be used to swap endianness of data
|
||||
* into big endian
|
||||
*/
|
||||
class EndianSwapper {
|
||||
private:
|
||||
EndianSwapper() {
|
||||
|
@ -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 {
|
||||
|
@ -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);
|
||||
|
@ -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>
|
||||
|
@ -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> {
|
||||
|
@ -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:
|
||||
|
Loading…
Reference in New Issue
Block a user