eive/fsfw
eive/fsfw
14
1
Fork 0
forked from fsfw/fsfw
Code Issues Pull Requests Releases 1 Wiki Activity

some doc unclarities comment added

Browse Source
This commit is contained in:
Robin Müller 2020-04-15 23:28:45 +02:00
parent 9284fe81da
commit fc08754b98
2 changed files with 105 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
devicehandlers/DeviceHandlerBase.cpp
View File

@ -16,10 +16,11 @@ object_id_t DeviceHandlerBase::powerSwitcherId = 0;
object_id_t DeviceHandlerBase::rawDataReceiverId = 0; object_id_t DeviceHandlerBase::rawDataReceiverId = 0;
object_id_t DeviceHandlerBase::defaultFDIRParentId = 0; object_id_t DeviceHandlerBase::defaultFDIRParentId = 0;
DeviceHandlerBase::DeviceHandlerBase(object_id_t setObjectId, object_id_t deviceCommunication, DeviceHandlerBase::DeviceHandlerBase(object_id_t setObjectId,
CookieIF * comCookie_, uint8_t setDeviceSwitch, object_id_t deviceCommunication, CookieIF * comCookie_,
uint32_t thermalStatePoolId, uint32_t thermalRequestPoolId, uint8_t setDeviceSwitch, uint32_t thermalStatePoolId,
FailureIsolationBase* fdirInstance, size_t cmdQueueSize) : uint32_t thermalRequestPoolId, FailureIsolationBase* fdirInstance,
size_t cmdQueueSize) :
SystemObject(setObjectId), mode(MODE_OFF), submode(SUBMODE_NONE), SystemObject(setObjectId), mode(MODE_OFF), submode(SUBMODE_NONE),
wiretappingMode(OFF), storedRawData(StorageManagerIF::INVALID_ADDRESS), wiretappingMode(OFF), storedRawData(StorageManagerIF::INVALID_ADDRESS),
deviceCommunicationId(deviceCommunication), comCookie(comCookie_), deviceCommunicationId(deviceCommunication), comCookie(comCookie_),
@ -37,7 +38,8 @@ DeviceHandlerBase::DeviceHandlerBase(object_id_t setObjectId, object_id_t device
insertInCommandMap(RAW_COMMAND_ID); insertInCommandMap(RAW_COMMAND_ID);
if (this->fdirInstance == nullptr) { if (this->fdirInstance == nullptr) {
this->fdirInstance = this->fdirInstance =
new DeviceHandlerFailureIsolation(setObjectId, defaultFDIRParentId); new DeviceHandlerFailureIsolation(setObjectId,
defaultFDIRParentId);
} }
} }

155
devicehandlers/DeviceHandlerBase.h
View File

@ -93,8 +93,10 @@ public:
* *
* @param setObjectId the ObjectId to pass to the SystemObject() Constructor * @param setObjectId the ObjectId to pass to the SystemObject() Constructor
* @param maxDeviceReplyLen the largest allowed reply size * @param maxDeviceReplyLen the largest allowed reply size
* @param setDeviceSwitch the switch the device is connected to, for devices using two switches, overwrite getSwitches() * @param setDeviceSwitch the switch the device is connected to,
* @param deviceCommuncation Communcation Interface object which is used to implement communication functions * for devices using two switches, overwrite getSwitches()
* @param deviceCommuncation Communcation Interface object which is
* used to implement communication functions
* @param thermalStatePoolId * @param thermalStatePoolId
* @param thermalRequestPoolId * @param thermalRequestPoolId
* @param fdirInstance * @param fdirInstance
@ -107,31 +109,35 @@ public:
FailureIsolationBase* fdirInstance = nullptr, size_t cmdQueueSize = 20); FailureIsolationBase* fdirInstance = nullptr, size_t cmdQueueSize = 20);
/** /**
* @brief This function is the device handler base core component and is called periodically. * @brief This function is the device handler base core component and is
* called periodically.
* @details * @details
* General sequence, showing where abstract virtual functions are called: * General sequence, showing where abstract virtual functions are called:
* If the State is SEND_WRITE: * If the State is SEND_WRITE:
* 1. Set the cookie state to COOKIE_UNUSED and read the command queue * 1. Set the cookie state to COOKIE_UNUSED and read the command queue
* 2. Handles Device State Modes by calling doStateMachine(). * 2. Handles Device State Modes by calling doStateMachine().
* This function calls callChildStatemachine() which calls the abstract functions * This function calls callChildStatemachine() which calls the
* doStartUp() and doShutDown() * abstract functions doStartUp() and doShutDown()
* 3. Check switch states by calling checkSwitchStates() * 3. Check switch states by calling checkSwitchStates()
* 4. Decrements counter for timeout of replies by calling decrementDeviceReplyMap() * 4. Decrements counter for timeout of replies by calling
* decrementDeviceReplyMap()
* 5. Performs FDIR check for failures * 5. Performs FDIR check for failures
* 6. Calls hkSwitcher.performOperation() * 6. Calls hkSwitcher.performOperation()
* 7. If the device mode is MODE_OFF, return RETURN_OK. Otherwise, perform the Action property * 7. If the device mode is MODE_OFF, return RETURN_OK.
* and performs depending on value specified * Otherwise, perform the Action property and performs depending
* by input value counter. The child class tells base class what to do by setting this value. * on value specified by input value counter (incremented in PST).
* - SEND_WRITE: Send data or commands to device by calling doSendWrite() which calls * The child class tells base class what to do by setting this value.
* sendMessage function of #communicationInterface * - SEND_WRITE: Send data or commands to device by calling
* doSendWrite() which calls sendMessage function
* of #communicationInterface
* and calls buildInternalCommand if the cookie state is COOKIE_UNUSED * and calls buildInternalCommand if the cookie state is COOKIE_UNUSED
* - GET_WRITE: Get ackknowledgement for sending by calling doGetWrite() which calls * - GET_WRITE: Get ackknowledgement for sending by calling doGetWrite()
* getSendSuccess of #communicationInterface. * which calls getSendSuccess of #communicationInterface.
* Calls abstract functions scanForReply() and interpretDeviceReply(). * Calls abstract functions scanForReply() and interpretDeviceReply().
* - SEND_READ: Request reading data from device by calling doSendRead() which calls * - SEND_READ: Request reading data from device by calling doSendRead()
* requestReceiveMessage of #communcationInterface * which calls requestReceiveMessage of #communcationInterface
* - GET_READ: Access requested reading data by calling doGetRead() which calls * - GET_READ: Access requested reading data by calling doGetRead()
* readReceivedMessage of #communicationInterface * which calls readReceivedMessage of #communicationInterface
* @param counter Specifies which Action to perform * @param counter Specifies which Action to perform
* @return RETURN_OK for successful execution * @return RETURN_OK for successful execution
*/ */
@ -153,37 +159,54 @@ public:
virtual ~DeviceHandlerBase(); virtual ~DeviceHandlerBase();
protected: protected:
/** /**
* This is used to let the child class handle the transition from mode @c _MODE_START_UP to @c MODE_ON * @brief This is used to let the child class handle the transition from
* * mode @c _MODE_START_UP to @c MODE_ON
* It is only called when the device handler is in mode @c _MODE_START_UP. That means, the device switch(es) are already set to on. * @details
* Device handler commands are read and can be handled by the child class. If the child class handles a command, it should also send * It is only called when the device handler is in mode @c _MODE_START_UP.
* That means, the device switch(es) are already set to on.
* Device handler commands are read and can be handled by the child class.
* If the child class handles a command, it should also send
* an reply accordingly. * an reply accordingly.
* If an Command is not handled (ie #DeviceHandlerCommand is not @c CMD_NONE, the base class handles rejecting the command and sends a reply. * If an Command is not handled (ie #DeviceHandlerCommand is not @c CMD_NONE,
* the base class handles rejecting the command and sends a reply.
* The replies for mode transitions are handled by the base class. * The replies for mode transitions are handled by the base class.
* *
* If the device is started and ready for operation, the mode should be set to MODE_ON. It is possible to set the mode to _MODE_TO_ON to * - If the device is started and ready for operation, the mode should be
* use the to on transition if available. * set to MODE_ON. It is possible to set the mode to _MODE_TO_ON to
* If the power-up fails, the mode should be set to _MODE_POWER_DOWN which will lead to the device being powered off. * use the to on transition if available.
* If the device does not change the mode, the mode will be changed to _MODE_POWER_DOWN, after the timeout (from getTransitionDelay()) has passed. * - If the power-up fails, the mode should be set to _MODE_POWER_DOWN
* which will lead to the device being powered off.
* - If the device does not change the mode, the mode will be changed
* to _MODE_POWER_DOWN, after the timeout (from getTransitionDelay())
* has passed.
* *
* #transitionFailure can be set to a failure code indicating the reason for a failed transition * #transitionFailure can be set to a failure code indicating the reason
* for a failed transition
*/ */
virtual void doStartUp() = 0; virtual void doStartUp() = 0;
/** /**
* This is used to let the child class handle the transition from mode @c _MODE_SHUT_DOWN to @c _MODE_POWER_DOWN * @brief This is used to let the child class handle the transition
* * from mode @c _MODE_SHUT_DOWN to @c _MODE_POWER_DOWN
* @details
* It is only called when the device handler is in mode @c _MODE_SHUT_DOWN. * It is only called when the device handler is in mode @c _MODE_SHUT_DOWN.
* Device handler commands are read and can be handled by the child class. If the child class handles a command, it should also send * Device handler commands are read and can be handled by the child class.
* an reply accordingly. * If the child class handles a command, it should also send an reply
* If an Command is not handled (ie #DeviceHandlerCommand is not @c CMD_NONE, the base class handles rejecting the command and sends a reply. * accordingly.
* The replies for mode transitions are handled by the base class. * If an Command is not handled (ie #DeviceHandlerCommand is not
* @c CMD_NONE, the base class handles rejecting the command and sends a
* reply. The replies for mode transitions are handled by the base class.
* *
* If the device ready to be switched off, the mode should be set to _MODE_POWER_DOWN. * - If the device ready to be switched off,
* If the device should not be switched off, the mode can be changed to _MODE_TO_ON (or MODE_ON if no transition is needed). * the mode should be set to _MODE_POWER_DOWN.
* If the device does not change the mode, the mode will be changed to _MODE_POWER_DOWN, when the timeout (from getTransitionDelay()) has passed. * - If the device should not be switched off, the mode can be changed to
* _MODE_TO_ON (or MODE_ON if no transition is needed).
* - If the device does not change the mode, the mode will be changed to
* _MODE_POWER_DOWN, when the timeout (from getTransitionDelay())
* has passed.
* *
* #transitionFailure can be set to a failure code indicating the reason for a failed transition * #transitionFailure can be set to a failure code indicating the reason
* for a failed transition
*/ */
virtual void doShutDown() = 0; virtual void doShutDown() = 0;
@ -249,27 +272,42 @@ protected:
* @details * @details
* This is used to let the base class know which replies are expected. * This is used to let the base class know which replies are expected.
* There are different scenarios regarding this: * There are different scenarios regarding this:
* - "Normal" commands. These are commands, that trigger a direct reply from the device.
* In this case, the id of the command should be added to the command map
* with a commandData_t where maxDelayCycles is set to the maximum expected
* number of PST cycles the reply will take. Then, scanForReply returns
* the id of the command and the base class can handle time-out and missing replies.
* - Periodic, unrequested replies. These are replies that, once enabled, are sent by the device
* on its own in a defined interval. In this case, the id of the reply
* or a placeholder id should be added to the deviceCommandMap with a commandData_t
* where maxDelayCycles is set to the maximum expected number of PST cycles between
* two replies (also a tolerance should be added, as an FDIR message will be generated if it is missed).
* As soon as the replies are enabled, DeviceCommandInfo.periodic must be set to 1,
* DeviceCommandInfo.delayCycles to DeviceCommandInfo.MaxDelayCycles.
* From then on, the base class handles the reception.
* Then, scanForReply returns the id of the reply or the placeholder id and the base class will
* take care of checking that all replies are received and the interval is correct.
* When the replies are disabled, DeviceCommandInfo.periodic must be set to 0,
* DeviceCommandInfo.delayCycles to 0;
* - Aperiodic, unrequested replies. These are replies that are sent
* by the device without any preceding command and not in a defined interval.
* These are not entered in the deviceCommandMap but handled by returning @c APERIODIC_REPLY in scanForReply().
* *
* - "Normal" commands. These are commands, that trigger a direct reply
* from the device. In this case, the id of the command should be added
* to the command map with a commandData_t where maxDelayCycles is set
* to the maximum expected number of PST cycles the reply will take.
* Then, scanForReply returns the id of the command and the base class
* can handle time-out and missing replies.
*
* - Periodic, unrequested replies. These are replies that, once enabled,
* are sent by the device on its own in a defined interval.
* In this case, the id of the reply or a placeholder id should be added
* to the deviceCommandMap with a commandData_t where maxDelayCycles is
* set to the maximum expected number of PST cycles between two replies
* (also a tolerance should be added, as an FDIR message will be
* generated if it is missed).
*
* (Robin) This part confuses me. "must do as soon as" implies that
* the developer must do something somewhere else in the code. Is
* that really the case? If I understood correctly, DHB performs
* almost everything (e.g. in erirm function) as long as the commands
* are inserted correctly.
*
* As soon as the replies are enabled, DeviceCommandInfo.periodic must
* be set to true, DeviceCommandInfo.delayCycles to
* DeviceCommandInfo.maxDelayCycles.
* From then on, the base class handles the reception.
* Then, scanForReply returns the id of the reply or the placeholder id
* and the base class will take care of checking that all replies are
* received and the interval is correct.
* When the replies are disabled, DeviceCommandInfo.periodic must be set
* to 0, DeviceCommandInfo.delayCycles to 0;
*
* - Aperiodic, unrequested replies. These are replies that are sent
* by the device without any preceding command and not in a defined
* interval. These are not entered in the deviceCommandMap but
* handled by returning @c APERIODIC_REPLY in scanForReply().
*/ */
virtual void fillCommandAndReplyMap() = 0; virtual void fillCommandAndReplyMap() = 0;
@ -530,6 +568,9 @@ protected:
uint16_t maxDelayCycles; //!< The maximum number of cycles the handler should wait for a reply to this command. uint16_t maxDelayCycles; //!< The maximum number of cycles the handler should wait for a reply to this command.
uint16_t delayCycles; //!< The currently remaining cycles the handler should wait for a reply, 0 means there is no reply expected uint16_t delayCycles; //!< The currently remaining cycles the handler should wait for a reply, 0 means there is no reply expected
size_t replyLen = 0; //!< Expected size of the reply. size_t replyLen = 0; //!< Expected size of the reply.
//(Robin): This is a flag, isnt it? could we declare it bool? uint8_t always
// gives away the impression that this variable is more than a simple flag
// and true/false are also more explicit.
uint8_t periodic; //!< if this is !=0, the delayCycles will not be reset to 0 but to maxDelayCycles uint8_t periodic; //!< if this is !=0, the delayCycles will not be reset to 0 but to maxDelayCycles
DeviceCommandMap::iterator command; //!< The command that expects this reply. DeviceCommandMap::iterator command; //!< The command that expects this reply.
}; };