Additional documentation for DHB and CSB

devicehandlers/DeviceHandlerBase.h

@@ -33,24 +33,29 @@ class StorageManagerIF;
  * 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.
  *
  * 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
- * communication with commanding objects.
+ * It features handling of @link DeviceHandlerIF::Mode_t Modes @endlink, communication with
+ * 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.
  *
  * 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.
- * 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,
- * a default implementation is provided.
+ * 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
+ * (sendRead-getRead-sendWrite-getWrite) structure, a default implementation is provided.
  *
  * 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
+ * and contain information about the communcation (e.g. slave address for I2C or RMAP structs).
  *
  * \ingroup devices
  */

tmtcservices/CommandingServiceBase.h

@@ -180,20 +180,65 @@ protected:
 	 */
 	void sendTmPacket(uint8_t subservice, SerializeIF* content,
 			SerializeIF* header = NULL);
+
+	/**
+	 * Check the target subservice
+	 * @param subservice
+	 * @return
+	 */
 	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,
 			uint8_t subservice, const uint8_t *tcData, uint32_t tcDataLen,
 			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,
 			Command_t previousCommand, uint32_t *state,
 			CommandMessage *optionalNextCommand, object_id_t objectId,
 			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);
 
@@ -209,7 +254,8 @@ private:
 	 * 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
 	 * 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,6] Step Failure
 	 *   - TM[1,7] Completion Success