Hierarchical State Machine class. More...

#include "qep.h"

Inheritance diagram for QHsm:

Public Member Functions
bool	QHsm_isIn (QHsm *const me, QStateHandler const state)

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

Static Public Member Functions
static QStateHandler	QHsm_state (QHsm *const me)

Protected Member Functions
void	QHsm_ctor (QHsm *const me, QStateHandler const initial)

QState	QHsm_top (QHsm const const me, QEvt const const e)

void	QHsm_init_ (QHsm const me, void const const e, uint_fast8_t const qs_id)

void	QHsm_dispatch_ (QHsm const me, QEvt const const e, uint_fast8_t const qs_id)

Private Member Functions
QStateHandler	QHsm_getStateHandler_ (QHsm *const me)

void	QHsm_state_entry_ (QHsm *const me, QStateHandler const state, uint_fast8_t const qs_id)

bool	QHsm_state_exit_ (QHsm *const me, QStateHandler const state, uint_fast8_t const qs_id)

int_fast8_t	QHsm_tran_ (QHsm const me, QStateHandler const path, uint_fast8_t const qs_id)

Static Private Member Functions
static QState	QHsm_reservedEvt_ (QHsm *const me, QStateHandler const state, enum QReservedSig const sig)

Private Attributes
struct QHsmVtable const *	vptr

union QHsmAttr	state

union QHsmAttr	temp

Detailed Description

QHsm represents a Hierarchical State Machine (HSM) with full support for hierarchical nesting of states, entry/exit actions, initial transitions, and transitions to history in any composite state. This class is designed for ease of manual coding of HSMs in C, but it is also supported by the QM modeling tool.

QHsm is also the base class for the QMsm state machine, which provides a superior efficiency, but requires the use of the QM modeling tool to generate code.

Note: QHsm is not intended to be instantiated directly, but rather serves as the abstract base class for derivation of state machines in the QP application.

Traceability

Usage: The following example illustrates how to derive a state machine class from QHsm. Please note that the QHsm member super is defined as the FIRST member of the derived class.
typedef struct {

QHsm super; /* inhertits QHsm */

double operand1;

double operand2;

char display[DISP_WIDTH + 1];

uint8_t len;

uint8_t opKey;

} Calc;

QHsm
Hierarchical State Machine class.
Definition: qep.h:353

Definition at line 353 of file qep.h.

Member Function Documentation

◆ 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.

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	current instance pointer (see oop)
[in]	state	pointer to the state-handler function to be tested

Returns: 'true' if the HSM "is in" the state and 'false' otherwise

Precondition qep_hsm:600

the state configuration must be stable

Traceability

REQ-QP-02_25

Definition at line 107 of file qep_hsm.c.

◆ QHsm_state()

static QStateHandler QHsm_state ( QHsm *const me )

inlinestatic

Obtain the current active state from a HSM (read only).

Parameters

[in] me current instance pointer (see oop)

Returns: the current active state of the QHsm class

Note: This function is used in QM for auto-generating code for state history.

Definition at line 414 of file qep.h.

◆ QHsm_childState()

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

Obtain the current active child state of a given parent in QHsm

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	current instance pointer (see oop)
[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.

Postcondition qep_hsm:890

the child must be found

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.

Traceability

REQ-QP-02_39

Definition at line 133 of file qep_hsm.c.

◆ QHsm_ctor()

void QHsm_ctor	(	QHsm *const	me,
		QStateHandler const	initial
	)

protected

Protected "constructor" of QHsm

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	current instance pointer (see oop)
[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;

}

Q_STATE_CAST
#define Q_STATE_CAST(handler_)
Definition: qep.h:1050

QHsm::QHsm_ctor
void QHsm_ctor(QHsm *const me, QStateHandler const initial)
Definition: qep_hsm.c:166

Traceability

Definition at line 166 of file qep_hsm.c.

◆ QHsm_top()

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

protected

The top-state of QHsm.

QHsm_top() is the ultimate root of state hierarchy in all HSMs derived from QHsm.

Parameters

[in]	me	current instance pointer (see oop)
[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.

Traceability

REQ-QP-02_40

Definition at line 183 of file qep_hsm.c.

◆ QHsm_init_()

void QHsm_init_	(	QHsm *const	me,
		void const *const	e,
		uint_fast8_t const	qs_id
	)

protected

Implementation of the top-most initial tran. in QHsm.

Executes the top-most initial transition in a HSM.

Parameters

[in,out]	me	current instance pointer (see oop)
[in]	e	pointer to an extra parameter (might be NULL)
[in]	qs_id	QS-id of this state machine (for QS local filter)

Precondition qep_hsm:200

the virtual pointer must be initialized,
the top-most initial transition must be initialized,
the initial transition must not be taken yet.

Note: Must be called only ONCE after the QHsm_ctor().

Traceability

Definition at line 193 of file qep_hsm.c.

◆ QHsm_dispatch_()

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

protected

Implementation of dispatching events to a QHsm

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	current instance pointer (see oop)
[in]	e	pointer to the event to be dispatched to the HSM
[in]	qs_id	QS-id of this state machine (for QS local filter)

Precondition qep_hsm:400

the current state must be initialized and
the state configuration must be stable

Note: This function should be called only via the virtual table (see QHSM_DISPATCH()) and should NOT be called directly in the applications.

Traceability

REQ-QP-02_10

Definition at line 274 of file qep_hsm.c.

◆ QHsm_getStateHandler_()

QStateHandler QHsm_getStateHandler_ ( QHsm *const me )

private

Implementation of getting the state handler in a QHsm subclass

Definition at line 425 of file qep_hsm.c.

◆ QHsm_state_entry_()

void QHsm_state_entry_	(	QHsm *const	me,
		QStateHandler const	state,
		uint_fast8_t const	qs_id
	)

private

Helper function to execute entry into a given state in a hierarchical state machine (HSM).

Parameters

[in]	state	state handler function
[in]	qs_id	QS-id of this state machine (for QS local filter)

Definition at line 567 of file qep_hsm.c.

◆ QHsm_state_exit_()

bool QHsm_state_exit_	(	QHsm *const	me,
		QStateHandler const	state,
		uint_fast8_t const	qs_id
	)

private

Helper function to execute exit from a given state in a hierarchical state machine (HSM).

Parameters

[in]	state	state handler function
[in]	qs_id	QS-id of this state machine (for QS local filter)

Returns: 'true' if the exit action has been found in the state and 'flase' otherwise.

Definition at line 587 of file qep_hsm.c.

◆ QHsm_reservedEvt_()

static QState QHsm_reservedEvt_	(	QHsm *const	me,
		QStateHandler const	state,
		enum QReservedSig const	sig
	)

inlinestaticprivate

helper function to trigger reserved event in an QHsm

Parameters

[in]	state	state handler function
[in]	sig	reserved signal to trigger

Definition at line 88 of file qep_hsm.c.

◆ QHsm_tran_()

int_fast8_t QHsm_tran_	(	QHsm *const	me,
		QStateHandler *const	path,
		uint_fast8_t const	qs_id
	)

private

Definition at line 432 of file qep_hsm.c.

Member Data Documentation

◆ vptr

struct QHsmVtable const* vptr

private

Virtual pointer

Traceability

REQ-QP-02_10

Definition at line 362 of file qep.h.

◆ state

union QHsmAttr state

private

Current active state (state-variable).

Definition at line 369 of file qep.h.

◆ temp

union QHsmAttr temp

private

Temporary: target/act-table, etc.

Definition at line 374 of file qep.h.

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Member Functions

Protected Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Function Documentation

◆ QHsm_isIn()

◆ QHsm_state()

◆ QHsm_childState()

◆ QHsm_ctor()

◆ QHsm_top()

◆ QHsm_init_()

◆ QHsm_dispatch_()

◆ QHsm_getStateHandler_()

◆ QHsm_state_entry_()

◆ QHsm_state_exit_()

◆ QHsm_reservedEvt_()

◆ QHsm_tran_()

Member Data Documentation

◆ vptr

◆ state

◆ temp