FW Profile - C1 Implementation
FwSmConfig.h File Reference

Declaration of the configuration interface for a FW State Machine. More...

Go to the source code of this file.

Functions

void FwSmSetData (FwSmDesc_t smDesc, void *smData)
 Set the pointer to the state machine data in the state machine descriptor. More...
 
void * FwSmGetData (FwSmDesc_t smDesc)
 Get the pointer to the state machine data in the state machine descriptor. More...
 
void FwSmAddState (FwSmDesc_t smDesc, FwSmCounterS1_t stateId, FwSmCounterS1_t nOfOutTrans, FwSmAction_t entryAction, FwSmAction_t exitAction, FwSmAction_t doAction, FwSmDesc_t esmDesc)
 Create a state with the given characteristics and add it to a state machine. More...
 
void FwSmAddChoicePseudoState (FwSmDesc_t smDesc, FwSmCounterS1_t choiceId, FwSmCounterS1_t nOfOutTrans)
 Create a choice pseudo-state with the given characteristics and add it to a state machine. More...
 
void FwSmAddTransIpsToSta (FwSmDesc_t smDesc, FwSmCounterS1_t destId, FwSmAction_t trAction)
 Create a transition from the initial pseudo-state to a proper state and add it to a state machine. More...
 
void FwSmAddTransIpsToCps (FwSmDesc_t smDesc, FwSmCounterS1_t destId, FwSmAction_t trAction)
 Create a transition from the initial pseudo-state to a choice pseudo-state and add it to a state machine. More...
 
void FwSmAddTransStaToSta (FwSmDesc_t smDesc, FwSmCounterU2_t transId, FwSmCounterS1_t srcId, FwSmCounterS1_t destId, FwSmAction_t trAction, FwSmGuard_t trGuard)
 Create a transition from a proper state to a proper state and add it to a state machine. More...
 
void FwSmAddTransStaToCps (FwSmDesc_t smDesc, FwSmCounterU2_t transId, FwSmCounterS1_t srcId, FwSmCounterS1_t destId, FwSmAction_t trAction, FwSmGuard_t trGuard)
 Create a transition from a proper state to a choice pseudo-state and add it to a state machine. More...
 
void FwSmAddTransCpsToSta (FwSmDesc_t smDesc, FwSmCounterS1_t srcId, FwSmCounterS1_t destId, FwSmAction_t trAction, FwSmGuard_t trGuard)
 Create a transition from a choice pseudo-state to a proper state and add it to a state machine. More...
 
void FwSmAddTransStaToFps (FwSmDesc_t smDesc, FwSmCounterU2_t transId, FwSmCounterS1_t srcId, FwSmAction_t trAction, FwSmGuard_t trGuard)
 Create a transition from a proper state to the final pseudo-state and add it to a state machine. More...
 
void FwSmAddTransCpsToFps (FwSmDesc_t smDesc, FwSmCounterS1_t srcId, FwSmAction_t trAction, FwSmGuard_t trGuard)
 Create a transition from a choice pseudo-state to the final pseudo-state and add it to a state machine. More...
 
FwSmErrCode_t FwSmCheck (FwSmDesc_t smDesc)
 Check the correctness and completeness of the configuration of a state machine descriptor. More...
 
FwSmErrCode_t FwSmCheckRec (FwSmDesc_t smDesc)
 Recursively check the configuration of a state machine and all its embedded state machines. More...
 
void FwSmOverrideAction (FwSmDesc_t smDesc, FwSmAction_t oldAction, FwSmAction_t newAction)
 Override an action (either a state action or a transition action) in a derived state machine. More...
 
void FwSmOverrideGuard (FwSmDesc_t smDesc, FwSmGuard_t oldGuard, FwSmGuard_t newGuard)
 Override a guard in a derived state machine. More...
 
void FwSmEmbed (FwSmDesc_t smDesc, FwSmCounterS1_t stateId, FwSmDesc_t esmDesc)
 Embed a state machine in a state of a derived state machine. More...
 

Detailed Description

Declaration of the configuration interface for a FW State Machine.

A FW State Machine is described by a state machine descriptor. The functions declared in this interface allow a state machine descriptor to be configured. During the configuration process, the states, the choice pseudo-states and the transitions of the state machine are defined.

There are two types of state machines: newly created state machines (i.e. state machines which are created from scratch using FwSmCreate or FW_SM_INST) and derived state machines (i.e. state machines which are created by extending another state machine through calls to FwSmCreateDer or FW_SM_INST_DER). The functions declared in this header file can be used to configure both types of state machines.

In the case of a newly created state machine, the mode of use of the functions in this header file is as follows:

  1. The states of the state machine are added to its descriptor with the FwSmAddState function.
  2. The choice pseudo-states of the state machine are added to its descriptor with the FwSmAddChoicePseudoState function.
  3. The transitions of the state machines are added to the state machine with the FwSmAddFlow* functions (there are several of these functions, one for each type of transition source and destination).
  4. The pointer to the state machine data in the state machine descriptor is set with the FwSmSetData function.
  5. The consistency and completeness of the state machine configuration may be verified with function FwSmCheck or FwSmCheckRec. Use of this function is optional.

The only constraint on the order in which the above functions are called is that a transition from a state or choice pseudo-state can only be defined after the source state or choice pseudo-state has been defined.

In the case of a derived state machine, the mode of use of the functions declared in this header file is as follows:

  1. An action (either a state or a transition action) can be overridden with the FwSmOverrideAction function.
  2. A guard can be overridden with the FwSmOverrideGuard function.
  3. A state machine can be embedded in the state of the derived state machine with the FwSmEmbed function.
  4. The consistency and completeness of the configuration of the derived state machine may be verified with function FwSmCheck or FwSmCheckRec. Use of this function is optional.

There are no constraints on the order in which the above functions are called.

Error handling is done as follows:

  • Errors are reported through error codes. The range of error codes is defined in header file FwSmConstant.h. The error code is stored in the state machine descriptor (see FwSmGetErrCode).
  • If an illegal input value could cause a corruption of the internal data structures of a state machine descriptor, a check is performed on the input parameter value and the function is aborted if this is found to be illegal.
  • When a function takes a state machine descriptor as an argument, no check is performed that the argument is non-NULL and valid (e.g. if a configuration function is called with a NULL value for the state machine descriptor argument, this error is not handled and the call will probably result in a segmentation fault).
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 FwSmConfig.h.

Function Documentation

void FwSmAddChoicePseudoState ( FwSmDesc_t  smDesc,
FwSmCounterS1_t  choiceId,
FwSmCounterS1_t  nOfOutTrans 
)

Create a choice pseudo-state with the given characteristics and add it to a state machine.

This function reports the following errors in the error code of the state machine descriptor:

Parameters
smDescthe descriptor of the state machine to which the choice pseudo-state is added.
choiceIdthe identifier of the choice pseudo-state to be added (an integer in the range [1,N] where N is the number of choice pseudo-states).
nOfOutTransthe number of outgoing transitions from the new state (a positive integer).

Definition at line 140 of file FwSmConfig.c.

void FwSmAddState ( FwSmDesc_t  smDesc,
FwSmCounterS1_t  stateId,
FwSmCounterS1_t  nOfOutTrans,
FwSmAction_t  entryAction,
FwSmAction_t  exitAction,
FwSmAction_t  doAction,
FwSmDesc_t  esmDesc 
)

Create a state with the given characteristics and add it to a state machine.

This function reports the following errors in the error code of the state machine descriptor:

Parameters
smDescthe state machine to which the state is added.
stateIdthe identifier of the state to be added (an integer in the range [1,N] where N is the number of states in the state machine).
nOfOutTransthe number of out-going transitions from the new state. This must be a non-negative integer. A negative value is illegal but will not be reported as an error by this function.
entryActionthe entry action for the new state (a function pointer) or NULL if no entry action is associated to this state.
doActionthe do action for the new state (a function pointer) or NULL if no do action is associated to this state.
exitActionthe exit action for the new state (a function pointer) or NULL if no exit action is associated to this state.
esmDescthe descriptor of the state machine embedded in the new state or NULL if no state machine is embedded in the new state.

Definition at line 92 of file FwSmConfig.c.

void FwSmAddTransCpsToFps ( FwSmDesc_t  smDesc,
FwSmCounterS1_t  srcId,
FwSmAction_t  trAction,
FwSmGuard_t  trGuard 
)

Create a transition from a choice pseudo-state to the final pseudo-state and add it to a state machine.

This function should only be performed after the source state of the transition has been added to the state state machine. Transitions from a choice pseudo-state have no trigger. This function reports the following errors in the error code of the state machine descriptor:

  • smIllTransSrc: the identifier of the source of this transition has an illegal value
  • smUndefinedTransSrc: the source of this transition has not yet been added to the state machine
  • smTooManyTrans: there is no space left in the transition array of the state machine descriptor for this transition
  • smTooManyGuards: there is no space left in the guard array of the state machine descriptor for the guard defined by this transition
  • smTooManyActions: there is no space left in the action array of the state machine for the transition action defined by this transition
Parameters
smDescthe descriptor of the state machine to which the transition is added.
srcIdthe identifier of the source state of the transition (an integer in the range [1,N] where N is the number of states).
trActionthe transition action (a function pointer) or NULL if no action is associated to this transition.
trGuardthe transition guard (a function pointer) or NULL if no guard is associated to this transition

Definition at line 215 of file FwSmConfig.c.

void FwSmAddTransCpsToSta ( FwSmDesc_t  smDesc,
FwSmCounterS1_t  srcId,
FwSmCounterS1_t  destId,
FwSmAction_t  trAction,
FwSmGuard_t  trGuard 
)

Create a transition from a choice pseudo-state to a proper state and add it to a state machine.

This function should only be performed after the source of the transition has been added to the state state machine. This function reports the following errors in the error code of the state machine descriptor:

  • smIllTransSrc: the identifier of the source of this transition has an illegal value
  • smUndefinedTransSrc: the source of this transition has not yet been added to the state machine
  • smTooManyTrans: there is no space left in the transition array of the state machine descriptor for this transition
  • smTooManyGuards: there is no space left in the guard array of the state machine descriptor for the guard defined by this transition
  • smTooManyActions: there is no space left in the action array of the state machine for the transition action defined by this transition
Parameters
smDescthe descriptor of the state machine to which the transition is added.
srcIdthe identifier of the source choice pseudo-state of the transition (an integer in the range [1,N] where N is the number of choice pseudo-states).
destIdthe identifier of the destination state of the transition (an integer in the range [1,N] where N is the number of states).
trActionthe transition action (a function pointer) or NULL if no action is associated to this transition.
trGuardthe transition guard (a function pointer) or NULL if no guard is associated to this transition.

Definition at line 203 of file FwSmConfig.c.

void FwSmAddTransIpsToCps ( FwSmDesc_t  smDesc,
FwSmCounterS1_t  destId,
FwSmAction_t  trAction 
)

Create a transition from the initial pseudo-state to a choice pseudo-state and add it to a state machine.

Transitions from the initial pseudo-state have no trigger and no guard. This function reports the following errors in the error code of the state machine descriptor:

  • smTooManyTrans: there is no space left in the transition array of the state machine descriptor for this transition
  • smTooManyActions: there is no space left in the action array of the state machine for the transition action defined by this transition
Parameters
smDescthe descriptor of the state machine to which the transition is added.
destIdthe identifier of the destination choice pseudo-state of the transition (an integer in the range [1,N] where N is the number of choice pseudo-states).
trActionthe transition action (a function pointer) or NULL if no action is associated to this transition.

Definition at line 186 of file FwSmConfig.c.

void FwSmAddTransIpsToSta ( FwSmDesc_t  smDesc,
FwSmCounterS1_t  destId,
FwSmAction_t  trAction 
)

Create a transition from the initial pseudo-state to a proper state and add it to a state machine.

Transitions from the initial pseudo-state have no trigger and no guard. This function reports the following errors in the error code of the state machine descriptor:

  • smTooManyTrans: there is no space left in the transition array of the state machine descriptor for this transition
  • smTooManyActions: there is no space left in the action array of the state machine for the transition action defined by this transition
Parameters
smDescthe descriptor of the state machine to which the transition is added.
destIdthe identifier of the destination state of the transition (an integer in the range [1,N] where N is the number of states).
trActionthe transition action (a function pointer) or NULL if no action is associated to this transition.

Definition at line 181 of file FwSmConfig.c.

void FwSmAddTransStaToCps ( FwSmDesc_t  smDesc,
FwSmCounterU2_t  transId,
FwSmCounterS1_t  srcId,
FwSmCounterS1_t  destId,
FwSmAction_t  trAction,
FwSmGuard_t  trGuard 
)

Create a transition from a proper state to a choice pseudo-state and add it to a state machine.

This function should only be performed after the source state of the transition has been added to the state state machine. This function reports the following errors in the error code of the state machine descriptor:

  • smIllTransSrc: the identifier of the source of this transition has an illegal value
  • smUndefinedTransSrc: the source of this transition has not yet been added to the state machine
  • smTooManyTrans: there is no space left in the transition array of the state machine descriptor for this transition
  • smTooManyGuards: there is no space left in the guard array of the state machine descriptor for the guard defined by this transition
  • smTooManyActions: there is no space left in the action array of the state machine for the transition action defined by this transition
Parameters
smDescthe descriptor of the state machine to which the transition is added.
transIdthe identifier of the trigger which is associated to the transition. This is a non-negative integer but the value of zero is reserved for the "Execute" transition (see FW_TR_EXECUTE).
srcIdthe identifier of the source state of the transition (an integer in the range [1,N] where N is the number of states)
destIdthe identifier of the destination choice pseudo-state of the transition (an integer in the range [1,M] where M is the number of choice pseudo-states)
trActionthe transition action (a function pointer) or NULL if no action is associated to this transition.
trGuardthe transition guard (a function pointer) or NULL if no guard is associated to this transition.

Definition at line 197 of file FwSmConfig.c.

void FwSmAddTransStaToFps ( FwSmDesc_t  smDesc,
FwSmCounterU2_t  transId,
FwSmCounterS1_t  srcId,
FwSmAction_t  trAction,
FwSmGuard_t  trGuard 
)

Create a transition from a proper state to the final pseudo-state and add it to a state machine.

This function should only be performed after the source state of the transition has been added to the state state machine. This function reports the following errors in the error code of the state machine descriptor:

  • smIllTransSrc: the identifier of the source of this transition has an illegal value
  • smUndefinedTransSrc: the source of this transition has not yet been added to the state machine
  • smTooManyTrans: there is no space left in the transition array of the state machine descriptor for this transition
  • smTooManyGuards: there is no space left in the guard array of the state machine descriptor for the guard defined by this transition
  • smTooManyActions: there is no space left in the action array of the state machine for the transition action defined by this transition
Parameters
smDescthe descriptor of the state machine to which the transition is added.
transIdthe identifier of the trigger which is associated to the transition. This is a non-negative integer but the value of zero is reserved for the "Execute" transition (see FW_TR_EXECUTE).
srcIdthe identifier of the source state of the transition (an integer in the range [1,N] where N is the number of states).
trActionthe transition action (a function pointer) or NULL if no action is associated to this transition.
trGuardthe transition guard (a function pointer) or NULL if no guard is associated to this transition.

Definition at line 209 of file FwSmConfig.c.

void FwSmAddTransStaToSta ( FwSmDesc_t  smDesc,
FwSmCounterU2_t  transId,
FwSmCounterS1_t  srcId,
FwSmCounterS1_t  destId,
FwSmAction_t  trAction,
FwSmGuard_t  trGuard 
)

Create a transition from a proper state to a proper state and add it to a state machine.

This function should only be performed after the source state of the transition has been added to the state state machine. This function reports the following errors in the error code of the state machine descriptor:

  • smIllTransSrc: the identifier of the source of this transition has an illegal value
  • smUndefinedTransSrc: the source of this transition has not yet been added to the state machine
  • smTooManyTrans: there is no space left in the transition array of the state machine descriptor for this transition
  • smTooManyGuards: there is no space left in the guard array of the state machine descriptor for the guard defined by this transition
  • smTooManyActions: there is no space left in the action array of the state machine for the transition action defined by this transition
Parameters
smDescthe descriptor of the state machine to which the transition is added.
transIdthe identifier of the trigger which is associated to the transition. This is an integer which is unique for the state machine and for all its embedded state machines. The zero identifier is reserved for the "Execute" transition.
srcIdthe identifier of the source state of the transition (an integer in the range [1,N] where N is the number of states).
destIdthe identifier of the destination state of the transition.
trActionthe transition action (a function pointer) or NULL if no action is associated to this transition.
trGuardthe transition guard (a function pointer) or NULL if no guard is associated to this transition.

Definition at line 191 of file FwSmConfig.c.

FwSmErrCode_t FwSmCheck ( FwSmDesc_t  smDesc)

Check the correctness and completeness of the configuration of a state machine descriptor.

This function may be called on a state machine descriptor after it has been created and configured. This function does not modify the configuration of the state machine. It checks the error conditions which may arise when an application configures a state machine using the configuration functions declared in this header file. More specifically, this function performs the following checks:

  1. Check that no configuration errors have occurred (i.e. check that the error code in the state machine descriptor is equal to: smSuccess).
  2. Check that all states have been defined.
  3. Check that all choice pseudo-states have been defined.
  4. Check that all transitions have been defined.
  5. Check that the destinations of the transitions out of a state represent legal entities.
  6. Check that the destinations of the transitions out of a choice pseudo-state represent legal entities.
  7. Check that the number of actions declared when the state machine was created is the same as the number of actions defined during the state machine configuration process.
  8. Check that the number of guards declared when the state machine was created is the same as the number of guards defined during the state machine configuration process.
  9. Check that all states are reachable (i.e. they are at the end of at least one transition).
  10. Check that all choice pseudo-states are reachable (i.e. they are at the end of at least one transition).

Note that there are configuration errors which are not covered by this function because they cannot occur if the state machine is configured using the functions declared in this header file. Examples of this kind of errors include:

  • Defining a guard on a transition out of the initial pseudo-state;
  • Defining a transition which has a choice pseudo-state as both source and destination of the transition.
Parameters
smDescthe descriptor of the state machine to be checked.
Returns
the outcome of the check. The outcome of the check is one of the following: This function returns when it encounters the first error. Hence, the function return value is determined by the first error encountered by the function.

Definition at line 350 of file FwSmConfig.c.

FwSmErrCode_t FwSmCheckRec ( FwSmDesc_t  smDesc)

Recursively check the configuration of a state machine and all its embedded state machines.

This function performs the same checks as FwSmCheck but the checks are also performed (recursively) on all the embedded state machines. The function returns the first error code it encounters while checking the outer state machine and its embedded state machine. Thus, the error reported by this function may have arisen either in the outer state machine or in one of its embedded state machines.

Parameters
smDescthe descriptor of the state machine to be checked.
Returns
the outcome of the check (this is the same as for FwSmCheck).

Definition at line 438 of file FwSmConfig.c.

void FwSmEmbed ( FwSmDesc_t  smDesc,
FwSmCounterS1_t  stateId,
FwSmDesc_t  esmDesc 
)

Embed a state machine in a state of a derived state machine.

By default a derived state machine has the same embedded state machines as the base state machine from which it was derived. This function allows a state machine to be embedded in one of the states of the derived state machine. A state machine can only be embedded in an "empty" state (i.e. a state which, in the base state machine, had no embedded state).

As an example consider the case of a base state machine B and suppose that state S1 in this state machine has not embedded state machine. If an application creates a derived state machine D from B (for instance, through function FwSmCreateDer), then, after creation, state S1 in the derived state machine has no embedded state machine. This function allows a state machine to be embedded in S1.

If an attempt is made to embed a state machine in a non-empty state, the function returns with an error but does not modify in any way the state machine descriptor.

The override mechanism is only available for derived state machines. If this function is called on a base state machine, an error is returned and the function returns without doing anything.

This function reports the following errors in the error code of the state machine descriptor:

Parameters
smDescthe descriptor of the derived state machine.
stateIdthe identifier of the state where the state machine is to be embedded.
esmDescthe descriptor of the state machine to be embedded.

Definition at line 494 of file FwSmConfig.c.

void* FwSmGetData ( FwSmDesc_t  smDesc)

Get the pointer to the state machine data in the state machine descriptor.

This function returns the pointer which was set with the FwSmSetData function. This function is normally used by the functions implementing a state machine action or guard to access the state machine data. See the description of the FwSmSetData function for more details.

Parameters
smDescthe descriptor of the state machine to which the data structure is attached.
Returns
the pointer to the state machine data or NULL if no state machine data were defined for the state machine.

Definition at line 87 of file FwSmConfig.c.

void FwSmOverrideAction ( FwSmDesc_t  smDesc,
FwSmAction_t  oldAction,
FwSmAction_t  newAction 
)

Override an action (either a state action or a transition action) in a derived state machine.

By default a derived state machine has the same actions as the base state machine from which it was derived. This function overrides one of the actions of the derived state machine.

As an example consider the case of a base state machine B and suppose that action a1 is used as entry action of state S1 and as exit action of state S2. If an application creates a derived state machine D from B (for instance, through function FwSmCreateDer), then, after creation, the entry action of state S1 and the exit action of state S2 in state machine D is still a1. This function can be used to change a1. Note that a single invocation of this function will change both the entry action of S1 and the exit action of S2.

A call to this function on a state machine D has no effect on the actions of the state machines which are embedded in the states of D.

If an attempt is made to override a non-existent action, an error is declared and the function returns without doing anything.

The override mechanism is only available for derived state machines. If this function is called on a state machine which was not derived by extending some other state machine, an error is declared.

This function reports the following errors in the error code of the state machine descriptor:

Parameters
smDescthe descriptor of the derived state machine.
oldActionthe action to be overridden
newActionthe new action which overrides the old action

Definition at line 456 of file FwSmConfig.c.

void FwSmOverrideGuard ( FwSmDesc_t  smDesc,
FwSmGuard_t  oldGuard,
FwSmGuard_t  newGuard 
)

Override a guard in a derived state machine.

By default a derived state machine has the same guards as the base state machine from which it was derived. This function overrides one of the guards of the derived state machine.

As an example consider the case of a base state machine B and suppose that the transitions from state S1 to state S2 and the transition from state S3 to state S4 both have the same guard g1. If an application creates a derived state machine D from B (for instance, through function FwSmCreateDer), then, after creation, the guard of the transition from S1 to S2 and from S3 to S4 is still g1. This function can be used to change g1. Note that a single invocation of this function will change the guard on both transitions.

A call to this function on a state machine D has no effect on the guards of the state machines which are embedded in the states of D.

If an attempt is made to override a non-existent guard, the function declares an error and returns.

The override mechanism is only available for derived state machines. If this function is called on a state machine which was not derived by extending some other state machine, an error is declared.

This function reports the following errors in the error code of the state machine descriptor:

Parameters
smDescthe descriptor of the derived state machine.
oldGuardthe guard to be overridden
newGuardthe new guard which overrides the old guard

Definition at line 475 of file FwSmConfig.c.

void FwSmSetData ( FwSmDesc_t  smDesc,
void *  smData 
)

Set the pointer to the state machine data in the state machine descriptor.

The state machine data are data which are manipulated by the state machine actions and guards. The state machine descriptor holds a pointer to the state machine data. This function allows this pointer to be defined. The exact type of the state machine data is defined by applications for each state machine. It is therefore unknown at the level of the FW State Machine Module. This function accordingly treats the pointer to the state machine data as a pointer to void. In most cases, the state machine data will take the form of a struct whose fields represents the inputs and outputs for the state machine actions and guards.

The functions which implement the actions and guards access the state machine data as follows:

  • The functions implementing the actions and guards of a state machine take the state machine descriptor as an argument (because they must conform to the prototype defined by FwSmAction_t and FwSmGuard_t).
  • The functions implementing the actions and guards of a state machine use the FwSmGetData function to retrieve the pointer to the state machine data.
  • The pointer returned by FwSmGetData is defined as a pointer to void and will normally have to be cast to its true type.
    Parameters
    smDescthe descriptor of the state machine to which the data structure is attached.
    smDatathe pointer to the state machine data. A value of NULL is legal (but note that the default value of the pointer to the state machine data when the state machine is created is NULL).

Definition at line 83 of file FwSmConfig.c.

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