qep_hsm.c File Reference

QHsm implementation More...

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

Include dependency graph for qep_hsm.c:

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 More...
#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 More...
static QEvt const	QEP_reservedEvt_ []

Detailed Description

QHsm implementation

Definition in file qep_hsm.c.

Macro Definition Documentation

QEP_TRIG_

#define QEP_TRIG_	(		state_,
			sig_
	)		((*(state_))(me, &QEP_reservedEvt_[(sig_)]))

helper macro to trigger reserved event in an HSM

Definition at line 79 of file qep_hsm.c.

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)

helper macro to trigger exit action in an HSM

Definition at line 83 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)

helper macro to trigger entry action in an HSM

Definition at line 93 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 56 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]	me	pointer (see Object Orientation)
[in,out]	path	array 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 411 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]	me	pointer (see Object Orientation)
[in]	initial	pointer 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 127 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]	me	pointer (see Object Orientation)
[in]	e	pointer 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 147 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]	me	pointer (see Object Orientation)
[in]	e	pointer 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 233 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]	me	pointer (see Object Orientation)
[in]	e	pointer 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 252 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]	me	pointer (see Object Orientation)
[in]	state	pointer 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 562 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]	me	pointer (see Object Orientation)
[in]	parent	pointer to the state-handler function

Returns

the child of a given parent state, which is an ancestor of the current active state. For the corner case when the currently active state is the given parent state, function returns the parent 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 found

Definition at line 607 of file qep_hsm.c.

Variable Documentation

QP_versionStr

char_t const QP_versionStr[6] = QP_VERSION_STR

the current QP version number string in ROM, based on QP_VERSION_STR

Definition at line 52 of file qep_hsm.c.

QEP_reservedEvt_

QEvt const QEP_reservedEvt_[]

static

Initial value:

= {
    { (QSignal)QEP_EMPTY_SIG_, (uint8_t)0, (uint8_t)0 },
    { (QSignal)Q_ENTRY_SIG,    (uint8_t)0, (uint8_t)0 },
    { (QSignal)Q_EXIT_SIG,     (uint8_t)0, (uint8_t)0 },
    { (QSignal)Q_INIT_SIG,     (uint8_t)0, (uint8_t)0 }
}

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 71 of file qep_hsm.c.