FW Profile - C1 Implementation
FwSmCore.c File Reference

Implements the core functions of the FW State Machine Module. More...

Go to the source code of this file.

Functions

void SmDummyAction (FwSmDesc_t smDesc)
 Dummy action which returns without doing anything. More...
 
FwSmBool_t SmDummyGuard (FwSmDesc_t smDesc)
 Dummy guard which always returns true. More...
 
void FwSmStart (FwSmDesc_t smDesc)
 Start a state machine. More...
 
void FwSmStop (FwSmDesc_t smDesc)
 Stop a state machine. More...
 
void FwSmMakeTrans (FwSmDesc_t smDesc, FwSmCounterU2_t transId)
 Trigger a transition in a state machine. More...
 
void FwSmExecute (FwSmDesc_t smDesc)
 Convenience method to execute a state machine. More...
 
FwSmDesc_t FwSmGetEmbSmCur (FwSmDesc_t smDesc)
 Return the state machine embedded in the current state. More...
 
FwSmDesc_t FwSmGetEmbSm (FwSmDesc_t smDesc, FwSmCounterS1_t i)
 Return the state machine embedded in the i-th state of the argument state machine. More...
 
FwSmCounterS1_t FwSmGetCurState (FwSmDesc_t smDesc)
 Return the identifier of the current state in a state machine (or zero if the state machine is stopped). More...
 
FwSmCounterS1_t FwSmGetCurStateEmb (FwSmDesc_t smDesc)
 Return the identifier of the current state of the state machine embedded in the current state (the sub-state). More...
 
FwSmBool_t FwSmIsStarted (FwSmDesc_t smDesc)
 Check whether the state machine is started. More...
 
FwSmErrCode_t FwSmGetErrCode (FwSmDesc_t smDesc)
 Return the error code of the argument state machine. More...
 
FwSmCounterU3_t FwSmGetExecCnt (FwSmDesc_t smDesc)
 Return the State Machine Execution Counter. More...
 
FwSmCounterU3_t FwSmGetStateExecCnt (FwSmDesc_t smDesc)
 Return the State Execution Counter. More...
 

Detailed Description

Implements the core functions of the FW State Machine Module.

Author
Vaclav Cechticky vacla.nosp@m.v.ce.nosp@m.chtic.nosp@m.ky@p.nosp@m.np-so.nosp@m.ftwa.nosp@m.re.co.nosp@m.m
Alessandro Pasetti paset.nosp@m.ti@p.nosp@m.np-so.nosp@m.ftwa.nosp@m.re.co.nosp@m.m

This file is part of the FW Profile.

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

For information on alternative licensing, please contact P&P Software GmbH.

Definition in file FwSmCore.c.

Function Documentation

void FwSmExecute ( FwSmDesc_t  smDesc)

Convenience method to execute a state machine.

Executing a state machine is equivalent to sending it the "Execute" transition command with function FwSmMakeTrans. The identifier of the "Execute" transition command is stored in FW_TR_EXECUTE.

Parameters
smDescthe descriptor of the state machine which is executed.

Definition at line 142 of file FwSmCore.c.

FwSmCounterS1_t FwSmGetCurState ( FwSmDesc_t  smDesc)

Return the identifier of the current state in a state machine (or zero if the state machine is stopped).

Parameters
smDescthe descriptor of the state machine.
Returns
the identifier of the current state of the state machine (or zero if the state machine is stopped).

Definition at line 222 of file FwSmCore.c.

FwSmCounterS1_t FwSmGetCurStateEmb ( FwSmDesc_t  smDesc)

Return the identifier of the current state of the state machine embedded in the current state (the sub-state).

If the current state is S and if there is a state machine embedded in this state, then this function returns the current state of the embedded state machine. More precisely, this function implements the following logic:

  • If the outer state machine is stopped, then the function returns -1.
  • If the current state of the outer state machine has an embedded state machine, then this function returns the current state of the embedded state machine (or zero if the embedded state machine is stopped).
  • If the current state of the outer state machine has no embedded state machine, then this function returns -1.
Parameters
smDescthe descriptor of the state machine.
Returns
the identifier of the current state of the embedded state machine (or zero if the embedded state machine is stopped, or -1 if the current state has no embedded state machine).

Definition at line 227 of file FwSmCore.c.

FwSmDesc_t FwSmGetEmbSm ( FwSmDesc_t  smDesc,
FwSmCounterS1_t  i 
)

Return the state machine embedded in the i-th state of the argument state machine.

No check is made on the legality of the value of argument 'i'. If this does not correspond to an existing state in the argument state machine, the behaviour of this function is undefined.

Parameters
smDescthe descriptor of the state machine.
ithe identifier of the state whose embedded state machine is returned
Returns
the descriptor of the state machine embedded in the i-th state or NULL if there is no embedded state machine in the i-th state .

Definition at line 217 of file FwSmCore.c.

FwSmDesc_t FwSmGetEmbSmCur ( FwSmDesc_t  smDesc)

Return the state machine embedded in the current state.

Parameters
smDescthe descriptor of the state machine.
Returns
the descriptor of the state machine embedded in the current state or NULL if there is no embedded state machine.

Definition at line 208 of file FwSmCore.c.

FwSmErrCode_t FwSmGetErrCode ( FwSmDesc_t  smDesc)

Return the error code of the argument state machine.

The error code of a state machine holds either smSuccess if the state machine never encountered an error or else it holds the code of the last error encountered by the state machine. If the error code is different from smSuccess, the behaviour of the state machine is undefined.

Parameters
smDescthe descriptor of the state machine to be checked.
Returns
either smSuccess or the code of the last error encountered by the state machine.

Definition at line 248 of file FwSmCore.c.

FwSmCounterU3_t FwSmGetExecCnt ( FwSmDesc_t  smDesc)

Return the State Machine Execution Counter.

The State Machine Execution Counter holds the number of execution cycles since the state machine was started. Note that the State Machine Execution Counter is not reset when the state machine is stopped (it is only reset when it is started).

Parameters
smDescthe descriptor of the state machine.
Returns
the value of the State Machine Execution Counter.

Definition at line 253 of file FwSmCore.c.

FwSmCounterU3_t FwSmGetStateExecCnt ( FwSmDesc_t  smDesc)

Return the State Execution Counter.

The State Execution Counter holds the number of execution cycles since the current state was entered. Note that the State Execution Counter is not reset when the state machine is stopped (it is only reset when the state machine is started).

Parameters
smDescthe descriptor of the state machine.
Returns
the value of the Node Execution Counter.

Definition at line 258 of file FwSmCore.c.

FwSmBool_t FwSmIsStarted ( FwSmDesc_t  smDesc)

Check whether the state machine is started.

Parameters
smDescthe descriptor of the state machine.
Returns
1 if the state machine is STARTED or 0 if it is STOPPED.

Definition at line 240 of file FwSmCore.c.

void FwSmMakeTrans ( FwSmDesc_t  smDesc,
FwSmCounterU2_t  transId 
)

Trigger a transition in a state machine.

The semantics of this function is defined by the following activity diagram (this is taken from figure 4.3-2 in the "FW Profile Definition Document"):

SM_CmdProcessing.png

The logic to execute a transition is implemented by the following activity diagram (this is taken from figure 4.3-3 in the "FW Profile Definition Document"):

SM_TransitionExecution.png

This operation is recursive because a transition request is propagated to the embedded state machine of the source state. The maximum depth of recursion is the maximum depth of nesting of embedded state machines.

If there are two transitions out of the current state which are both activated by this operation, the transition that will actually be taken is the one which was added first to the state machine (i.e. transitions are evaluated in the order in which they were added to the state machine).

Similarly, if the transition goes through a choice pseudo-state (CPS) and if there are two transitions out of the CPS which have guards which evaluate to true, the transition to be taken is the one which was added first to the state machine.

The FW Profile stipulates that at least one of the transitions out of a CPS must have a guard evaluating to true. This constraint is not enforced by the State Machine Module. If the constraint is violated, the error code is set to smTransErr.

This operation sets the error code to smTransErr if either of the following non-nominal situations occurs:

  • the transition encounters a choice pseudo-state which has no out-going transitions with a true guard; or
  • the transition encounters a transition which has a choice pseudo-state as both source and destination of the same transition.

In both the above cases, the state machine may remain in an inconsistent state.

Parameters
smDescthe descriptor of the state machine where the transition is triggered.
transIdthe identifier of the transition trigger.

Definition at line 92 of file FwSmCore.c.

void FwSmStart ( FwSmDesc_t  smDesc)

Start a state machine.

The semantics of this operation is defined by the activity diagram on the left-hand side of the following figure (this is figure 4.3-1 in the "FW Profile Definition Document"):

SM_StartStop.png

This function executes a transition from the initial pseudo-state to some state. It can set the error code to smTransErr if either of the following non-nominal situations occurs while performing the transition:

  • the transition encounters a choice pseudo-state which has no out-going transitions with a true guard; or
  • the transition encounters a transition which has a choice pseudo-state as both source and destination of the same transition.
Parameters
smDescthe descriptor of the state machine to be started.

Definition at line 52 of file FwSmCore.c.

void FwSmStop ( FwSmDesc_t  smDesc)

Stop a state machine.

The semantics of this operation is defined by the activity diagram on the right-hand side of the following figure (this is figure 4.3-1 in the "FW Profile Definition Document"):

SM_StartStop.png
Parameters
smDescthe descriptor of the state machine to be started.

Definition at line 69 of file FwSmCore.c.

void SmDummyAction ( FwSmDesc_t  smDesc)

Dummy action which returns without doing anything.

This action is used where nothing is specified for a state machine action (i.e. a state entry action, or a state do-action, or a state exit action, or a transition action).

Parameters
smDescstate machine descriptor. This parameter is unused in this dummy action. The parameter is retained for compatibility with the FwSmAction_t type.

Definition at line 40 of file FwSmCore.c.

FwSmBool_t SmDummyGuard ( FwSmDesc_t  smDesc)

Dummy guard which always returns true.

This guard is used where no transition guard is specified.

Parameters
smDescstate machine descriptor. This parameter is unused in this dummy guard. The parameter is retained for compatibility with the FwSmGuard_t type.
Returns
always return 1 (to signify that the guard is true).

Definition at line 46 of file FwSmCore.c.

P&P Software GmbH, Copyright 2011, All Rights Reserved