From 46986f69e4a17923717464c120f4d227df561618 Mon Sep 17 00:00:00 2001 From: "Robin.Mueller" Date: Sat, 2 Nov 2019 23:30:12 +0100 Subject: [PATCH] serialize tools more documentation --- serialize/SerialBufferAdapter.cpp | 8 ++++---- serialize/SerialBufferAdapter.h | 8 ++++++++ serialize/SerialFixedArrayListAdapter.h | 11 +++++++++++ serialize/SerialLinkedListAdapter.h | 10 +++++++++- serialize/SerializeIF.h | 6 +++--- 5 files changed, 35 insertions(+), 8 deletions(-) diff --git a/serialize/SerialBufferAdapter.cpp b/serialize/SerialBufferAdapter.cpp index 3ed083bf..c5fcfb57 100644 --- a/serialize/SerialBufferAdapter.cpp +++ b/serialize/SerialBufferAdapter.cpp @@ -5,15 +5,15 @@ template SerialBufferAdapter::SerialBufferAdapter(const uint8_t* buffer, - T bufferLength, bool serializeLenght) : - serializeLength(serializeLenght), constBuffer(buffer), buffer(NULL), bufferLength( + T bufferLength, bool serializeLength) : + serializeLength(serializeLength), constBuffer(buffer), buffer(NULL), bufferLength( bufferLength) { } template SerialBufferAdapter::SerialBufferAdapter(uint8_t* buffer, T bufferLength, - bool serializeLenght) : - serializeLength(serializeLenght), constBuffer(NULL), buffer(buffer), bufferLength( + bool serializeLength) : + serializeLength(serializeLength), constBuffer(NULL), buffer(buffer), bufferLength( bufferLength) { } diff --git a/serialize/SerialBufferAdapter.h b/serialize/SerialBufferAdapter.h index 7cd75d55..7d192bb4 100644 --- a/serialize/SerialBufferAdapter.h +++ b/serialize/SerialBufferAdapter.h @@ -5,6 +5,14 @@ #include /** + * 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> serialBufferElement + * * \ingroup serialize */ template diff --git a/serialize/SerialFixedArrayListAdapter.h b/serialize/SerialFixedArrayListAdapter.h index 16919b62..821e8710 100644 --- a/serialize/SerialFixedArrayListAdapter.h +++ b/serialize/SerialFixedArrayListAdapter.h @@ -5,6 +5,17 @@ #include /** + * This adapter provides an interface for SerializeIF to serialize and deserialize + * buffers with a header containing the buffer length. + * + * Can be used by SerialLinkedListAdapter. + * + * Buffers with a size header inside that class can be declared with + * SerialFixedArrayListAdapter. + * 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 */ template diff --git a/serialize/SerialLinkedListAdapter.h b/serialize/SerialLinkedListAdapter.h index 44d9e15b..08d385ee 100644 --- a/serialize/SerialLinkedListAdapter.h +++ b/serialize/SerialLinkedListAdapter.h @@ -17,12 +17,20 @@ * An alternative to the AutoSerializeAdapter functions to implement the conversion * of object data to data streams or vice-versa, using linked lists. * - * All object members with a datatype are declared as SerializeElement inside the class. + * All object members with a datatype are declared as SerializeElement inside the class + * implementing this adapter. * * Buffers with a size header inside that class can be declared with * SerialFixedArrayListAdapter. * 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 .setNext(&linkHelper) + * and initialising the link helper as linkHelper(&SerialFixedArrayListAdapterElement). + * + * For buffers with no size header, declare + * SerializeElement> 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 diff --git a/serialize/SerializeIF.h b/serialize/SerializeIF.h index d86349ab..cada1e72 100644 --- a/serialize/SerializeIF.h +++ b/serialize/SerializeIF.h @@ -11,14 +11,14 @@ /** * An interface for alle classes which require translation of objects data into data streams and vice-versa. * - * If the target architecture is little endian (ARM), any data types created might + * 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. + * 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 little-endian. Otherwise, @c EndianSwapper has to be used. + * 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.