diff --git a/devicehandlers/Cookie.h b/devicehandlers/Cookie.h index 618c901f..ec22ec3a 100644 --- a/devicehandlers/Cookie.h +++ b/devicehandlers/Cookie.h @@ -2,7 +2,13 @@ #define COOKIE_H_ /** - * This datatype is used to identify different connection over a single interface (like RMAP or I2C) + * @brief This datatype is used to identify different connection over a single interface + * (like RMAP or I2C) + * @details + * To use this class, implement a communication specific child cookie. This cookie + * can be used in the device communication interface by performing + * a C++ dynamic cast. The cookie can be used to store all kinds of information + * about the communication between read and send calls. */ class Cookie{ public: diff --git a/devicehandlers/DeviceCommunicationIF.h b/devicehandlers/DeviceCommunicationIF.h index 99904510..9b0e0a3a 100644 --- a/devicehandlers/DeviceCommunicationIF.h +++ b/devicehandlers/DeviceCommunicationIF.h @@ -8,6 +8,11 @@ * @brief Communication interfaces for flight software objects */ +/** + * Physical address type + */ +typedef uint32_t address_t; + /** * @brief This is an interface to decouple device communication from * the device handler to allow reuse of these components. @@ -39,23 +44,36 @@ public: virtual ~DeviceCommunicationIF() {} - virtual ReturnValue_t open(Cookie **cookie, uint32_t address, + /** + * Open a connection. Define a communication specific cookie which can + * be used to store information about the communication. + * + * @param cookie [in/out] This data class stores information about the communication. + * @param address Logical device address + * @param maxReplyLen Maximum length of expected reply + * @return + */ + virtual ReturnValue_t open(Cookie **cookie, address_t address, uint32_t maxReplyLen) = 0; /** * Use an existing cookie to open a connection to a new DeviceCommunication. * The previous connection must not be closed. - * If the returnvalue is not RETURN_OK, the cookie is unchanged and - * can be used with the previous connection. * * @param cookie * @param address * @param maxReplyLen - * @return + * @return -@c RETURN_OK New communication set up successfully + * - Everything else: Cookie is unchanged and can be used with + * previous connection */ - virtual ReturnValue_t reOpen(Cookie *cookie, uint32_t address, + virtual ReturnValue_t reOpen(Cookie *cookie, address_t address, uint32_t maxReplyLen) = 0; + /** + * Closing call of connection. Don't forget to free memory of cookie. + * @param cookie + */ virtual void close(Cookie *cookie) = 0; /** @@ -65,16 +83,18 @@ public: * @param cookie * @param data * @param len - * @return @c RETURN_OK for successfull send - * Everything else triggers sending failed event with returnvalue as parameter 1 + * @return -@c RETURN_OK for successfull send + * -Everything else triggers sending failed event with + * returnvalue as parameter 1 */ - virtual ReturnValue_t sendMessage(Cookie *cookie,const uint8_t *data, + virtual ReturnValue_t sendMessage(Cookie *cookie, const uint8_t *data, uint32_t len) = 0; virtual ReturnValue_t getSendSuccess(Cookie *cookie) = 0; /** * Called by DHB in the SEND_WRITE doSendRead(). + * Instructs the Communication Interface to prepare * @param cookie * @return */ @@ -93,9 +113,9 @@ public: virtual ReturnValue_t readReceivedMessage(Cookie *cookie, uint8_t **buffer, uint32_t *size) = 0; - virtual ReturnValue_t setAddress(Cookie *cookie, uint32_t address) = 0; + virtual ReturnValue_t setAddress(Cookie *cookie, address_t address) = 0; - virtual uint32_t getAddress(Cookie *cookie) = 0; + virtual address_t getAddress(Cookie *cookie) = 0; /** * Can be used by DeviceHandlerBase getParameter() call to set DeviceComIF parameters @@ -112,7 +132,6 @@ public: * @return */ virtual uint32_t getParameter(Cookie *cookie) = 0; - }; #endif /* DEVICECOMMUNICATIONIF_H_ */ diff --git a/devicehandlers/DeviceHandlerBase.h b/devicehandlers/DeviceHandlerBase.h index 53eaa7dd..60e8888e 100644 --- a/devicehandlers/DeviceHandlerBase.h +++ b/devicehandlers/DeviceHandlerBase.h @@ -33,28 +33,25 @@ class StorageManagerIF; * Contains all devices and the DeviceHandlerBase class. */ -/** - * Physical address type - */ -typedef uint32_t address_t; - /** * @brief This is the abstract base class for device handlers. * @details * Documentation: Dissertation Baetz p.138,139, p.141-149 * - * It features handling of @link DeviceHandlerIF::Mode_t Modes @endlink, communication with - * physical devices, using the @link DeviceCommunicationIF @endlink, and communication with commanding objects. + * It features handling of @link DeviceHandlerIF::Mode_t Modes @endlink, + * communication with physical devices, using the @link DeviceCommunicationIF @endlink, + * and communication with commanding objects. * 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 (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. - * NOTE: RMAP is a standard which is used for FLP. + * 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. NOTE: RMAP is a 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. + * However, the communication principles are similar to RMAP as there are + * two write and two send calls involved. * * 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 @@ -495,7 +492,8 @@ protected: DeviceCommunicationIF *communicationInterface; /** - * Cookie used for communication + * Cookie used for communication. This is passed to the communication + * interface. */ Cookie *cookie; @@ -910,7 +908,7 @@ private: /** * State a cookie is in. * - * Used to keep track of the state of the RMAP communication. + * Used to keep track of the state of the communication. */ enum CookieState_t { COOKIE_UNUSED, //!< The Cookie is unused diff --git a/rmap/RmapDeviceCommunicationIF.h b/rmap/RmapDeviceCommunicationIF.h index 12ae67e4..45963d86 100644 --- a/rmap/RmapDeviceCommunicationIF.h +++ b/rmap/RmapDeviceCommunicationIF.h @@ -4,7 +4,8 @@ #include /** - * @brief This class is a implementation of a DeviceCommunicationIF for RMAP calls. It expects RMAPCookies or a derived class of RMAPCookies + * @brief This class is a implementation of a DeviceCommunicationIF for RMAP calls. + * It expects RMAPCookies or a derived class of RMAPCookies * * @details The open, close and reOpen calls are mission specific * The open call might return any child of RMAPCookies @@ -44,7 +45,8 @@ public: /** - * Closing call of connection and memory free of cookie. Mission dependent call + * Closing call of connection and free memory of cookie. + * Mission dependent call * @param cookie */ virtual void close(Cookie *cookie) = 0;