WIP: documentation related commits #22
|
@ -7,8 +7,10 @@
|
|||
#include <framework/returnvalues/HasReturnvaluesIF.h>
|
||||
#include <framework/ipc/MessageQueueIF.h>
|
||||
/**
|
||||
* \brief Interface for component which uses actions
|
||||
* @brief
|
||||
* Interface for component which uses actions
|
||||
*
|
||||
* @details
|
||||
* This interface is used to execute actions in the component. Actions, in the sense of this interface, are activities with a well-defined beginning and
|
||||
* end in time. They may adjust sub-states of components, but are not supposed to change
|
||||
* the main mode of operation, which is handled with the HasModesIF described below.
|
||||
|
@ -23,6 +25,8 @@
|
|||
* parameters and immediately start execution of the action. It is, however, not required to
|
||||
* immediately finish execution. Instead, this may be deferred to a later point in time, at
|
||||
* which the component needs to inform the caller about finished or failed execution.
|
||||
*
|
||||
* \ingroup interfaces
|
||||
*/
|
||||
class HasActionsIF {
|
||||
public:
|
||||
|
|
|
@ -4,12 +4,41 @@
|
|||
#include <framework/container/RingBufferBase.h>
|
||||
#include <stddef.h>
|
||||
|
||||
/**
|
||||
* @brief Circular buffer implementation, useful for buffering into data streams.
|
||||
* @details Note that the deleteData() has to be called to increment the read pointer
|
||||
* @ingroup containers
|
||||
*/
|
||||
class SimpleRingBuffer: public RingBufferBase<> {
|
||||
public:
|
||||
SimpleRingBuffer(uint32_t size, bool overwriteOld);
|
||||
virtual ~SimpleRingBuffer();
|
||||
|
||||
/**
|
||||
* Write to circular buffer and increment write pointer by amount
|
||||
* @param data
|
||||
* @param amount
|
||||
* @return
|
||||
*/
|
||||
ReturnValue_t writeData(const uint8_t* data, uint32_t amount);
|
||||
|
||||
/**
|
||||
* Read from circular buffer at read pointer
|
||||
* @param data
|
||||
* @param amount
|
||||
* @param readRemaining
|
||||
* @param trueAmount
|
||||
* @return
|
||||
*/
|
||||
ReturnValue_t readData(uint8_t* data, uint32_t amount, bool readRemaining = false, uint32_t* trueAmount = NULL);
|
||||
|
||||
/**
|
||||
* Delete data starting by incrementing read pointer
|
||||
* @param amount
|
||||
* @param deleteRemaining
|
||||
* @param trueAmount
|
||||
* @return
|
||||
*/
|
||||
ReturnValue_t deleteData(uint32_t amount, bool deleteRemaining = false, uint32_t* trueAmount = NULL);
|
||||
private:
|
||||
// static const uint8_t TEMP_READ_PTR = 1;
|
||||
|
|
|
@ -112,8 +112,7 @@ public:
|
|||
* corresponds to.
|
||||
* \param dataSet The data set in which the variable shall register itself. If NULL,
|
||||
* the variable is not registered.
|
||||
* \param setWritable If this flag is set to true, changes in the value attribute can be
|
||||
* written back to the data pool, otherwise not.
|
||||
* \param setReadWriteMode
|
||||
*/
|
||||
PoolVariable(uint32_t set_id, DataSetIF* dataSet,
|
||||
ReadWriteMode_t setReadWriteMode) :
|
||||
|
|
|
@ -31,7 +31,7 @@ public:
|
|||
* \brief This attribute defines when a device handler object is executed.
|
||||
*
|
||||
* \details The pollingTime attribute identifies the time the handler is executed in ms. It must be
|
||||
* smaller than the period length of the polling sequence, what is ensured by automated calculation
|
||||
* smaller than the period length of the polling sequence, which is ensured by automated calculation
|
||||
* from a database.
|
||||
*/
|
||||
uint32_t pollingTimeMs;
|
||||
|
|
|
@ -104,7 +104,7 @@ protected:
|
|||
* \brief This list contains all OPUSPollingSlot objects, defining order and execution time of the
|
||||
* device handler objects.
|
||||
*
|
||||
* \details The slot list is a std:list object that contains all created OPUSPollingSlot instances.
|
||||
* @details The slot list is a std:list object that contains all created PollingSlot instances.
|
||||
* They are NOT ordered automatically, so by adding entries, the correct order needs to be ensured.
|
||||
* By iterating through this list the polling sequence is executed. Two entries with identical
|
||||
* polling times are executed immediately one after another.
|
||||
|
|
|
@ -27,8 +27,8 @@ public:
|
|||
/**
|
||||
* ctor
|
||||
*
|
||||
* @param owner
|
||||
* @param objectId the object Id to use when communication with the HealthTable
|
||||
* @param useAsFrom id to use as from id when sending replies, can be set to 0
|
||||
*/
|
||||
HealthHelper(HasHealthIF* owner, object_id_t objectId);
|
||||
|
||||
|
|
|
@ -3,12 +3,16 @@
|
|||
|
||||
// COULDDO: We could support blocking calls
|
||||
|
||||
/**
|
||||
* @defgroup message_queue Message Queue
|
||||
* @brief Message Queue related software components
|
||||
*/
|
||||
|
||||
#include <framework/ipc/MessageQueueMessage.h>
|
||||
#include <framework/ipc/MessageQueueSenderIF.h>
|
||||
#include <framework/returnvalues/HasReturnvaluesIF.h>
|
||||
class MessageQueueIF {
|
||||
public:
|
||||
|
||||
static const MessageQueueId_t NO_QUEUE = MessageQueueSenderIF::NO_QUEUE; //!< Ugly hack.
|
||||
|
||||
static const uint8_t INTERFACE_ID = CLASS_ID::MESSAGE_QUEUE_IF;
|
||||
|
@ -54,6 +58,8 @@ public:
|
|||
* lastPartner attribute. Else, the lastPartner information remains untouched, the
|
||||
* message's content is cleared and the function returns immediately.
|
||||
* @param message A pointer to a message in which the received data is stored.
|
||||
* @return -@c RETURN_OK on success
|
||||
* -@c MessageQueueIF::EMPTY if queue is empty
|
||||
*/
|
||||
virtual ReturnValue_t receiveMessage(MessageQueueMessage* message) = 0;
|
||||
/**
|
||||
|
@ -72,33 +78,38 @@ public:
|
|||
virtual MessageQueueId_t getId() const = 0;
|
||||
|
||||
/**
|
||||
* \brief With the sendMessage call, a queue message is sent to a receiving queue.
|
||||
* \details This method takes the message provided, adds the sentFrom information and passes
|
||||
* @brief With the sendMessage call, a queue message is sent to a receiving queue.
|
||||
* @details This method takes the message provided, adds the sentFrom information and passes
|
||||
* it on to the destination provided with an operating system call. The OS's return
|
||||
* value is returned.
|
||||
* \param sendTo This parameter specifies the message queue id to send the message to.
|
||||
* \param message This is a pointer to a previously created message, which is sent.
|
||||
* \param sentFrom The sentFrom information can be set to inject the sender's queue id into the message.
|
||||
* @param sendTo This parameter specifies the message queue id to send the message to.
|
||||
* @param message This is a pointer to a previously created message, which is sent.
|
||||
* @param sentFrom The sentFrom information can be set to inject the sender's queue id into the message.
|
||||
* This variable is set to zero by default.
|
||||
* \param ignoreFault If set to true, the internal software fault counter is not incremented if queue is full (if implemented).
|
||||
* @param ignoreFault If set to true, the internal software fault counter is not incremented if queue is full (if implemented).
|
||||
* @return -@c RETURN_OK on success
|
||||
* -@c MessageQueueIF::FULL if queue is full
|
||||
*/
|
||||
virtual ReturnValue_t sendMessageFrom( MessageQueueId_t sendTo, MessageQueueMessage* message, MessageQueueId_t sentFrom, bool ignoreFault = false ) = 0;
|
||||
|
||||
/**
|
||||
* @brief This operation sends a message to the given destination.
|
||||
* @details It directly uses the sendMessage call of the MessageQueueSender parent, but passes its
|
||||
* queue id as "sentFrom" parameter.
|
||||
* @param sendTo This parameter specifies the message queue id of the destination message queue.
|
||||
* @param message A pointer to a previously created message, which is sent.
|
||||
* @param ignoreFault If set to true, the internal software fault counter is not incremented if queue is full.
|
||||
*/
|
||||
* @brief This operation sends a message to the given destination.
|
||||
* @details It directly uses the sendMessage call of the MessageQueueSender parent, but passes its
|
||||
* queue id as "sentFrom" parameter.
|
||||
* @param sendTo This parameter specifies the message queue id of the destination message queue.
|
||||
* @param message A pointer to a previously created message, which is sent.
|
||||
* @param ignoreFault If set to true, the internal software fault counter is not incremented if queue is full.
|
||||
*/
|
||||
virtual ReturnValue_t sendMessage( MessageQueueId_t sendTo, MessageQueueMessage* message, bool ignoreFault = false ) = 0;
|
||||
|
||||
/**
|
||||
* \brief The sendToDefaultFrom method sends a queue message to the default destination.
|
||||
* \details In all other aspects, it works identical to the sendMessage method.
|
||||
* \param message This is a pointer to a previously created message, which is sent.
|
||||
* \param sentFrom The sentFrom information can be set to inject the sender's queue id into the message.
|
||||
* @brief The sendToDefaultFrom method sends a queue message to the default destination.
|
||||
* @details In all other aspects, it works identical to the sendMessage method.
|
||||
* @param message This is a pointer to a previously created message, which is sent.
|
||||
* @param sentFrom The sentFrom information can be set to inject the sender's queue id into the message.
|
||||
* This variable is set to zero by default.
|
||||
* @return -@c RETURN_OK on success
|
||||
* -@c MessageQueueIF::FULL if queue is full
|
||||
*/
|
||||
virtual ReturnValue_t sendToDefaultFrom( MessageQueueMessage* message, MessageQueueId_t sentFrom, bool ignoreFault = false ) = 0;
|
||||
/**
|
||||
|
@ -106,6 +117,8 @@ public:
|
|||
* @details As in the sendMessage method, this function uses the sendToDefault call of the
|
||||
* Implementation class and adds its queue id as "sentFrom" information.
|
||||
* @param message A pointer to a previously created message, which is sent.
|
||||
* @return -@c RETURN_OK on success
|
||||
* -@c MessageQueueIF::FULL if queue is full
|
||||
*/
|
||||
virtual ReturnValue_t sendToDefault( MessageQueueMessage* message ) = 0;
|
||||
/**
|
||||
|
|
|
@ -3,6 +3,13 @@
|
|||
|
||||
#include <framework/returnvalues/HasReturnvaluesIF.h>
|
||||
|
||||
/**
|
||||
* @brief Common interface for OS Mutex objects which provide MUTual EXclusion.
|
||||
*
|
||||
* @details https://en.wikipedia.org/wiki/Lock_(computer_science)
|
||||
* @ingroup osal
|
||||
* @ingroup interface
|
||||
*/
|
||||
class MutexIF {
|
||||
public:
|
||||
static const uint32_t NO_TIMEOUT; //!< Needs to be defined in implementation.
|
||||
|
|
|
@ -5,27 +5,55 @@
|
|||
#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.
|
||||
*
|
||||
* - Buffers with a size header inside that class can be declared with
|
||||
* @code
|
||||
* SerialFixedArrayListAdapter<BUFFER_TYPE,
|
||||
* MAX_SIZE, count_t> mySerialFixedArrayList(...).
|
||||
* @endcode
|
||||
*
|
||||
* - MAX_SIZE: specifies the maximum allowed number of elements
|
||||
* in FixedArrayList.
|
||||
* - BUFFER_TYPE: specifies the data type of the buffer
|
||||
* - count_t: specifies the type/size of the length field
|
||||
* which defaults to one byte.
|
||||
*
|
||||
* @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:
|
||||
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);
|
||||
}
|
||||
};
|
||||
|
||||
|
||||
|
||||
#endif /* SERIALFIXEDARRAYLISTADAPTER_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);
|
||||
|
|
|
@ -7,8 +7,60 @@
|
|||
#include <framework/serialize/SerializeIF.h>
|
||||
#include <string.h>
|
||||
|
||||
/**
|
||||
* \ingroup serialize
|
||||
/**
|
||||
* @brief These adapters 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
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* There are three ways to retrieve data out of a buffer to be used in the FSFW
|
||||
* to use regular aligned (big endian) data. Examples:
|
||||
*
|
||||
* 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, if necessary
|
||||
* @code
|
||||
* uint16_t data;
|
||||
* int32_t dataLen = sizeof(data);
|
||||
* ReturnValue_t result =
|
||||
* AutoSerializeAdapter::deSerialize(&data,&buffer,&dataLen,true);
|
||||
* @endcode
|
||||
*
|
||||
* 2. Perform a bitshift operation. Watch for for endianness:
|
||||
* @code
|
||||
* uint16_t data;
|
||||
* data = buffer[targetByte1] << 8 | buffer[targetByte2];
|
||||
* data = EndianSwapper::swap(data); //optional, or swap order above
|
||||
* @endcode
|
||||
*
|
||||
* 3. memcpy or std::copy can also be used, but watch out if system
|
||||
* endianness is different from required data endianness.
|
||||
* Perform endian-swapping if necessary.
|
||||
* @code
|
||||
* uint16_t data;
|
||||
* memcpy(&data,buffer + positionOfTargetByte1,sizeof(data));
|
||||
* data = EndianSwapper::swap(data); //optional
|
||||
* @endcode
|
||||
*
|
||||
* 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_ {
|
||||
|
|
|
@ -6,21 +6,34 @@
|
|||
#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:
|
||||
template<typename... Args>
|
||||
SerializeElement(Args... args) : LinkedElement<SerializeIF>(this), entry(std::forward<Args>(args)...) {
|
||||
SerializeElement(Args... args) : LinkedElement<SerializeIF>(this),
|
||||
entry(std::forward<Args>(args)...) {
|
||||
|
||||
}
|
||||
SerializeElement() : LinkedElement<SerializeIF>(this) {
|
||||
}
|
||||
|
||||
T entry;
|
||||
|
||||
ReturnValue_t serialize(uint8_t** buffer, uint32_t* size,
|
||||
const uint32_t max_size, bool bigEndian) const {
|
||||
return SerializeAdapter<T>::serialize(&entry, buffer, size, max_size, bigEndian);
|
||||
return SerializeAdapter<T>::serialize(&entry, buffer, size,
|
||||
max_size, bigEndian);
|
||||
}
|
||||
|
||||
uint32_t getSerializedSize() const {
|
||||
|
@ -29,8 +42,10 @@ public:
|
|||
|
||||
virtual ReturnValue_t deSerialize(const uint8_t** buffer, int32_t* size,
|
||||
bool bigEndian) {
|
||||
return SerializeAdapter<T>::deSerialize(&entry, buffer, size, bigEndian);
|
||||
return SerializeAdapter<T>::deSerialize(&entry, buffer,
|
||||
size, bigEndian);
|
||||
}
|
||||
|
||||
operator T() {
|
||||
return entry;
|
||||
}
|
||||
|
@ -39,6 +54,7 @@ public:
|
|||
entry = newValue;
|
||||
return *this;
|
||||
}
|
||||
|
||||
T *operator->() {
|
||||
return &entry;
|
||||
}
|
||||
|
|
|
@ -4,13 +4,31 @@
|
|||
#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 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
|
||||
* 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.
|
||||
*
|
||||
* @ingroup serialize
|
||||
*/
|
||||
class SerializeIF {
|
||||
public:
|
||||
|
|
Loading…
Reference in New Issue
Block a user