FW Profile - C1 Implementation
|
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... | |
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:
In both cases, creation of a state machine descriptor is done in two steps:
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.
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.
#define FW_SM_INST | ( | SM_DESC, | |
NS, | |||
NCPS, | |||
NTRANS, | |||
NA, | |||
NG | |||
) |
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:
SmPState_t
to represent the array holding the state machine states.SmCState_t
to represent the array holding the state machine choice pseudo-states.SmTrans_t
to represent the array holding the state machine transitions.SmAction_t
to represent the array holding the state machine actions.SmGuard_t
to represent the array holding the state machine guards.FwSmDescBase_t
to represent the base part of the state machine descriptor.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.
SM_DESC | the variable holding the state machine descriptor |
NS | a positive integer representing the number of states |
NCPS | a positive integer the number of choice pseudo-states |
NTRANS | a positive integer representing the number of transitions |
NA | a non-negative integer representing the number of actions (i.e. the number of transition or state actions which are defined on the state machine) |
NG | a 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 | |||
) |
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:
SmAction_t
to represent the array holding the state machine actions.SmGuard_t
to represent the array holding the state machine guards.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.
SM_DESC | the variable holding the state machine descriptor |
NS | a positive integer representing the number of states |
NA | a non-negative integer representing the number of actions (i.e. the number of transition or state actions which are defined on the state machine) |
NG | a 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 | |||
) |
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:
SmPState_t
to represent the array holding the state machine states.SmTrans_t
to represent the array holding the state machine transitions.SmAction_t
to represent the array holding the state machine actions.SmGuard_t
to represent the array holding the state machine guards.FwSmDescBase_t
to represent the base part of the state machine descriptor.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.
SM_DESC | the variable holding the state machine descriptor |
NS | a positive integer representing the number of states |
NTRANS | a positive integer representing the number of transitions |
NA | a non-negative integer representing the number of actions (i.e. the number of transition or state actions which are defined on the state machine) |
NG | a 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.
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.
smDesc | the 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:
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:
transCnt
field to zero.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:
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.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.
smDesc | the state machine descriptor to be initialized. |
smDescBase | the state machine descriptor of the base state machine. |
Definition at line 54 of file FwSmSCreate.c.