QP/C  6.0.0
qep_hsm.c File Reference

QHsm implementation More...

#include "qep_port.h"
#include "qassert.h"
#include "qs_port.h"

Go to the source code of this file.

Macros

#define QEP_TRIG_(state_, sig_)   ((*(state_))(me, &QEP_reservedEvt_[(sig_)]))
 helper macro to trigger reserved event in an HSM
 
#define QEP_EXIT_(state_)
 helper macro to trigger exit action in an HSM More...
 
#define QEP_ENTER_(state_)
 helper macro to trigger entry action in an HSM More...
 

Enumerations

enum  { QEP_EMPTY_SIG_ = 0, QHSM_MAX_NEST_DEPTH_ = 6 }
 internal QEP constants More...
 

Functions

static int_fast8_t QHsm_tran_ (QHsm *const me, QStateHandler path[QHSM_MAX_NEST_DEPTH_])
 helper function to execute a transition chain in HSM More...
 
void QHsm_ctor (QHsm *const me, QStateHandler initial)
 Protected "constructor" of QHsm. More...
 
void QHsm_init_ (QHsm *const me, QEvt const *const e)
 Implementation of the top-most initial transition in QHsm subclass. More...
 
QState QHsm_top (void const *const me, QEvt const *const e)
 the top-state. More...
 
void QHsm_dispatch_ (QHsm *const me, QEvt const *const e)
 Implementation of dispatching events to a QHsm subclass. More...
 
bool QHsm_isIn (QHsm *const me, QStateHandler const state)
 Tests if a given state is part of the current active state configuration in QHsm subclasses. More...
 
QStateHandler QHsm_childState_ (QHsm *const me, QStateHandler const parent)
 Helper function to obtain the current active child state of a parent. More...
 

Variables

char_t const QP_versionStr [6] = QP_VERSION_STR
 the current QP version number string in ROM, based on QP_VERSION_STR
 
static QEvt const QEP_reservedEvt_ []
 

Detailed Description

QHsm implementation

Definition in file qep_hsm.c.

Macro Definition Documentation

◆ QEP_EXIT_

#define QEP_EXIT_ (   state_)
Value:
do { \
if (QEP_TRIG_((state_), Q_EXIT_SIG) == (QState)Q_RET_HANDLED) { \
QS_BEGIN_(QS_QEP_STATE_EXIT, QS_priv_.locFilter[SM_OBJ], me) \
QS_OBJ_(me); \
QS_FUN_(state_); \
QS_END_() \
} \
} while (0)
event handled (internal transition)
Definition: qep.h:501
state machine object for QEP
Definition: qs.h:1057
uint_fast8_t QState
typedef of the return type from a state/action-handler function.
Definition: qep.h:209
void const * locFilter[MAX_OBJ]
local QS filters
Definition: qs.h:1069
a state was exited
Definition: qs.h:71
#define QEP_TRIG_(state_, sig_)
helper macro to trigger reserved event in an HSM
Definition: qep_hsm.c:78
signal for coding exit actions
Definition: qep.h:608

helper macro to trigger exit action in an HSM

Definition at line 82 of file qep_hsm.c.

◆ QEP_ENTER_

#define QEP_ENTER_ (   state_)
Value:
do { \
if (QEP_TRIG_((state_), Q_ENTRY_SIG) == (QState)Q_RET_HANDLED) { \
QS_BEGIN_(QS_QEP_STATE_ENTRY, QS_priv_.locFilter[SM_OBJ], me) \
QS_OBJ_(me); \
QS_FUN_(state_); \
QS_END_() \
} \
} while (0)
event handled (internal transition)
Definition: qep.h:501
a state was entered
Definition: qs.h:70
state machine object for QEP
Definition: qs.h:1057
signal for coding entry actions
Definition: qep.h:607
uint_fast8_t QState
typedef of the return type from a state/action-handler function.
Definition: qep.h:209
void const * locFilter[MAX_OBJ]
local QS filters
Definition: qs.h:1069
#define QEP_TRIG_(state_, sig_)
helper macro to trigger reserved event in an HSM
Definition: qep_hsm.c:78

helper macro to trigger entry action in an HSM

Definition at line 92 of file qep_hsm.c.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

internal QEP constants

Enumerator
QEP_EMPTY_SIG_ 

reserved empty signal for internal use only

QHSM_MAX_NEST_DEPTH_ 

maximum depth of state nesting in a HSM (including the top level), must be >= 3

Definition at line 55 of file qep_hsm.c.

Function Documentation

◆ QHsm_tran_()

static int_fast8_t QHsm_tran_ ( QHsm *const  me,
QStateHandler  path[QHSM_MAX_NEST_DEPTH_] 
)
static

helper function to execute a transition chain in HSM

Description
Static helper function to execute transition sequence in a hierarchical state machine (HSM).
Parameters
[in,out]mepointer (see Object Orientation)
[in,out]patharray of pointers to state-handler functions to execute the entry actions
Returns
the depth of the entry path stored in the path parameter.

Definition at line 410 of file qep_hsm.c.

◆ QHsm_ctor()

void QHsm_ctor ( QHsm *const  me,
QStateHandler  initial 
)

Protected "constructor" of QHsm.

Description
Performs the first step of HSM initialization by assigning the initial pseudostate to the currently active state of the state machine.
Parameters
[in,out]mepointer (see Object Orientation)
[in]initialpointer to the top-most initial state-handler function in the derived state machine
Note
Must be called only by the constructors of the derived state machines.
Must be called only ONCE before QHSM_INIT().
Usage
The following example illustrates how to invoke QHsm_ctor() in the "constructor" of a derived state machine:
void Calc_ctor(Calc * const me) {
/* superclass' ctor */
QHsm_ctor(&me->super, Q_STATE_CAST(&Calc_initial));
me->operand1 = 0.0;
me->operand2 = 0.0;
me->len = 0U;
me->opKey = 0U;
}

Definition at line 126 of file qep_hsm.c.

◆ QHsm_init_()

void QHsm_init_ ( QHsm *const  me,
QEvt const *const  e 
)

Implementation of the top-most initial transition in QHsm subclass.

Description
Executes the top-most initial transition in a HSM.
Parameters
[in,out]mepointer (see Object Orientation)
[in]epointer to the initialization event (might be NULL)
Note
Must be called only ONCE after the QHsm_ctor().
Precondition
the virtual pointer must be initialized, the top-most initial transition must be initialized, and the initial transition must not be taken yet.

Definition at line 146 of file qep_hsm.c.

◆ QHsm_top()

QState QHsm_top ( void const *const  me,
QEvt const *const  e 
)

the top-state.

Description
QHsm_top() is the ultimate root of state hierarchy in all HSMs derived from QHsm.
Parameters
[in]mepointer (see Object Orientation)
[in]epointer to the event to be dispatched to the FSM
Returns
Always returns Q_RET_IGNORED, which means that the top state ignores all events.
Note
The parameters to this state handler are not used. They are provided for conformance with the state-handler function signature QStateHandler.

Definition at line 232 of file qep_hsm.c.

◆ QHsm_dispatch_()

void QHsm_dispatch_ ( QHsm *const  me,
QEvt const *const  e 
)

Implementation of dispatching events to a QHsm subclass.

Description
Dispatches an event for processing to a hierarchical state machine (HSM). The processing of an event represents one run-to-completion (RTC) step.
Parameters
[in,out]mepointer (see Object Orientation)
[in]epointer to the event to be dispatched to the HSM
Note
This function should be called only via the virtual table (see QHSM_DISPATCH()) and should NOT be called directly in the applications.
Precondition
the current state must be initialized and the state configuration must be stable

Definition at line 251 of file qep_hsm.c.

◆ QHsm_isIn()

bool QHsm_isIn ( QHsm *const  me,
QStateHandler const  state 
)

Tests if a given state is part of the current active state configuration in QHsm subclasses.

Description
Tests if a state machine derived from QHsm is-in a given state.
Note
For a HSM, to "be in a state" means also to be in a superstate of of the state.
Parameters
[in]mepointer (see Object Orientation)
[in]statepointer to the state-handler function to be tested
Returns
'true' if the HSM "is in" the state and 'false' otherwise
Precondition
the state configuration must be stable

Definition at line 560 of file qep_hsm.c.

◆ QHsm_childState_()

QStateHandler QHsm_childState_ ( QHsm *const  me,
QStateHandler const  parent 
)

Helper function to obtain the current active child state of a parent.

Description
Finds the child state of the given parent, such that this child state is an ancestor of the currently active state. The main purpose of this function is to support shallow history transitions in state machines derived from QHsm.
Parameters
[in]mepointer (see Object Orientation)
[in]parentpointer to the state-handler function
Returns
the child of a given parent state, which is an ancestor of the currently active state
Note
this function is designed to be called during state transitions, so it does not necessarily start in a stable state configuration. However, the function establishes stable state configuration upon exit.
See also
QHsm_childState()
Postcondition
the child must be confirmed

Definition at line 602 of file qep_hsm.c.

Variable Documentation

◆ QEP_reservedEvt_

QEvt const QEP_reservedEvt_[]
static
Initial value:
= {
}
unsigned char uint8_t
exact-width 8-bit unsigned int
Definition: stdint.h:28
uint16_t QSignal
QSignal represents the signal of an event.
Definition: qep.h:130
signal for coding entry actions
Definition: qep.h:607
reserved empty signal for internal use only
Definition: qep_hsm.c:56
signal for coding initial transitions
Definition: qep.h:609
signal for coding exit actions
Definition: qep.h:608
Description
Static, preallocated standard events that the QEP event processor sends to state handler functions of QHsm and QFsm subclasses to execute entry actions, exit actions, and initial transitions.

Definition at line 70 of file qep_hsm.c.