FW Profile - C1 Implementation
FwSmSCreate.h File Reference

Declaration of the static creation interface for a FW State Machine. More...

Go to the source code of this file.

Macros

#define FW_SM_INST(SM_DESC, NS, NCPS, NTRANS, NA, NG)
 Instantiate a state machine descriptor and its internal data structure. More...
 
#define FW_SM_INST_NOCPS(SM_DESC, NS, NTRANS, NA, NG)
 Instantiate a state machine descriptor and its internal data structure. More...
 
#define FW_SM_INST_DER(SM_DESC, NS, NA, NG)
 Instantiate a descriptor for a derived state machine. More...
 

Functions

void FwSmInit (FwSmDesc_t smDesc)
 Initialize a state machine descriptor to represent an unconfigured state machine with no transitions, no actions, no guards and no embedded state machines. More...
 
void FwSmInitDer (FwSmDesc_t smDesc, FwSmDesc_t smDescBase)
 Initialize a state machine descriptor to extend another state machine (the base state machine). More...
 

Detailed Description

Declaration of the static creation interface for a FW State Machine.

A FW State Machine is described by a state machine descriptor. This interface allows a state machine descriptor to be created statically (i.e. without using dynamic memory allocation). In this sense, this interface is alternative to the dynamic creation interface defined in FwSmDCreate.h.

A state machine can be created in two ways:

  • It can be created from scratch, or
  • It can be created by extending an existing state machine.

In both cases, creation of a state machine descriptor is done in two steps:

  • The state machine descriptor and its internal data structures are instantiated.
  • The state machine descriptor and its internal data structures are initialized.

Instantiation is done by means of the following macros.

  • FW_SM_INST should be used to instantiate from scratch a descriptor for a state machine with one or more choice pseudo-states.
  • FW_SM_INST_NOCPS should be used to instantiate from scratch a descriptor for a state machine with no choice pseudo-states.
  • FW_SM_INST_DER should be used to instantiate a descriptor for a state machine which is derived by extending another state machine.

Initialization is done by means of the following functions:

  • FwSmInit should be used to initialize a descriptor which has been created from scratch with either FW_SM_INST or FW_SM_INST_NOCPS.
  • FwSmInitDer should be used to initialize a descriptor of a state machine which is derived by extending another state machine.

Function FwSmInitDer only initializes a descriptor in full if the base state machine (i.e. the state machine which is being extended) has no embedded state machines. If the base state machine has embedded state machines, additional initialization actions are required as described in the function documentation.

After a state machine descriptor has been instantiated and initialized, it will normally need to be configured. Configuration of a state machine descriptor can be done using the functions described in the FwSmConfig.h file.

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 FwSmSCreate.h.

Macro Definition Documentation

#define FW_SM_INST (   SM_DESC,
  NS,
  NCPS,
  NTRANS,
  NA,
  NG 
)
Value:
static SmPState_t SM_DESC##_pState[(NS)]; \
static SmCState_t SM_DESC##_cState[(NCPS)]; \
static SmTrans_t SM_DESC##_trans[(NTRANS)]; \
static FwSmAction_t SM_DESC##_actions[(NA) + 1]; \
static FwSmGuard_t SM_DESC##_guards[(NG) + 1]; \
static FwSmDesc_t SM_DESC##_esm[(NS)]; \
static SmBaseDesc_t SM_DESC##_base = {(SM_DESC##_pState), (SM_DESC##_cState), (SM_DESC##_trans), NS, NCPS, NTRANS}; \
static struct FwSmDesc(SM_DESC) = {&(SM_DESC##_base), \
(SM_DESC##_actions), \
(SM_DESC##_guards), \
(SM_DESC##_esm), \
(NA) + 1, \
(NG) + 1, \
1, \
0, \
0, \
0, \
NULL};
FwSmBool_t(* FwSmGuard_t)(FwSmDesc_t)
Type for a pointer to a state machine guard.
Definition: FwSmConstants.h:64
void(* FwSmAction_t)(FwSmDesc_t)
Type for a pointer to a state machine action.
Definition: FwSmConstants.h:46
Structure representing a transition.
Definition: FwSmPrivate.h:195
Structure representing a state machine descriptor.
Definition: FwSmPrivate.h:303
Structure representing the base descriptor of a state machine.
Definition: FwSmPrivate.h:235
Structure representing a choice pseudo state in a state machine.
Definition: FwSmPrivate.h:149
Structure representing a proper state in state machine.
Definition: FwSmPrivate.h:121
Return codes of a function which has completed execution without errors.
Definition: FwSmConstants.h:86

Instantiate a state machine descriptor and its internal data structure.

This macro compiles correctly only if the number of states NS, the number of choice pseudo-states NCPS and the number of transitions NTRANS is positive. If there is a need to define a state machine with zero choice pseudo-states, the FW_SM_INST_NOCPS macro should be used.

The macro generates code that does the following:

  • It defines an array of NS elements of type SmPState_t to represent the array holding the state machine states.
  • It defines an array of NS elements of to represent the array holding the state machines embedded in the NS states.
  • It defines an array of NCPS elements of type SmCState_t to represent the array holding the state machine choice pseudo-states.
  • It defines an array of NTRANS elements of type SmTrans_t to represent the array holding the state machine transitions.
  • It defines an array of (NA+1) elements of type SmAction_t to represent the array holding the state machine actions.
  • It defines an array of (NG+1) elements of type SmGuard_t to represent the array holding the state machine guards.
  • It defines and initializes a variable of type FwSmDescBase_t to represent the base part of the state machine descriptor.
  • It defines and initializes a variable with the name SM_DESC of type struct FwSmDesc to represent the state machine descriptor.

All variables defined by this macro are static.

The state machine descriptor instantiated by the macro is only partially initialized. Full initialization is performed using function FwSmInit.

Since the macro includes the declaration of several variables, it should be located in the section of a c-file where variable declaration is legal.

Parameters
SM_DESCthe variable holding the state machine descriptor
NSa positive integer representing the number of states
NCPSa positive integer the number of choice pseudo-states
NTRANSa positive integer representing the number of transitions
NAa non-negative integer representing the number of actions (i.e. the number of transition or state actions which are defined on the state machine)
NGa non-negative integer representing the number of guards (i.e. the number of transition actions which are defined on the state machine)

Definition at line 113 of file FwSmSCreate.h.

#define FW_SM_INST_DER (   SM_DESC,
  NS,
  NA,
  NG 
)
Value:
static FwSmAction_t SM_DESC##_actions[(NA) + 1]; \
static FwSmGuard_t SM_DESC##_guards[(NG) + 1]; \
static FwSmDesc_t SM_DESC##_esm[(NS)]; \
static struct FwSmDesc(SM_DESC) = \
{ \
NULL, (SM_DESC##_actions), (SM_DESC##_guards), (SM_DESC##_esm), (NA) + 1, (NG) + 1, 1, 0, 0, 0, smSuccess, \
NULL};
FwSmBool_t(* FwSmGuard_t)(FwSmDesc_t)
Type for a pointer to a state machine guard.
Definition: FwSmConstants.h:64
void(* FwSmAction_t)(FwSmDesc_t)
Type for a pointer to a state machine action.
Definition: FwSmConstants.h:46
Structure representing a state machine descriptor.
Definition: FwSmPrivate.h:303
Return codes of a function which has completed execution without errors.
Definition: FwSmConstants.h:86

Instantiate a descriptor for a derived state machine.

A derived state machine is a state machine which is created by extending another state machine. The state machine which is thus extended is called base state machine.

A state machine descriptor consists of two parts: the base descriptor and the extension descriptor (see FwSmPrivate.h). A derived state machine and its base state machine share the same base descriptor (which defines the topology of the state machine) but have different extension descriptors. This macro accordingly only instantiates a new extension descriptor. More precisely, this macro generates code that does the following:

  • It defines an array of (NA+1) elements of type SmAction_t to represent the array holding the state machine actions.
  • It defines an array of (NG+1) elements of type SmGuard_t to represent the array holding the state machine guards.
  • It defines and initializes a variable with the name SM_DESC of type struct FwSmDesc to represent the state machine descriptor.

All variables defined by this macro are static.

The state machine descriptor instantiated by the macro is only partially initialized. Full initialization is performed using function FwSmInitDer.

Since the macro includes the declaration of several variables, it should be located in the section of a c-file where variable declaration is legal.

Parameters
SM_DESCthe variable holding the state machine descriptor
NSa positive integer representing the number of states
NAa non-negative integer representing the number of actions (i.e. the number of transition or state actions which are defined on the state machine)
NGa non-negative integer representing the number of guards

Definition at line 231 of file FwSmSCreate.h.

#define FW_SM_INST_NOCPS (   SM_DESC,
  NS,
  NTRANS,
  NA,
  NG 
)
Value:
static SmPState_t SM_DESC##_pState[(NS)]; \
static SmTrans_t SM_DESC##_trans[(NTRANS)]; \
static FwSmAction_t SM_DESC##_actions[(NA) + 1]; \
static FwSmGuard_t SM_DESC##_guards[(NG) + 1]; \
static FwSmDesc_t SM_DESC##_esm[(NS)]; \
static SmBaseDesc_t SM_DESC##_base = {(SM_DESC##_pState), NULL, (SM_DESC##_trans), NS, 0, NTRANS}; \
static struct FwSmDesc(SM_DESC) = {&(SM_DESC##_base), \
(SM_DESC##_actions), \
(SM_DESC##_guards), \
(SM_DESC##_esm), \
(NA) + 1, \
(NG) + 1, \
1, \
0, \
0, \
0, \
NULL};
FwSmBool_t(* FwSmGuard_t)(FwSmDesc_t)
Type for a pointer to a state machine guard.
Definition: FwSmConstants.h:64
void(* FwSmAction_t)(FwSmDesc_t)
Type for a pointer to a state machine action.
Definition: FwSmConstants.h:46
Structure representing a transition.
Definition: FwSmPrivate.h:195
Structure representing a state machine descriptor.
Definition: FwSmPrivate.h:303
Structure representing the base descriptor of a state machine.
Definition: FwSmPrivate.h:235
Structure representing a proper state in state machine.
Definition: FwSmPrivate.h:121
Return codes of a function which has completed execution without errors.
Definition: FwSmConstants.h:86

Instantiate a state machine descriptor and its internal data structure.

This macro compiles correctly only if the number of states NS and the number of transitions NTRANS is positive. This macro instantiates a descriptor for a state machine without choice pseudo-states. If there is a need to define a state machine with one or more choice pseudo-states, the FW_SM_INST macro should be used.

The macro generates code that does the following:

  • It defines an array of NS elements of type SmPState_t to represent the array holding the state machine states.
  • It defines an array of NS elements of to represent the array holding the state machines embedded in the NS states.
  • It defines an array of NTRANS elements of type SmTrans_t to represent the array holding the state machine transitions.
  • It defines an array of (NA+1) elements of type SmAction_t to represent the array holding the state machine actions.
  • It defines an array of (NG+1) elements of type SmGuard_t to represent the array holding the state machine guards.
  • It defines and initializes a variable of type FwSmDescBase_t to represent the base part of the state machine descriptor.
  • It defines and initializes a variable with the name SM_DESC of type struct FwSmDesc to represent the state machine descriptor.

All variables defined by this macro are static.

The state machine descriptor instantiated by the macro is only partially initialized. Full initialization is performed using function FwSmInit.

Since the macro includes the declaration of several variables, it should be located in the section of a c-file where variable declaration is legal.

Parameters
SM_DESCthe variable holding the state machine descriptor
NSa positive integer representing the number of states
NTRANSa positive integer representing the number of transitions
NAa non-negative integer representing the number of actions (i.e. the number of transition or state actions which are defined on the state machine)
NGa non-negative integer representing the number of guards (i.e. the number of transition actions which are defined on the state machine)

Definition at line 176 of file FwSmSCreate.h.

Function Documentation

void FwSmInit ( FwSmDesc_t  smDesc)

Initialize a state machine descriptor to represent an unconfigured state machine with no transitions, no actions, no guards and no embedded state machines.

After this function has been executed, the argument state machine descriptor has the same content as a state machine descriptor which has been created by calling FwSmCreate.

This function is primarily intended to be used to initialize a state machine descriptor which has been statically instantiated with macro FW_SM_INST or FW_SM_INST_NOCPS.

If the function is called upon a state machine descriptor that had already been initialized, the previous initialization values are lost. In such a case, a memory leak is possible due to the potential loss of the pointers to the arrays where the state machines states, choice pseudo-states, transitions and embedded state machines are stored.

Parameters
smDescthe state machine descriptor to be initialized.

Definition at line 24 of file FwSmSCreate.c.

void FwSmInitDer ( FwSmDesc_t  smDesc,
FwSmDesc_t  smDescBase 
)

Initialize a state machine descriptor to extend another state machine (the base state machine).

This function checks that the descriptor to be initialized satisfies the following constraints:

  • it has the same number of actions as the base state machine, and
  • it has the same number of guards as the base state machine.

If either constraint is not satisfied, the function reports an error by setting the error code of the descriptor to be initialized and then returns. If the first constraint is not satisfied, the function sets the error code to smWrongNOfActions. If the second constraint is not satisfied, the function sets the error code to smWrongNOfGuards.

If both constraints are satisfied, this function initializes a descriptor as follows:

  • It links it to the descriptor of the base state machine.
  • It initializes its actions to be the same as the actions of the base state machine.
  • It initializes its guards to be the same as the guards of the base state machine.
  • It initializes its states to have no embedded state machines.
  • It initializes its error code to be the same as the error code of the base state machine.
  • It initializes its transCnt field to zero.
  • It sets its state to STOPPED.

Thus, if the base state machine has no embedded state machines, then this function initializes a descriptor to represent its derived state machine. In this case, the descriptor initialized by this function represents exactly the same state machine as the descriptor created by calling function FwSmCreateDer. If, instead, the base state machine has one or more embedded state machines, then, in order to achieve the same effect as the FwSmCreateDer function, the descriptor initialized by this function must be further configured as follows:

  • The state machines embedded in the base state machine are extended. The extension is done using, recursively, the FW_SM_INST_DER macro and the FwSmInitDer function. Let ESM(i) be the extension of the state machine embedded in the i-th state of the base state machine.
  • The ESM(i) state machine is embedded within the i-th state of the descriptor initialized by this function using the FwSmEmbed function.

This function is primarily intended to be used to initialize a state machine descriptor which has been statically instantiated with macro FW_SM_INST_DER. If the function is called upon a state machine descriptor that had already been initialized, the previous initialization values are lost. In such a case, a memory leak is possible due to the potential loss of the pointers to the arrays where the state machines states, choice pseudo-states, transitions and embedded state machines are stored.

Parameters
smDescthe state machine descriptor to be initialized.
smDescBasethe state machine descriptor of the base state machine.

Definition at line 54 of file FwSmSCreate.c.

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