doc improved

This commit is contained in:
Robin Müller 2020-09-02 23:36:54 +02:00
parent 631b2ca705
commit 6069c64048

View File

@ -39,9 +39,10 @@ class StorageManagerIF;
* Documentation: Dissertation Baetz p.138,139, p.141-149 * Documentation: Dissertation Baetz p.138,139, p.141-149
* *
* It features handling of @link DeviceHandlerIF::Mode_t Modes @endlink, * It features handling of @link DeviceHandlerIF::Mode_t Modes @endlink,
* communication with physical devices, using the @link DeviceCommunicationIF @endlink, * communication with physical devices, using the
* and communication with commanding objects. * @link DeviceCommunicationIF @endlink, and communication with commanding
* It inherits SystemObject and thus can be created by the ObjectManagerIF. * 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. * This class uses the opcode of ExecutableObjectIF to perform a step-wise execution.
* For each step an RMAP action is selected and executed. * For each step an RMAP action is selected and executed.
@ -49,7 +50,7 @@ class StorageManagerIF;
* The action for each step can be defined by the child class but as most * 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, * device handlers share a 4-call (sendRead-getRead-sendWrite-getWrite) structure,
* a default implementation is provided. * a default implementation is provided.
* NOTE: RMAP is a standard which is used for FLP. * NOTE: RMAP is a standard which is used for Flying Laptop.
* RMAP communication is not mandatory for projects implementing the FSFW. * RMAP communication is not mandatory for projects implementing the FSFW.
* However, the communication principles are similar to RMAP as there are * However, the communication principles are similar to RMAP as there are
* two write and two send calls involved. * two write and two send calls involved.
@ -70,9 +71,6 @@ class StorageManagerIF;
* *
* Other important virtual methods with a default implementation * Other important virtual methods with a default implementation
* are the getTransitionDelayMs() function and the getSwitches() function. * are the getTransitionDelayMs() function and the getSwitches() function.
* Please ensure that getSwitches() returns DeviceHandlerIF::NO_SWITCHES if
* power switches are not implemented yet. Otherwise, the device handler will
* not transition to MODE_ON, even if setMode(MODE_ON) is called.
* If a transition to MODE_ON is desired without commanding, override the * If a transition to MODE_ON is desired without commanding, override the
* intialize() function and call setMode(_MODE_START_UP) before calling * intialize() function and call setMode(_MODE_START_UP) before calling
* DeviceHandlerBase::initialize(). * DeviceHandlerBase::initialize().
@ -94,13 +92,10 @@ public:
* The constructor passes the objectId to the SystemObject(). * The constructor passes the objectId to the SystemObject().
* *
* @param setObjectId the ObjectId to pass to the SystemObject() Constructor * @param setObjectId the ObjectId to pass to the SystemObject() Constructor
* @param maxDeviceReplyLen the length the RMAP getRead call will be sent with
* @param setDeviceSwitch the switch the device is connected to,
* for devices using two switches, overwrite getSwitches()
* @param deviceCommuncation Communcation Interface object which is used * @param deviceCommuncation Communcation Interface object which is used
* to implement communication functions * to implement communication functions
* @param thermalStatePoolId * @param comCookie This object will be passed to the communication inter-
* @param thermalRequestPoolId * face and can contain user-defined information about the communication.
* @param fdirInstance * @param fdirInstance
* @param cmdQueueSize * @param cmdQueueSize
*/ */
@ -352,22 +347,10 @@ protected:
* set to the maximum expected number of PST cycles between two replies * set to the maximum expected number of PST cycles between two replies
* (also a tolerance should be added, as an FDIR message will be * (also a tolerance should be added, as an FDIR message will be
* generated if it is missed). * 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. * From then on, the base class handles the reception.
* Then, scanForReply returns the id of the reply or the placeholder id * 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 * and the base class will take care of checking that all replies are
* received and the interval is correct. * 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 * - Aperiodic, unrequested replies. These are replies that are sent
* by the device without any preceding command and not in a defined * by the device without any preceding command and not in a defined
@ -705,14 +688,18 @@ protected:
uint32_t deviceThermalRequestPoolId = PoolVariableIF::NO_PARAMETER; uint32_t deviceThermalRequestPoolId = PoolVariableIF::NO_PARAMETER;
/** /**
* Optional Error code * Optional Error code. Can be set in doStartUp(), doShutDown() and
* Can be set in doStartUp(), doShutDown() and doTransition() to signal cause for Transition failure. * doTransition() to signal cause for Transition failure.
*/ */
ReturnValue_t childTransitionFailure; ReturnValue_t childTransitionFailure;
uint32_t ignoreMissedRepliesCount = 0; //!< Counts if communication channel lost a reply, so some missed replys can be ignored. /** Counts if communication channel lost a reply, so some missed
* replys can be ignored. */
uint32_t ignoreMissedRepliesCount = 0;
FailureIsolationBase* fdirInstance; //!< Pointer to the used FDIR instance. If not provided by child, default class is instantiated. /** Pointer to the used FDIR instance. If not provided by child,
* default class is instantiated. */
FailureIsolationBase* fdirInstance;
HkSwitchHelper hkSwitcher; HkSwitchHelper hkSwitcher;
@ -1099,11 +1086,6 @@ private:
void buildRawDeviceCommand(CommandMessage* message); void buildRawDeviceCommand(CommandMessage* message);
void buildInternalCommand(void); void buildInternalCommand(void);
// /**
// * Send a reply with the current mode and submode.
// */
// void announceMode(void);
/** /**
* Decrement the counter for the timout of replies. * Decrement the counter for the timout of replies.
* *
@ -1130,10 +1112,14 @@ private:
/** /**
* Build and send a command to the device. * Build and send a command to the device.
* *
* This routine checks whether a raw or direct command has been received, checks the content of the received command and * This routine checks whether a raw or direct command has been received,
* calls buildCommandFromCommand() for direct commands or sets #rawpacket to the received raw packet. * checks the content of the received command and calls
* If no external command is received or the received command is invalid and the current mode is @c MODE_NORMAL or a transitional mode, * buildCommandFromCommand() for direct commands or sets #rawpacket
* it asks the child class to build a command (via getNormalDeviceCommand() or getTransitionalDeviceCommand() and buildCommand()) and * to the received raw packet.
* If no external command is received or the received command is invalid and
* the current mode is @c MODE_NORMAL or a transitional mode, it asks the
* child class to build a command (via getNormalDeviceCommand() or
* getTransitionalDeviceCommand() and buildCommand()) and
* sends the command via RMAP. * sends the command via RMAP.
*/ */
void doSendWrite(void); void doSendWrite(void);
@ -1196,7 +1182,8 @@ private:
* @param newChannel the object Id of the channel to switch to * @param newChannel the object Id of the channel to switch to
* @return * @return
* - @c RETURN_OK when cookie was changed * - @c RETURN_OK when cookie was changed
* - @c RETURN_FAILED when cookies could not be changed, eg because the newChannel is not enabled * - @c RETURN_FAILED when cookies could not be changed,
* e.g. because the newChannel is not enabled
* - @c returnvalues of RMAPChannelIF::isActive() * - @c returnvalues of RMAPChannelIF::isActive()
*/ */
ReturnValue_t switchCookieChannel(object_id_t newChannelId); ReturnValue_t switchCookieChannel(object_id_t newChannelId);