7.2.1. How to Write State Machines

This section demonstrates how state machines are implemented within the foxBMS 2 project. A simple, but fully functional, real-world implementation of this can be found in the debug AFE driver (see Debug Default).

7.2.1.1. The Example

This example implements a simple state machine with the following states:

  • Uninitialized

  • Initialization

  • Running

  • Error

An error in this example is an unrecoverable error. This gives the state flow diagram in Fig. 7.1.

States and their transitions

Fig. 7.1 States and their transitions

The state Initialization consists of three substates, which are processed sequentially:

  • I0: The first initialization substate

  • I1: The second initialization substates

  • Iexit: The last initialization substate (e.g., for some cleanup)

The state Running consists of three substate which are run in an endless loop in the following order:

  • R0: The first running substate

  • R1: The second running substate

  • R2: The third running substate

In any of the states Initialization and Running and any of the substates errors can occur. If this is the case, the state machine transitions from the substate to the state Error. The full state machine graph is shown in Fig. 7.2.

States and substates and their transitions

Fig. 7.2 States and substates and their transitions

7.2.1.2. Implementing the State Machine

The following describes the idea behind the state machine pattern and how it is implemented for the described example.

This how to is written in a top-down approach, starting for an abstract state machine interface to more detailed implementations of subfunctions. This makes the global understanding simpler. But this also means, that functions are used and only explained at a later point in the text.

Note

In this example, the module prefix will be EG. Sometimes in this how to it will a appropriate to use a variable reference for the module prefix. In that case {MODULE_PREFIX} is used.

Note

In running text functions always use parentheses with no argument or three dots (...) to indicate that a function is referred to. Code examples of course always implement the full and correct function or function call. Below two simple examples are shown:

  • The function void noArguments() is referred to by noArguments().

  • The function uint8_t addTwoNumbers(uint8_t a, uint8_t b) is referred to by addTwoNumbers().

7.2.1.2.1. Basics

All states MUST be put into an enum describing the states. There are four states in the example (Uninitialized, Initialization, Running, Error) plus the boilerplate of the state machine (a dummy state called DUMMY and a state indicating that the state machine has never run called HAS_NEVER_RUN). The enum entries MUST use FSM_STATE as infix after the module prefix. Taking all these rules into account, the enum for the states used in this example looks like this:

Listing 7.22 Enumeration of the states
1 typedef enum {
2     EG_FSM_STATE_DUMMY,          /*!< dummy state - always the first state */
3     EG_FSM_STATE_HAS_NEVER_RUN,  /*!< never run state - always the second state */
4     EG_FSM_STATE_UNINITIALIZED,  /*!< uninitialized state */
5     EG_FSM_STATE_INITIALIZATION, /*!< initializing the state machine */
6     EG_FSM_STATE_RUNNING,        /*!< operational mode of the state machine */
7     EG_FSM_STATE_ERROR,          /*!< state for error processing  */
8 } EG_FSM_STATES_e;

A similar pattern applies to the substates. For the boilerplate, a dummy substate called Dummy (as in the state) and an additional substate called Entry have to be defined. The enum entries MUST use FSM_SUBSTATE as infix after the module prefix. Taking all these rules into account, the enum for the substates used in this example looks like this:

Listing 7.23 Enumeration of the substates
 1 typedef enum {
 2     EG_FSM_SUBSTATE_DUMMY,               /*!< dummy state - always the first substate */
 3     EG_FSM_SUBSTATE_ENTRY,               /*!< entry state - always the second substate */
 4     EG_FSM_SUBSTATE_INITIALIZATION_0,    /*!< first initialization substate */
 5     EG_FSM_SUBSTATE_INITIALIZATION_1,    /*!< second initialization substate */
 6     EG_FSM_SUBSTATE_INITIALIZATION_EXIT, /*!< last initialization substate */
 7     EG_FSM_SUBSTATE_RUNNING_0,           /*!< first running substate */
 8     EG_FSM_SUBSTATE_RUNNING_1,           /*!< second running substate */
 9     EG_FSM_SUBSTATE_RUNNING_2,           /*!< third running substate */
10 } EG_FSM_SUBSTATES_e;

A struct named {MODULE_PREFIX}_STATE_s contains the general state of the state machine, with variables like currentState and previousState. In this example this struct is named EG_STATE_s. This struct is typically extended by an additional struct that holds relevant information or data (EG_INFORMATION_s information). In a real application these are usually pointers to some database entries required (see Debug Default) or variables used within the module. In this example it is just a struct holding three values.

Listing 7.24 The state type
 1 typedef struct {
 2     uint16_t timer;                      /*!< timer of the state */
 3     uint8_t triggerEntry;                /*!< trigger entry of the state */
 4     EG_FSM_STATES_e nextState;           /*!< next state of the FSM */
 5     EG_FSM_STATES_e currentState;        /*!< current state of the FSM */
 6     EG_FSM_STATES_e previousState;       /*!< previous state of the FSM */
 7     EG_FSM_SUBSTATES_e nextSubstate;     /*!< next substate of the FSM */
 8     EG_FSM_SUBSTATES_e currentSubstate;  /*!< current substate of the FSM */
 9     EG_FSM_SUBSTATES_e previousSubstate; /*!< previous substate of the FSM */
10     EG_INFORMATION_s information;        /*!< Some information to be stored */
11 } EG_STATE_s;

With these lines of code, all types needed for the state machine are defined. The next step is the implementation of the state machine.

The first thing to do is to declare a variable for the state machine state

Listing 7.25 The state variable
1 extern EG_STATE_s eg_state;

and initialize it as shown in Listing 7.26. The members of the struct related to the state (previousState, currentState and nextState) MUST be initialized with EG_FSM_STATE_HAS_NEVER_RUN to indicate that the state machine has not run yet. The members of the struct related to the substate (previousSubstate, currentSubstate and nextSubstate) MUST be initialized with the dummy state EG_FSM_SUBSTATE_DUMMY. The information struct can be anything that is required by the application.

Listing 7.26 The state variable
 1 EG_STATE_s eg_state = {
 2     .timer             = 0,
 3     .triggerEntry      = 0,
 4     .nextState        = EG_FSM_STATE_HAS_NEVER_RUN,
 5     .currentState     = EG_FSM_STATE_HAS_NEVER_RUN,
 6     .previousState    = EG_FSM_STATE_HAS_NEVER_RUN,
 7     .nextSubstate     = EG_FSM_SUBSTATE_DUMMY,
 8     .currentSubstate  = EG_FSM_SUBSTATE_DUMMY,
 9     .previousSubstate = EG_FSM_SUBSTATE_DUMMY,
10     .information.r0   = 0,
11     .information.r1   = 0,
12     .information.r2   = 0,
13 };

A state machine always consists of a periodic trigger function. The trigger function gets the state variable introduced above (eg_state in this example) as parameter. The trigger function MUST use Trigger as function name infix. This example uses EG_Trigger(). If needed, the name can be extended (e.g., EG_TriggerAfe()).

Listing 7.27 The trigger function
1 extern EG_Trigger(EG_STATE_s *pEgState)

The trigger function is then called somewhere in the application with EG_Trigger(&eg_state);

The trigger function is always implemented as shown in Listing 7.28 where EG_RunStateMachine() is the actual state machine implementation. The base name of the function MUST be {MODULE_PREFIX}_RunStateMachine. The implementation of EG_CheckMultipleCalls() can be taken directly from the example code. The detailed explanation of this function is found later in the text in Section 7.2.1.3.1.

It is often necessary to wait a definite amount of time. This can be the case for example when the state machine waits for a measurement to be finished before continuing. Waiting is implemented via the variable timer which is a member of the state variable. It must be decremented one time every time the trigger function is called. Two cases can happen:

  • If it has the value zero, it stays at zero and the content of the state machine is processed further.

  • If it has a non-zero value, it is decremented and the trigger function exits without processing the state machine.

To wait a definite amount of time, the time variable must only be assigned a non-zero value. The time to wait will depend on the periodicity with which the state machine is processed via the trigger function. If timer is set to N and the trigger function is called with a period T, the wait time before the state machine is processed further will be N*T.

Listing 7.28 Implementation of the trigger function
 1 extern STD_RETURN_TYPE_e EG_Trigger(EG_STATE_s *pEgState) {
 2     FAS_ASSERT(pEgState != NULL_PTR);
 3     bool earlyExit                = false;
 4     STD_RETURN_TYPE_e returnValue = STD_OK;
 5
 6     /* Check re-entrance of function */
 7     if (EG_MULTIPLE_CALLS_YES == EG_CheckMultipleCalls(pEgState)) {
 8         returnValue = STD_NOT_OK;
 9         earlyExit   = true;
10     }
11
12     if (earlyExit == false) {
13         if (pEgState->timer > 0u) {
14             if ((--pEgState->timer) > 0u) {
15                 pEgState->triggerEntry--;
16                 returnValue = STD_OK;
17                 earlyExit   = true;
18             }
19         }
20     }
21
22     if (earlyExit == false) {
23         EG_RunStateMachine(pEgState);
24         pEgState->triggerEntry--;
25     }
26     return returnValue;
27 }

As stated above the actual state machine is processed by EG_RunStateMachine().

EG_RunStateMachine() must process all states, except for the dummy state (EG_FSM_STATE_DUMMY). A condensed version of the state machine runner function looks like this:

Listing 7.29 Condensed state machine runner function
 1 static STD_RETURN_TYPE_e EG_RunStateMachine(EG_STATE_s *pEgState) {
 2     STD_RETURN_TYPE_e ranStateMachine = STD_OK;
 3     EG_FSM_STATES_e nextState         = EG_FSM_STATE_DUMMY;
 4     switch (pEgState->currentState) {
 5         /********************************************** STATE: HAS NEVER RUN */
 6         case EG_FSM_STATE_HAS_NEVER_RUN:
 7             /* code goes here */
 8             break;
 9
10         /********************************************** STATE: UNINITIALIZED */
11         case EG_FSM_STATE_UNINITIALIZED:
12             /* code goes here */
13             break;
14
15         /********************************************* STATE: INITIALIZATION */
16         case EG_FSM_STATE_INITIALIZATION:
17             /* code goes here */
18             break;
19
20         /**************************************************** STATE: RUNNING */
21         case EG_FSM_STATE_RUNNING:
22             /* code goes here */
23             break;
24         /****************************************************** STATE: ERROR */
25         case EG_FSM_STATE_ERROR:
26             /* code goes here */
27             break;
28
29         /**************************************************** STATE: DEFAULT */
30         default:
31             /* all cases must be processed, trap if unknown state arrives */
32             FAS_ASSERT(FAS_TRAP);
33             break;
34     }
35
36     return ranStateMachine;
37 }

It can now be seen why the EG_FSM_STATE_DUMMY state must never be processed by the state machine: If a function irregularly sets the state to EG_FSM_STATE_DUMMY, the state machine will switch to the default case and the FAS_ASSERT() function will stop this undefined behavior.

7.2.1.2.2. Description of the Implementation of All Cases

At next the implementations of all cases are explained in detail.

7.2.1.2.2.1. EG_FSM_STATE_HAS_NEVER_RUN

If the state machine has never run, it needs to be transferred to a known state, the uninitialized state (EG_FSM_STATE_UNINITIALIZED).

Note

This section uses the function EG_SetState(). The detailed explanation of EG_SetState() is found later in the text in Section 7.2.1.3.2.

Listing 7.30 Transition from the first startup of the state machine
1 switch (pEgState->currentState) {
2     /********************************************** STATE: HAS NEVER RUN */
3     case EG_FSM_STATE_HAS_NEVER_RUN:
4         /* Nothing to do, just transfer */
5         EG_SetState(pEgState, EG_FSM_STATE_UNINITIALIZED, EG_FSM_SUBSTATE_ENTRY, EG_FSM_SHORT_TIME);
6         break;
7     /* ... */
8 }

7.2.1.2.2.2. EG_FSM_STATE_UNINITIALIZED

This is the first state that is present in the state machine example. In the example there is nothing to do in the state Uninitialized. For most applications this will also be the case. However, if needed an application can implement some behavior in this state before transferring to the state Initialization (EG_FSM_STATE_INITIALIZATION):

Listing 7.31 Transition from the first startup of the state machine
1 switch (pEgState->currentState) {
2     /* ... */
3     /********************************************** STATE: UNINITIALIZED */
4     case EG_FSM_STATE_UNINITIALIZED:
5         /* Nothing to do, just transfer */
6         EG_SetState(pEgState, EG_FSM_STATE_INITIALIZATION, EG_FSM_SUBSTATE_ENTRY, EG_FSM_SHORT_TIME);
7         break;
8     /* ... */
9 }

7.2.1.2.2.3. EG_FSM_STATE_INITIALIZATION

The example showed, that the state Initialization consists of three substates. Putting all code for all substates directly into the state Initialization would cause bad readability and bad maintainability. Therefore all details of what happens in the state are implemented in state processing functions. Description of the Implementation of State Processing Functions explains what state processing functions are and how they work. For now it is sufficient to know that state processing functions need to exist.

If an error occurs in any of the substates of the state Initialization the state machine needs to transition to the state Error. The transitions based on the states and substates would not be clearly visible in such an implementation. Therefore this logic is transferred into a state processing function EG_ProcessInitializationState(). State processing functions MUST use the naming pattern {MODULE_PREFIX}_Process{StateName}State where {StateName} is the state to be processed, e.g., for the state Initialization {StateName} needs to be replaced with Initialization.

The state processing function (in this example EG_ProcessInitializationState()) returns the state the state machine has to transition to.

Generally three cases can happen:

  • the state machine stays in the current state,

  • the state machine transitions to another state or

  • something went wrong and the state machine must process the error.

To reflect this, an if-else structure is used. The first if always processes the current case, i.e., staying in the current state. The final else always processes the case if something unforeseen went wrong and performs an assertion. Between the if and else all else if implement the state transitions to other states. For this example this translates into the following code:

Listing 7.32 The initialization state is processed by an own function
 1 switch (pEgState->currentState) {
 2     /* ... */
 3     /********************************************* STATE: INITIALIZATION */
 4     case EG_FSM_STATE_INITIALIZATION:
 5         nextState = EG_ProcessInitializationState(pEgState);
 6         if (nextState == EG_FSM_STATE_INITIALIZATION) {
 7             /* staying in state, processed by substate function */
 8         } else if (nextState == EG_FSM_STATE_ERROR) {
 9             EG_SetState(pEgState, EG_FSM_STATE_ERROR, EG_FSM_SUBSTATE_ENTRY, EG_FSM_SHORT_TIME);
10         } else if (nextState == EG_FSM_STATE_RUNNING) {
11             EG_SetState(pEgState, EG_FSM_STATE_RUNNING, EG_FSM_SUBSTATE_ENTRY, EG_FSM_SHORT_TIME);
12         } else {
13             FAS_ASSERT(FAS_TRAP); /* Something went wrong */
14         }
15         break;
16     /* ... */
17 }

7.2.1.2.2.4. EG_FSM_STATE_RUNNING

After a successful initialization the state machine transfers into the operational mode. As described above, the state machine stays in that state until an error occurs. This state is also processed by the state function EG_ProcessRunningState() as it has more than one option to transfer to (either staying in the state or going to an error state).

Listing 7.33 The running state is also processed by a own function
 1 switch (pEgState->currentState) {
 2     /* ... */
 3     /**************************************************** STATE: RUNNING */
 4     case EG_FSM_STATE_RUNNING:
 5         nextState = EG_ProcessRunningState(pEgState);
 6         if (nextState == EG_FSM_STATE_RUNNING) {
 7             /* staying in state, processed by state function */
 8         } else if (nextState == EG_FSM_STATE_ERROR) {
 9             EG_SetState(pEgState, EG_FSM_STATE_ERROR, EG_FSM_SUBSTATE_ENTRY, EG_FSM_SHORT_TIME);
10         } else {
11             FAS_ASSERT(FAS_TRAP); /* Something went wrong */
12         }
13         break;
14     /* ... */
15 }

7.2.1.2.2.5. EG_FSM_STATE_ERROR

This state processes the error case. Errors can be recoverable, but in this example, for the sake of simplicity, they are not.

Listing 7.34 The error state
1 switch (pEgState->currentState) {
2     /* ... */
3     /****************************************************** STATE: ERROR */
4     case EG_FSM_STATE_ERROR:
5         /* implement error processing here or trap */
6         break;
7     /* ... */
8 }

In many cases an error is recoverable. Such a situation is described in Extended Example With Recoverable Error

7.2.1.2.2.6. default

This case makes sure that all states are correctly processed and the dummy state (EG_FSM_STATE_DUMMY) is not used. If this is not the case then this function traps.

Listing 7.35 The default state
1 switch (pEgState->currentState) {
2     /* ... */
3     /**************************************************** STATE: DEFAULT */
4     default:
5         /* all cases must be processed, trap if unknown state arrives */
6         FAS_ASSERT(FAS_TRAP);
7         break;
8 }

7.2.1.2.2.7. EG_FSM_STATE_DUMMY

As already stated in default processing the EG_FSM_STATE_DUMMY state is not required. The following describes the purpose of this pseudo state. There are two reasons one additional state is needed.

The first reason is that EG_SetState() and EG_SetSubstate() need some state to set the nextState and nextSubstate members of the struct to some valid value after the nextState is transferred to currentState and currentSubstate member. This must be some value that is not a real state that the state machine could transfer to, but something to indicate that nextState and nextSubstate were cleared. EG_FSM_STATE_DUMMY is used for that purpose.

The second reason comes from the initialization of variables in C. All uninitialized struct variables are initialized with zero, therefore for this example also eg_state, which is the state variable of this state machine. This is guaranteed by the C99 standard. For details see ISO C99 Standard 6.7.8.21 (Language/Declarations/Initialization/21).

State variables store all states. These states are defined by an enum. This was described in Basics. The first entry in an unnumbered enum has the value zero. Not fully explicitly initializing the state variable would implicitly initialize it with zero.

Listing 7.36 No initialization of the state variable eg_state
1 EG_STATE_s eg_state;
2 /* equals to: EG_STATE_s eg_state = {0}; */

In order to prevent not thinking about the initialization of the state members, the first state is the second enum entry (in this example EG_FSM_STATE_HAS_NEVER_RUN). This equals integer value 1, not 0. This forces the developer to think about initialization and think how the state variable (here eg_state) needs to be initialized explicitly. In combination with the implementation pattern of the EG_RunStateMachine() the state machine only starts if the initialization is correctly done.

7.2.1.2.3. Description of the Implementation of State Processing Functions

Functions that process a specific state are referred to as state processing functions.

State processing functions MUST use the naming pattern {MODULE_PREFIX}_Process{StateName}State where StateName is the state to be processed, e.g., for the state Initialization StateName needs to be replaced with Initialization.

State processing functions always return the next state to transition to. A variable called nextState MUST be defined locally in such functions. This variable MUST always be initialized with the state this state processing function implements.

Generally the nextState variables definition follows the following pattern EG_FSM_STATES_e nextState = EG_FSM_STATE_{SOME_STATE} where {SOME_STATE} needs to be replaced with the state this function processes. For example, as the function EG_ProcessInitializationState() process the state Initialization the correct state to initialize nextState with is EG_FSM_STATE_INITIALIZATION. The example in Listing 7.37 shows this more detailed for EG_ProcessInitializationState():

Listing 7.37 Example of nextState initialization
1 static EG_FSM_STATES_e EG_ProcessInitializationState(EG_STATE_s *pEgState) {
2     EG_FSM_STATES_e nextState = EG_FSM_STATE_INITIALIZATION; /* default behavior: stay in state */
3     /* code */
4     return nextState;
5     }

At next the state processing functions EG_ProcessInitializationState() and EG_ProcessRunningState() are explained.

7.2.1.2.3.1. EG_ProcessInitializationState()

Note

This section uses the function EG_SetSubstate(). The detailed explanation of EG_SetSubstate() is found later in the text in Section 7.2.1.3.3.

The initialization state has three substates (I0, I1, Iexit) that are run sequentially. The Entry substate (from the enums boilerplate) just transfers the state machine in the first initialization substate I0. There is no error handling required and code reads as simple as follows:

Listing 7.38 Transferring from the Entry state in first initialization substate I0
 1 static EG_FSM_STATES_e EG_ProcessInitializationState(EG_STATE_s *pEgState) {
 2     EG_FSM_STATES_e nextState = EG_FSM_STATE_INITIALIZATION; /* default behavior: stay in state */
 3     switch (pEgState->currentSubstate) {
 4         case EG_FSM_SUBSTATE_ENTRY:
 5             /* Nothing to do, just transfer to next substate */
 6             EG_SetSubstate(pEgState, EG_FSM_SUBSTATE_INITIALIZATION_0, EG_FSM_SHORT_TIME);
 7             break;
 8         /* ... */
 9     }
10 }

In the first substate I0 some work needs to be done (hypothetically for this example). This work is implemented in a function EG_SomeInitializationFunction0() that returns either true (if successful) or false (if unsuccessful). If it was unsuccessful, the substate I0 failed and the state machine needs to transition to the state Error. If this substate was successful the Initialization state should precede with the second substate I1. The code below shows the implementation.

Listing 7.39 Transferring from the first initialization substate I0 to second initialization substate I1
 1 static EG_FSM_STATES_e EG_ProcessInitializationState(EG_STATE_s *pEgState) {
 2     EG_FSM_STATES_e nextState = EG_FSM_STATE_INITIALIZATION; /* default behavior: stay in state */
 3     switch (pEgState->currentSubstate) {
 4         /* ... */
 5         case EG_FSM_SUBSTATE_INITIALIZATION_0:
 6             if (EG_SomeInitializationFunction0() == true) {
 7                 EG_SetSubstate(pEgState, EG_FSM_SUBSTATE_INITIALIZATION_1, EG_FSM_SHORT_TIME);
 8             } else {
 9                 /* Something might go wrong, so transition to error state */
10                 nextState = EG_FSM_STATE_ERROR;
11             }
12             break;
13         /* ... */
14     }
15 }

Transferring from initialization substate I1 to initialization substate Iexit works similar, therefore this implementation is left out. At next the transition from the initialization substate Iexit into the next state, the first running substate R0, is shown. The function EG_SomeInitializationFunctionExit() behaves the same way EG_SomeInitializationFunction0() above does. This leads to the following implementation:

Listing 7.40 Transferring from the last initialization substate Iexit to first running substate R0
 1 static EG_FSM_STATES_e EG_ProcessInitializationState(EG_STATE_s *pEgState) {
 2     EG_FSM_STATES_e nextState = EG_FSM_STATE_INITIALIZATION; /* default behavior: stay in state */
 3     switch (pEgState->currentSubstate) {
 4         /* ... */
 5         case EG_FSM_SUBSTATE_INITIALIZATION_EXIT:
 6             if (EG_SomeInitializationFunctionExit() == true) {
 7                 /* Initialization was successful, so transition to running state */
 8                 nextState = EG_FSM_STATE_RUNNING;
 9             } else {
10                 /* Something might go wrong, so transition to error state */
11                 nextState = EG_FSM_STATE_ERROR;
12             }
13             break;
14         /* ... */
15
16     }
17 }

The default case is implemented to assert on illegal substates:

Listing 7.41 Assertion on illegal substate
1 static EG_FSM_STATES_e EG_ProcessInitializationState(EG_STATE_s *pEgState) {
2     EG_FSM_STATES_e nextState = EG_FSM_STATE_INITIALIZATION; /* default behavior: stay in state */
3     switch (pEgState->currentSubstate) {
4         /* ... */
5     default:                  /* LCOV_EXCL_LINE */
6         FAS_ASSERT(FAS_TRAP); /* LCOV_EXCL_LINE */
7         break;                /* LCOV_EXCL_LINE */
8     }
9 }

7.2.1.2.3.2. EG_ProcessRunningState()

The state Running consists of three substates that are looped in order ( R0, R1, R2, R0, R1, R2, R0, …) as long as no error occurs. If an error occurs in any Running state’s substates the next state is the state Error.

In all substates of the Running state, some work needs to be done (again, hypothetically for this example). This work is implemented in the functions EG_SomeRunningFunction0() for substate R0, EG_SomeRunningFunction1() for substate R1 and EG_SomeRunningFunction2() for substate R2 that return either true (if successful) or false (if unsuccessful). If it was unsuccessful, the respective next state is the state Error. If it was successful, the respective next substate will be run. The implementation is shown below:

Listing 7.42 The Running and its substates implemented in its state processing function
 1 static EG_FSM_STATES_e EG_ProcessRunningState(EG_STATE_s *pEgState) {
 2     EG_FSM_STATES_e nextState = EG_FSM_STATE_RUNNING; /* default behavior: stay in state */
 3     switch (pEgState->currentSubstate) {
 4         case EG_FSM_SUBSTATE_ENTRY:
 5             /* Nothing to do, just transfer to next substate */
 6             EG_SetSubstate(pEgState, EG_FSM_SUBSTATE_RUNNING_0, EG_FSM_SHORT_TIME);
 7             break;
 8
 9         case EG_FSM_SUBSTATE_RUNNING_0:
10             if (EG_SomeRunningFunction0() == true) {
11                 EG_SetSubstate(pEgState, EG_FSM_SUBSTATE_RUNNING_1, EG_FSM_SHORT_TIME);
12             } else {
13                 /* Something might go wrong, so transition to error state */
14                 nextState = EG_FSM_STATE_ERROR;
15             }
16             break;
17
18         case EG_FSM_SUBSTATE_RUNNING_1:
19             if (EG_SomeRunningFunction1() == true) {
20                 EG_SetSubstate(pEgState, EG_FSM_SUBSTATE_RUNNING_2, EG_FSM_SHORT_TIME);
21             } else {
22                 /* Something might go wrong, so transition to error state */
23                 nextState = EG_FSM_STATE_ERROR;
24             }
25             break;
26
27         case EG_FSM_SUBSTATE_RUNNING_2:
28             if (EG_SomeRunningFunction2() == true) {
29                 EG_SetSubstate(pEgState, EG_FSM_SUBSTATE_RUNNING_0, EG_FSM_SHORT_TIME);
30             } else {
31                 /* Something might go wrong, so transition to error state */
32                 nextState = EG_FSM_STATE_ERROR;
33             }
34             break;
35
36         default:                  /* LCOV_EXCL_LINE */
37             FAS_ASSERT(FAS_TRAP); /* LCOV_EXCL_LINE */
38             break;                /* LCOV_EXCL_LINE */
39     }
40     return nextState;
41 }

7.2.1.3. Generic Functions Used in the State Machine

The following functions (EG_CheckMultipleCalls, EG_SetState, EG_SetSubstate) are needed for all state machines.

7.2.1.3.1. EG_CheckMultipleCalls()

The state machine trigger function (here EG_Trigger) MUST only be called time or event triggered and MUST NOT be called multiple times (no reentrance).

EG_CheckMultipleCalls() checks based on triggerEntry if the function is called only one time. The triggerEntry variable must be incremented once in each call of this function. It must be decremented once in every call of the trigger function, no matter what the trigger function does (this means even if the timer has not elapsed).

7.2.1.3.2. EG_SetState()

This function sets the next state. The following steps are performed:

  • setting the idle time of a state and

  • setting the state and substate.

Function behavior:

If neither, the state or substate have changed, there is no action to be taken. If the state has changed, the state and the substate need to change. The state is set to the next state and the substate is set to the entry state for substates (EG_FSM_SUBSTATE_ENTRY). After that the nextState and nextSubstate of state and substate can be cleared (set to EG_FSM_STATE_DUMMY and EG_FSM_SUBSTATE_DUMMY respectively). If the state has not changed, and only the substate has, the next substate is set by EG_SetSubstate().

This implementation requires that every state has a defined entry for all states and all states need to implement that entry. This also ensures that no state transitions from e.g.,

  • State A and third substate into

  • State C and second substate

are made, but a strict chain needs to be followed:

  • State A and third substate into

  • State C and first substate (EG_FSM_SUBSTATE_ENTRY) into

  • State C and second substate.

What if there is no substate in a case?: There might be states that do not need substates. Even this example has three states with no substates ( EG_FSM_STATE_HAS_NEVER_RUN, EG_FSM_STATE_UNINITIALIZED and EG_FSM_STATE_ERROR). In this case just the transition(s) in the next state(s) need to be implemented and no state processing function needs to be implemented. Therefore setting the substate implicitly by using the EG_SetState is fine, as the substate is ignored in that case and it is correctly set to entry (EG_FSM_SUBSTATE_ENTRY) for the next case, whether this state implements substates or not.

7.2.1.3.3. EG_SetSubstate()

This function only sets the substate.

When currentSubstate is set to the next substate, the nextSubstate can be cleared. This is done by setting it to the dummy substate (EG_FSM_SUBSTATE_DUMMY).

7.2.1.4. Extended Example With Recoverable Error

There are cases where an error during the processing of the state machine can occur and there are strategies to recover from them. The example from Fig. 7.1 is extended as follows:

Example with recoverable error

Fig. 7.3 Example with recoverable error

To implement this behavior, the error case needs to be changed to something like shown in Listing 7.43. There is a state function EG_ProcessErrorState() to process the error case and there might be an option to re-initialize the state machine based on the type of error.

Listing 7.43 The error state
 1 switch (pEgState->currentState) {
 2     /* ... */
 3     /****************************************************** STATE: ERROR */
 4     case EG_FSM_STATE_ERROR:
 5         nextState = EG_ProcessErrorState(pEgState);
 6         if (nextState == EG_FSM_STATE_ERROR) {
 7             /* staying in error state, processed by state function */
 8         } else if (nextState == EG_FSM_STATE_UNINITIALIZED) {
 9             EG_SetState(pEgState, EG_FSM_STATE_UNINITIALIZED, EG_FSM_SUBSTATE_ENTRY, EG_FSM_SHORT_TIME);
10         } else {
11             FAS_ASSERT(FAS_TRAP); /* Something went wrong */
12         }
13         break;
14     /* ... */
15 }

7.2.1.5. Full Example Code

The full implementation of this state machine is found in Listing 7.44 and Listing 7.45.

Listing 7.44 The header of the state machine
  1/**
  2 *
  3 * @copyright &copy; 2010 - 2026, Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V.
  4 * All rights reserved.
  5 *
  6 * SPDX-License-Identifier: BSD-3-Clause
  7 *
  8 * Redistribution and use in source and binary forms, with or without
  9 * modification, are permitted provided that the following conditions are met:
 10 *
 11 * 1. Redistributions of source code must retain the above copyright notice, this
 12 *    list of conditions and the following disclaimer.
 13 *
 14 * 2. Redistributions in binary form must reproduce the above copyright notice,
 15 *    this list of conditions and the following disclaimer in the documentation
 16 *    and/or other materials provided with the distribution.
 17 *
 18 * 3. Neither the name of the copyright holder nor the names of its
 19 *    contributors may be used to endorse or promote products derived from
 20 *    this software without specific prior written permission.
 21 *
 22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 23 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 24 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 25 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
 26 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 27 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 28 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 29 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 30 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 32 *
 33 * We kindly request you to use one or more of the following phrases to refer to
 34 * foxBMS in your hardware, software, documentation or advertising materials:
 35 *
 36 * - "This product uses parts of foxBMS&reg;"
 37 * - "This product includes parts of foxBMS&reg;"
 38 * - "This product is derived from foxBMS&reg;"
 39 *
 40 */
 41
 42/**
 43 * @file    state-machine.h
 44 * @author  foxBMS Team
 45 * @date    2020-10-29 (date of creation)
 46 * @updated 2026-10-06 (date of last update)
 47 * @version v1.12.0
 48 * @ingroup STATE_MACHINE
 49 * @prefix  EG
 50 *
 51 * @brief   Header file of some software
 52 * @details This header declares the data types and public interface of the
 53 *          example state machine used in the style-guide documentation.
 54 *          It shows how states, substates, and the state container can be
 55 *          structured for a module that advances through a trigger function.
 56 */
 57
 58#ifndef FOXBMS__STATE_MACHINE_H_
 59#define FOXBMS__STATE_MACHINE_H_
 60
 61/*========== Includes =======================================================*/
 62#include "fstd_types.h"
 63
 64#include <stdint.h>
 65
 66/*========== Macros and Definitions =========================================*/
 67/** States of the state machine */
 68typedef enum {
 69    EG_FSM_STATE_DUMMY,          /*!< dummy state - always the first state */
 70    EG_FSM_STATE_HAS_NEVER_RUN,  /*!< never run state - always the second state */
 71    EG_FSM_STATE_UNINITIALIZED,  /*!< uninitialized state */
 72    EG_FSM_STATE_INITIALIZATION, /*!< initializing the state machine */
 73    EG_FSM_STATE_RUNNING,        /*!< operational mode of the state machine */
 74    EG_FSM_STATE_ERROR,          /*!< state for error processing  */
 75} EG_FSM_STATES_e;
 76
 77/** Substates of the state machine */
 78typedef enum {
 79    EG_FSM_SUBSTATE_DUMMY,               /*!< dummy state - always the first substate */
 80    EG_FSM_SUBSTATE_ENTRY,               /*!< entry state - always the second substate */
 81    EG_FSM_SUBSTATE_INITIALIZATION_0,    /*!< first initialization substate */
 82    EG_FSM_SUBSTATE_INITIALIZATION_1,    /*!< second initialization substate */
 83    EG_FSM_SUBSTATE_INITIALIZATION_EXIT, /*!< last initialization substate */
 84    EG_FSM_SUBSTATE_RUNNING_0,           /*!< first running substate */
 85    EG_FSM_SUBSTATE_RUNNING_1,           /*!< second running substate */
 86    EG_FSM_SUBSTATE_RUNNING_2,           /*!< third running substate */
 87} EG_FSM_SUBSTATES_e;
 88
 89/** some struct with some information */
 90typedef struct {
 91    uint8_t r0; /*!< some info 0 */
 92    uint8_t r1; /*!< some info 1 */
 93    uint8_t r2; /*!< some info 2 */
 94} EG_INFORMATION_s;
 95
 96/** This struct describes the state of the monitoring instance */
 97typedef struct {
 98    uint16_t timer;                      /*!< timer of the state */
 99    uint8_t triggerEntry;                /*!< trigger entry of the state */
100    EG_FSM_STATES_e nextState;           /*!< next state of the FSM */
101    EG_FSM_STATES_e currentState;        /*!< current state of the FSM */
102    EG_FSM_STATES_e previousState;       /*!< previous state of the FSM */
103    EG_FSM_SUBSTATES_e nextSubstate;     /*!< next substate of the FSM */
104    EG_FSM_SUBSTATES_e currentSubstate;  /*!< current substate of the FSM */
105    EG_FSM_SUBSTATES_e previousSubstate; /*!< previous substate of the FSM */
106    EG_INFORMATION_s information;        /*!< Some information to be stored */
107} EG_STATE_s;
108
109/*========== Extern Constant and Variable Declarations ======================*/
110
111/** state of the example state machine */
112extern EG_STATE_s eg_state;
113
114/*========== Extern Function Prototypes =====================================*/
115/**
116 * @brief   tick function, call this to advance the state machine
117 * @param   pEgState current state of the state machine
118 * @return  returns always #STD_OK
119 */
120extern STD_RETURN_TYPE_e EG_Trigger(EG_STATE_s *pEgState);
121
122/*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
123#ifdef UNITY_UNIT_TEST
124#endif
125
126#endif /* FOXBMS__STATE_MACHINE_H_ */
Listing 7.45 The implementation of the state machine
  1/**
  2 *
  3 * @copyright &copy; 2010 - 2026, Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V.
  4 * All rights reserved.
  5 *
  6 * SPDX-License-Identifier: BSD-3-Clause
  7 *
  8 * Redistribution and use in source and binary forms, with or without
  9 * modification, are permitted provided that the following conditions are met:
 10 *
 11 * 1. Redistributions of source code must retain the above copyright notice, this
 12 *    list of conditions and the following disclaimer.
 13 *
 14 * 2. Redistributions in binary form must reproduce the above copyright notice,
 15 *    this list of conditions and the following disclaimer in the documentation
 16 *    and/or other materials provided with the distribution.
 17 *
 18 * 3. Neither the name of the copyright holder nor the names of its
 19 *    contributors may be used to endorse or promote products derived from
 20 *    this software without specific prior written permission.
 21 *
 22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 23 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 24 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 25 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
 26 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 27 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 28 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 29 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 30 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 32 *
 33 * We kindly request you to use one or more of the following phrases to refer to
 34 * foxBMS in your hardware, software, documentation or advertising materials:
 35 *
 36 * - "This product uses parts of foxBMS&reg;"
 37 * - "This product includes parts of foxBMS&reg;"
 38 * - "This product is derived from foxBMS&reg;"
 39 *
 40 */
 41
 42/**
 43 * @file    state-machine.c
 44 * @author  foxBMS Team
 45 * @date    2020-10-29 (date of creation)
 46 * @updated 2026-10-06 (date of last update)
 47 * @version v1.12.0
 48 * @ingroup STATE_MACHINE
 49 * @prefix  EG
 50 *
 51 * @brief   Implementation of some driver that needs a state machine
 52 * @details This source file implements the example state machine used in the
 53 *          style-guide documentation.
 54 *          It demonstrates a trigger-driven state machine with main states,
 55 *          substates, timing between transitions, and basic error handling.
 56 */
 57
 58/*========== Includes =======================================================*/
 59#include "state-machine.h"
 60
 61#include "fassert.h"
 62#include "fstd_types.h"
 63#include "os.h"
 64
 65#include <stdbool.h>
 66#include <stdint.h>
 67
 68/*========== Macros and Definitions =========================================*/
 69/**
 70 * state machine short time definition in #EG_Trigger calls until next state is
 71 * processed
 72 */
 73#define EG_FSM_SHORT_TIME (1u)
 74
 75/**
 76 * state machine medium time definition in #EG_Trigger calls until next
 77 * state/substate is processed
 78 */
 79#define EG_FSM_MEDIUM_TIME (5u)
 80
 81/**
 82 * state machine long time definition in #EG_Trigger calls until next
 83 * state/substate is processed
 84 */
 85#define EG_FSM_LONG_TIME (10u)
 86
 87/** Symbolic names to check for multiple calls of #EG_Trigger */
 88typedef enum {
 89    EG_MULTIPLE_CALLS_NO,  /*!< no multiple calls, OK */
 90    EG_MULTIPLE_CALLS_YES, /*!< multiple calls, not OK */
 91} EG_CHECK_MULTIPLE_CALLS_e;
 92
 93/*========== Static Constant and Variable Definitions =======================*/
 94
 95/*========== Extern Constant and Variable Definitions =======================*/
 96
 97/** local instance of the driver-state */
 98EG_STATE_s eg_state = {
 99    .timer            = 0,
100    .triggerEntry     = 0,
101    .nextState        = EG_FSM_STATE_HAS_NEVER_RUN,
102    .currentState     = EG_FSM_STATE_HAS_NEVER_RUN,
103    .previousState    = EG_FSM_STATE_HAS_NEVER_RUN,
104    .nextSubstate     = EG_FSM_SUBSTATE_DUMMY,
105    .currentSubstate  = EG_FSM_SUBSTATE_DUMMY,
106    .previousSubstate = EG_FSM_SUBSTATE_DUMMY,
107    .information.r0   = 0,
108    .information.r1   = 0,
109    .information.r2   = 0,
110};
111
112/*========== Static Function Prototypes =====================================*/
113/**
114 * @brief   check for multiple calls of state machine trigger function
115 * @details The trigger function is not reentrant, which means it cannot
116 *          be called multiple times. This functions increments the
117 *          triggerEntry counter once and must be called each time the
118 *          trigger function is called. If triggerEntry is greater than
119 *          one, there were multiple calls. For this function to work,
120 *          triggerEntry must be decremented each time the trigger function
121 *          is called, even if no processing do because the timer is
122 *          non-zero.
123 * @param   pEgState state of the fake state machine
124 * @return  #EG_MULTIPLE_CALLS_YES if there were multiple calls,
125 *          #EG_MULTIPLE_CALLS_NO otherwise
126 */
127static EG_CHECK_MULTIPLE_CALLS_e EG_CheckMultipleCalls(EG_STATE_s *pEgState);
128
129/**
130 * @brief   Sets the next state, the next substate and the timer value
131 *          of the state variable.
132 * @param   pEgState       state of the example state machine
133 * @param   nextState      state to be transferred into
134 * @param   nextSubstate   substate to be transferred into
135 * @param   idleTime       wait time for the state machine
136 */
137static void EG_SetState(
138    EG_STATE_s *pEgState,
139    EG_FSM_STATES_e nextState,
140    EG_FSM_SUBSTATES_e nextSubstate,
141    uint16_t idleTime);
142
143/**
144 * @brief   Sets the next substate and the timer value
145 *          of the state variable.
146 * @param   pEgState       state of the example state machine
147 * @param   nextSubstate   substate to be transferred into
148 * @param   idleTime       wait time for the state machine
149 */
150static void EG_SetSubstate(EG_STATE_s *pEgState, EG_FSM_SUBSTATES_e nextSubstate, uint16_t idleTime);
151
152/**
153 * @brief   dummy function for initialization substate
154 *          #EG_FSM_SUBSTATE_INITIALIZATION_0
155 * @return  returns always true
156 */
157static bool EG_SomeInitializationFunction0(void);
158
159/**
160 * @brief   dummy function for initialization substate
161 *          #EG_FSM_SUBSTATE_INITIALIZATION_1
162 * @return  returns always true
163 */
164static bool EG_SomeInitializationFunction1(void);
165
166/**
167 * @brief   dummy function to check if the initialization
168 *          step of the state machine was successful
169 *          (#EG_FSM_SUBSTATE_INITIALIZATION_1)
170 * @return  returns always true
171 */
172static bool EG_SomeInitializationFunctionExit(void);
173
174/**
175 * @brief   dummy function making a test to determine
176 *          the outcome of substate #EG_FSM_SUBSTATE_RUNNING_0
177 * @return  returns always true
178 */
179static bool EG_SomeRunningFunction0(void);
180
181/**
182 * @brief   dummy function making a test to determine
183 *          the outcome of substate EG_FSM_SUBSTATE_RUNNING_1
184 * @return  returns always true
185 */
186static bool EG_SomeRunningFunction1(void);
187
188/**
189 * @brief   dummy function making a test to determine
190 *          the outcome of substate EG_FSM_SUBSTATE_RUNNING_2
191 * @return  returns always true
192 */
193static bool EG_SomeRunningFunction2(void);
194
195/**
196 * @brief   Processes the initialization state
197 * @param   pEgState state of the example state machine
198 * @return  next state
199 */
200static EG_FSM_STATES_e EG_ProcessInitializationState(EG_STATE_s *pEgState);
201
202/**
203 * @brief   Processes the running state
204 * @param   pEgState state of the example state machine
205 * @return  next state
206 */
207static EG_FSM_STATES_e EG_ProcessRunningState(EG_STATE_s *pEgState);
208
209/**
210 * @brief   Defines the state transitions
211 * @details This function contains the implementation of the state
212 *          machine, i.e., the sequence of states and substates.
213 *          It is called by the trigger function every time
214 *          the state machine timer has a non-zero value.
215 * @param   pEgState state of the example state machine
216 * @return  Always #STD_OK
217 */
218static STD_RETURN_TYPE_e EG_RunStateMachine(EG_STATE_s *pEgState);
219
220/*========== Static Function Implementations ================================*/
221
222static EG_CHECK_MULTIPLE_CALLS_e EG_CheckMultipleCalls(EG_STATE_s *pEgState) {
223    FAS_ASSERT(pEgState != NULL_PTR);
224    EG_CHECK_MULTIPLE_CALLS_e multipleCalls = EG_MULTIPLE_CALLS_NO;
225    OS_EnterTaskCritical();
226    if (pEgState->triggerEntry == 0u) {
227        pEgState->triggerEntry++;
228    } else {
229        multipleCalls = EG_MULTIPLE_CALLS_YES; /* multiple call of function EG_Trigger for instance pEgState */
230    }
231    OS_ExitTaskCritical();
232    return multipleCalls;
233}
234
235static void EG_SetState(
236    EG_STATE_s *pEgState,
237    EG_FSM_STATES_e nextState,
238    EG_FSM_SUBSTATES_e nextSubstate,
239    uint16_t idleTime) {
240    FAS_ASSERT(pEgState != NULL_PTR);
241    bool earlyExit = false;
242
243    pEgState->timer            = idleTime;
244    pEgState->previousState    = pEgState->currentState;
245    pEgState->previousSubstate = pEgState->currentSubstate;
246
247    if ((pEgState->currentState == nextState) && (pEgState->currentSubstate == nextSubstate)) {
248        /* Next state and next substate equal to current state and substate: nothing to do */
249        pEgState->nextState    = EG_FSM_STATE_DUMMY;    /* no state transition required -> reset */
250        pEgState->nextSubstate = EG_FSM_SUBSTATE_DUMMY; /* no substate transition required -> reset */
251        earlyExit              = true;
252    }
253
254    if (earlyExit == false) {
255        if (pEgState->currentState != nextState) {
256            /* distinguish between just a state transfer to the error state and a normal state transfer */
257            if (nextState == EG_FSM_STATE_ERROR) {
258                /* Error state gets treated differently since we dont need to enter it through the entry substate */
259                pEgState->currentState    = nextState;
260                pEgState->currentSubstate = nextSubstate;
261            } else {
262                /* Next state is different than the current one: switch to it and set substate to entry value */
263                pEgState->previousState    = pEgState->currentState;
264                pEgState->currentState     = nextState;
265                pEgState->previousSubstate = pEgState->currentSubstate;
266                pEgState->currentSubstate  = EG_FSM_SUBSTATE_ENTRY; /* entry state after a top level state change */
267                pEgState->nextState        = EG_FSM_STATE_DUMMY;    /* no state transition required -> reset */
268                pEgState->nextSubstate     = EG_FSM_SUBSTATE_DUMMY; /* no substate transition required -> reset */
269            }
270        } else if (pEgState->currentSubstate != nextSubstate) {
271            /* Only the next substate is different, switch to it */
272            EG_SetSubstate(pEgState, nextSubstate, idleTime);
273        } else {
274            ;
275        }
276    }
277}
278
279static void EG_SetSubstate(EG_STATE_s *pEgState, EG_FSM_SUBSTATES_e nextSubstate, uint16_t idleTime) {
280    FAS_ASSERT(pEgState != NULL_PTR);
281    pEgState->timer            = idleTime;
282    pEgState->previousSubstate = pEgState->currentSubstate;
283    pEgState->currentSubstate  = nextSubstate;
284    pEgState->nextSubstate     = EG_FSM_SUBSTATE_DUMMY; /* substate has been set, now reset value for nextSubstate */
285}
286
287static bool EG_SomeInitializationFunction0(void) {
288    return true;
289}
290
291static bool EG_SomeInitializationFunction1(void) {
292    return true;
293}
294
295static bool EG_SomeInitializationFunctionExit(void) {
296    return true;
297}
298
299static bool EG_SomeRunningFunction0(void) {
300    return true;
301}
302
303static bool EG_SomeRunningFunction1(void) {
304    return true;
305}
306
307static bool EG_SomeRunningFunction2(void) {
308    return true;
309}
310
311static EG_FSM_STATES_e EG_ProcessInitializationState(EG_STATE_s *pEgState) {
312    EG_FSM_STATES_e nextState = EG_FSM_STATE_INITIALIZATION; /* default behavior: stay in state */
313    switch (pEgState->currentSubstate) {
314        case EG_FSM_SUBSTATE_ENTRY:
315            /* Nothing to do, just transfer to next substate */
316            EG_SetSubstate(pEgState, EG_FSM_SUBSTATE_INITIALIZATION_0, EG_FSM_SHORT_TIME);
317            break;
318
319        case EG_FSM_SUBSTATE_INITIALIZATION_0:
320            if (EG_SomeInitializationFunction0() == true) {
321                EG_SetSubstate(pEgState, EG_FSM_SUBSTATE_INITIALIZATION_1, EG_FSM_SHORT_TIME);
322            } else {
323                /* Something went wrong, so transition to error state */
324                nextState = EG_FSM_STATE_ERROR;
325            }
326            break;
327
328        case EG_FSM_SUBSTATE_INITIALIZATION_1:
329            if (EG_SomeInitializationFunction1() == true) {
330                EG_SetSubstate(pEgState, EG_FSM_SUBSTATE_INITIALIZATION_EXIT, EG_FSM_SHORT_TIME);
331            } else {
332                /* Something went wrong, so transition to error state */
333                nextState = EG_FSM_STATE_ERROR;
334            }
335            break;
336
337        case EG_FSM_SUBSTATE_INITIALIZATION_EXIT:
338            if (EG_SomeInitializationFunctionExit() == true) {
339                /* Initialization was successful, so transition to running state */
340                nextState = EG_FSM_STATE_RUNNING;
341            } else {
342                /* Something went wrong, so transition to error state */
343                nextState = EG_FSM_STATE_ERROR;
344            }
345            break;
346
347        default:                  /* LCOV_EXCL_LINE */
348            FAS_ASSERT(FAS_TRAP); /* LCOV_EXCL_LINE */
349            break;                /* LCOV_EXCL_LINE */
350    }
351    return nextState;
352}
353
354static EG_FSM_STATES_e EG_ProcessRunningState(EG_STATE_s *pEgState) {
355    EG_FSM_STATES_e nextState = EG_FSM_STATE_RUNNING; /* default behavior: stay in state */
356    switch (pEgState->currentSubstate) {
357        case EG_FSM_SUBSTATE_ENTRY:
358            /* Nothing to do, just transfer to next substate */
359            EG_SetSubstate(pEgState, EG_FSM_SUBSTATE_RUNNING_0, EG_FSM_SHORT_TIME);
360            break;
361
362        case EG_FSM_SUBSTATE_RUNNING_0:
363            if (EG_SomeRunningFunction0() == true) {
364                EG_SetSubstate(pEgState, EG_FSM_SUBSTATE_RUNNING_1, EG_FSM_SHORT_TIME);
365            } else {
366                /* Something went wrong, so transition to error state */
367                nextState = EG_FSM_STATE_ERROR;
368            }
369            break;
370
371        case EG_FSM_SUBSTATE_RUNNING_1:
372            if (EG_SomeRunningFunction1() == true) {
373                EG_SetSubstate(pEgState, EG_FSM_SUBSTATE_RUNNING_2, EG_FSM_SHORT_TIME);
374            } else {
375                /* Something went wrong, so transition to error state */
376                nextState = EG_FSM_STATE_ERROR;
377            }
378            break;
379
380        case EG_FSM_SUBSTATE_RUNNING_2:
381            if (EG_SomeRunningFunction2() == true) {
382                EG_SetSubstate(pEgState, EG_FSM_SUBSTATE_RUNNING_0, EG_FSM_SHORT_TIME);
383            } else {
384                /* Something went wrong, so transition to error state */
385                nextState = EG_FSM_STATE_ERROR;
386            }
387            break;
388
389        default:
390            FAS_ASSERT(FAS_TRAP);
391            break; /* LCOV_EXCL_LINE */
392    }
393
394    return nextState;
395}
396
397static STD_RETURN_TYPE_e EG_RunStateMachine(EG_STATE_s *pEgState) {
398    STD_RETURN_TYPE_e ranStateMachine = STD_OK;
399    EG_FSM_STATES_e nextState         = EG_FSM_STATE_DUMMY;
400    switch (pEgState->currentState) {
401        /********************************************** STATE: HAS NEVER RUN */
402        case EG_FSM_STATE_HAS_NEVER_RUN:
403            /* Options:
404             * (1) Initial value, just transfer into the entry state
405             */
406            EG_SetState(pEgState, EG_FSM_STATE_UNINITIALIZED, EG_FSM_SUBSTATE_ENTRY, EG_FSM_SHORT_TIME);
407            break;
408
409        /********************************************** STATE: UNINITIALIZED */
410        case EG_FSM_STATE_UNINITIALIZED:
411            /* Options:
412             * (1) Nothing to do in this uninitialized state,
413                   just transfer into the entry state
414             */
415            EG_SetState(pEgState, EG_FSM_STATE_INITIALIZATION, EG_FSM_SUBSTATE_ENTRY, EG_FSM_SHORT_TIME);
416            break;
417
418        /********************************************* STATE: INITIALIZATION */
419        case EG_FSM_STATE_INITIALIZATION:
420            /* Options:
421             * (1) stay in this main state,
422             * (2) transition to error state
423             * (3) transition to next allowed/defined state(s):
424             *     - EG_FSM_STATE_RUNNING
425             * (4) invalid main state requested to transition from this state
426             *     to --> assert
427             */
428            nextState = EG_ProcessInitializationState(pEgState);
429            if (nextState == EG_FSM_STATE_INITIALIZATION) {
430                /* staying in state, processed by state function */
431            } else if (nextState == EG_FSM_STATE_ERROR) {
432                EG_SetState(pEgState, EG_FSM_STATE_ERROR, EG_FSM_SUBSTATE_ENTRY, EG_FSM_SHORT_TIME);
433            } else if (nextState == EG_FSM_STATE_RUNNING) {
434                EG_SetState(pEgState, EG_FSM_STATE_RUNNING, EG_FSM_SUBSTATE_ENTRY, EG_FSM_SHORT_TIME);
435            } else {
436                FAS_ASSERT(FAS_TRAP); /* invalid state transition requested */
437            }
438            break;
439
440        /**************************************************** STATE: RUNNING */
441        case EG_FSM_STATE_RUNNING:
442            /* Options:
443             * (1) stay in this main state,
444             * (2) transition to error state
445             * (3) invalid main state requested to transition from this state
446             *     to --> assert
447             */
448            nextState = EG_ProcessRunningState(pEgState);
449            if (nextState == EG_FSM_STATE_RUNNING) {
450                /* staying in state, processed by state function */
451            } else if (nextState == EG_FSM_STATE_ERROR) {
452                EG_SetState(pEgState, EG_FSM_STATE_ERROR, EG_FSM_SUBSTATE_ENTRY, EG_FSM_SHORT_TIME);
453            } else {
454                FAS_ASSERT(FAS_TRAP); /* invalid state transition requested */
455            }
456            break;
457
458        /****************************************************** STATE: ERROR */
459        case EG_FSM_STATE_ERROR:
460            /* implement error processing here or trap */
461            break;
462
463        /**************************************************** STATE: DEFAULT */
464        default:
465            /* all cases must be processed, trap if unknown state arrives */
466            FAS_ASSERT(FAS_TRAP);
467            break;
468    }
469
470    return ranStateMachine;
471}
472
473/*========== Extern Function Implementations ================================*/
474extern STD_RETURN_TYPE_e EG_Trigger(EG_STATE_s *pEgState) {
475    FAS_ASSERT(pEgState != NULL_PTR);
476    bool earlyExit                = false;
477    STD_RETURN_TYPE_e returnValue = STD_OK;
478
479    /* Check multiple calls of function */
480    if (EG_MULTIPLE_CALLS_YES == EG_CheckMultipleCalls(pEgState)) {
481        returnValue = STD_NOT_OK;
482        earlyExit   = true;
483    }
484
485    if (earlyExit == false) {
486        if (pEgState->timer > 0u) {
487            if ((--pEgState->timer) > 0u) {
488                pEgState->triggerEntry--;
489                returnValue = STD_OK;
490                earlyExit   = true;
491            }
492        }
493    }
494
495    if (earlyExit == false) {
496        EG_RunStateMachine(pEgState);
497        pEgState->triggerEntry--;
498    }
499    return returnValue;
500}
501
502/*========== Externalized Static Function Implementations (Unit Test) =======*/
503#ifdef UNITY_UNIT_TEST
504#endif