#include <qep.h>

Inheritance diagram for QHsm:

Public Member Functions
QStateHandler	QHsm_childState (QHsm *const me, QStateHandler const parent)

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

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

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

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

Private Member Functions
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)

QStateHandler	QHsm_getStateHandler_ (QHsm *const me)

Static Private Member Functions
static int_fast8_t	QHsm_tran_ (QHsm *const me, QStateHandler path[QHSM_MAX_NEST_DEPTH_], uint_fast8_t const qs_id)

Private Attributes
struct QHsmVtable const *	vptr

union QHsmAttr	state

union QHsmAttr	temp

Detailed Description

Hierarchical State Machine class

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 base class for derivation of state machines in the application code.

Traceability:

traces to: RQP103

traces to: AQP211

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
Definition: qep.h:253

Definition at line 253 of file qep.h.

Member Function Documentation

◆ QHsm_init_()

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

private

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

Executes the top-most initial transition in a HSM.

Parameters

[in,out]	me	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)

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

Traceability:

traces to: RQP103

traces to: RQP120I

traces to: RQP120D

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

◆ QHsm_dispatch_()

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

private

Implementation of dispatching events to a QHsm subclass

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 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)

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

Traceability:

traces to: RQP103

traces to: RQP120A

traces to: RQP120B

traces to: RQP120C

traces to: RQP120D

traces to: RQP120E

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

Traceability:: traces to: RQP120E

Traceability:: traces to: RQP120C

Traceability:: traces to: RQP120B

Traceability:: traces to: RQP120I

Definition at line 286 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 605 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 pointer (see oop)

Returns: the current active state of a QHsm class

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

Definition at line 373 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

Parameters

[in]	me	pointer (see oop)
[in]	parent	pointer to the parent state-handler

Returns: the current active child state-handler of a given parent

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

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

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:

traces to: RQP103

traces to: RQP120H

Postcondition: the child must be found

Definition at line 677 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.

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

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

Traceability:

traces to: RQP103

traces to: RQP120S

Precondition: the state configuration must be stable

Definition at line 628 of file qep_hsm.c.

◆ QHsm_ctor()

void QHsm_ctor	(	QHsm *const	me,
		QStateHandler	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	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:196

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

Traceability:: traces to: RQP103

Definition at line 139 of file qep_hsm.c.

◆ QHsm_top()

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

protected

the top-state.

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

Parameters

[in]	me	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:

traces to: RQP103

traces to: RQP120T

Definition at line 261 of file qep_hsm.c.

◆ QHsm_tran_()

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

staticprivate

Static helper function to execute transition sequence in a hierarchical state machine (HSM).

Parameters

[in,out]	me	pointer (see oop)
[in,out]	path	array of pointers to state-handler functions to execute the entry actions
[in]	qs_id	QS-id of this state machine (for QS local filter)

Returns: the depth of the entry path stored in the path parameter.

Traceability:

traces to: RQP103

traces to: RQP120E

traces to: RQP120F

Definition at line 465 of file qep_hsm.c.

Field Documentation

◆ vptr

struct QHsmVtable const* vptr

private

virtual pointer

Traceability:: traces to: RQP102

Definition at line 254 of file qep.h.

◆ state

union QHsmAttr state

private

current active state (state-var)

Definition at line 255 of file qep.h.

◆ temp

union QHsmAttr temp

private

temporary: target/act-table, etc.

Definition at line 256 of file qep.h.

The documentation for this struct 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_init_()

◆ QHsm_dispatch_()

◆ QHsm_getStateHandler_()

◆ QHsm_state()

◆ QHsm_childState()

◆ QHsm_isIn()

◆ QHsm_ctor()

◆ QHsm_top()

◆ QHsm_tran_()

Field Documentation

◆ vptr

◆ state

◆ temp