Additional documentation for DHB and CSB

This commit is contained in:
Robin Müller 2019-10-27 13:38:08 +01:00
parent 64f84d9d9f
commit d79f072851
2 changed files with 62 additions and 11 deletions

View File

@ -33,24 +33,29 @@ class StorageManagerIF;
* Contains all devices and the DeviceHandlerBase class. * Contains all devices and the DeviceHandlerBase class.
*/ */
// Robin: We're not really using RMAP, right? Maybe we should adapt class description for that?
/** /**
* \brief This is the abstract base class for device handlers. * \brief This is the abstract base class for device handlers.
* *
* Documentation: Dissertation Baetz p.138,139, p.141-149 * Documentation: Dissertation Baetz p.138,139, p.141-149
* SpaceWire Remote Memory Access Protocol (RMAP)
* *
* It features handling of @link DeviceHandlerIF::Mode_t Modes @endlink, the RMAP communication and the * It features handling of @link DeviceHandlerIF::Mode_t Modes @endlink, communication with
* communication with commanding objects. * physical devices, using the @link DeviceCommunicationIF, and communication with commanding objects.
*
* NOTE: RMAP is a legacy standard which is used for FLP.
* RMAP communication is not mandatory for projects implementing the FSFW.
* However, the communication principles are similar to RMAP as there are two write and two send calls involved.
*
* It inherits SystemObject and thus can be created by the ObjectManagerIF. * It inherits SystemObject and thus can be created by the ObjectManagerIF.
* *
* This class uses the opcode of ExecutableObjectIF to perform a step-wise execution. * This class uses the opcode of ExecutableObjectIF to perform a step-wise execution.
* For each step an RMAP action is selected and executed. If data has been received (eg in case of an RMAP Read), the data will be interpreted. * For each step an RMAP action is selected and executed. If data has been received (GET_READ), the data will be interpreted.
* The action for each step can be defined by the child class but as most device handlers share a 4-call (Read-getRead-write-getWrite) structure, * The action for each step can be defined by the child class but as most device handlers share a 4-call
* a default implementation is provided. * (sendRead-getRead-sendWrite-getWrite) structure, a default implementation is provided.
* *
* Device handler instances should extend this class and implement the abstract functions. * Device handler instances should extend this class and implement the abstract functions.
* Components and drivers can send so called cookies which are used for communication * Components and drivers can send so called cookies which are used for communication
* and contain information about the communcation (e.g. slave address for I2C or RMAP structs).
* *
* \ingroup devices * \ingroup devices
*/ */

View File

@ -180,20 +180,65 @@ protected:
*/ */
void sendTmPacket(uint8_t subservice, SerializeIF* content, void sendTmPacket(uint8_t subservice, SerializeIF* content,
SerializeIF* header = NULL); SerializeIF* header = NULL);
/**
* Check the target subservice
* @param subservice
* @return
*/
virtual ReturnValue_t isValidSubservice(uint8_t subservice) = 0; virtual ReturnValue_t isValidSubservice(uint8_t subservice) = 0;
/**
* Once a TC Request is valid, the existence of the destination and its target interface is checked and retrieved.
* The target message queue ID can then be acquired by using the target interface.
* @param subservice
* @param tcData Application Data of TC Packet
* @param tcDataLen
* @param id MessageQueue ID is stored here
* @param objectId
* @return - @c RETURN_OK on success
* - @c RETURN_FAILED
* - @c CSB or implementation specific return codes
*/
virtual ReturnValue_t getMessageQueueAndObject(uint8_t subservice,
const uint8_t *tcData, uint32_t tcDataLen, MessageQueueId_t *id,
object_id_t *objectId) = 0;
/**
* After the Message Queue and Object ID are determined,
* the command is prepared by using an implementation specific CommandMessage type which is sent to
* the target device. It contains all necessary information for the device to
* execute telecommands.
* @param message
* @param subservice
* @param tcData
* @param tcDataLen
* @param state
* @param objectId
* @return
*/
virtual ReturnValue_t prepareCommand(CommandMessage *message, virtual ReturnValue_t prepareCommand(CommandMessage *message,
uint8_t subservice, const uint8_t *tcData, uint32_t tcDataLen, uint8_t subservice, const uint8_t *tcData, uint32_t tcDataLen,
uint32_t *state, object_id_t objectId) = 0; uint32_t *state, object_id_t objectId) = 0;
/**
* This function is responsible for the communication between the Command Service Base
* and the respective PUS Commanding Service once the execution has started.
* The PUS Commanding Service receives replies from the target device and forwards them by calling this function.
* There are different translations of these replies to specify how the Command Service proceeds.
* @param reply Command Message which determines how CommandServiceBase proceeds
* @param previousCommand
* @param state
* @param optionalNextCommand
* @param objectId
* @param isStep Flag value to mark steps of command execution
* @return
*/
virtual ReturnValue_t handleReply(const CommandMessage *reply, virtual ReturnValue_t handleReply(const CommandMessage *reply,
Command_t previousCommand, uint32_t *state, Command_t previousCommand, uint32_t *state,
CommandMessage *optionalNextCommand, object_id_t objectId, CommandMessage *optionalNextCommand, object_id_t objectId,
bool *isStep) = 0; bool *isStep) = 0;
virtual ReturnValue_t getMessageQueueAndObject(uint8_t subservice,
const uint8_t *tcData, uint32_t tcDataLen, MessageQueueId_t *id,
object_id_t *objectId) = 0;
virtual void handleUnrequestedReply(CommandMessage *reply); virtual void handleUnrequestedReply(CommandMessage *reply);
@ -209,7 +254,8 @@ private:
* It handles replies generated by the devices and relayed by the specific service implementation. * It handles replies generated by the devices and relayed by the specific service implementation.
* This means that it determines further course of action depending on the return values specified * This means that it determines further course of action depending on the return values specified
* in the service implementation. * in the service implementation.
* This includes the generation of TC verification messages: * This includes the generation of TC verification messages. Note that
* the static framework object ID @c VerificationReporter::messageReceiver needs to be set.
* - TM[1,5] Step Successs * - TM[1,5] Step Successs
* - TM[1,6] Step Failure * - TM[1,6] Step Failure
* - TM[1,7] Completion Success * - TM[1,7] Completion Success