Hierarchical State Machine class (QHsm-style state machine implementation strategy). More...

#include <qp.h>

Inheritance diagram for QHsm:

Public Member Functions
QStateHandler	QHsm_state (QHsm const *const me)
	Obtain the current active state from a HSM (read only).
QStateHandler	QHsm_childState (QHsm *const me, QStateHandler const parentHndl)
	Obtain the current active child state of a given parent in QHsm.

Protected Member Functions
void	QHsm_ctor (QHsm *const me, QStateHandler const initial)
	Constructor of the QHsm base class.
QState	QHsm_top (QHsm const const me, QEvt const const e)

Protected Attributes
QAsm	super
Protected Attributes inherited from QAsm
struct QAsmVtable const *	vptr
	Virtual pointer inherited by all QAsm subclasses (see also SAS_QP_OOA).
union QAsmAttr	state
	Current state (pointer to the current state-handler function).
union QAsmAttr	temp
	Temporary storage for target/act-table etc..

Private Member Functions
void	QHsm_init_ (QAsm const me, void const const e, uint_fast8_t const qsId)
	Implementation of the top-most initial transition in QHsm.
void	QHsm_dispatch_ (QAsm const me, QEvt const const e, uint_fast8_t const qsId)
	Implementation of dispatching events to a QHsm.
bool	QHsm_isIn_ (QAsm *const me, QStateHandler const stateHndl)
	Check if a given state is part of the current active state configuration.
QStateHandler	QHsm_getStateHandler_ (QAsm const *const me)
	Implementation of getting the state handler in an QHsm subclass.
size_t	QHsm_tran_simple_ (QAsm const me, QStateHandler const path, uint_fast8_t const qsId)
	Implementation of a simple state transition segment.
size_t	QHsm_tran_complex_ (QAsm const me, QStateHandler const path, uint_fast8_t const qsId)
	Implementation of a complex state transition segment.
void	QHsm_enter_target_ (QAsm const me, QStateHandler const path, size_t const depth, uint_fast8_t const qsId)
	Implementation of entry to the target state configuration.

Detailed Description

Hierarchical State Machine class (QHsm-style state machine implementation strategy).

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

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/C Application.

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;  // <=== inherit QHsm
 
    double operand1;
    double operand2;
    char display[DISP_WIDTH + 1];
    uint8_t len;
    uint8_t opKey;
} Calc;
 
void Calc_ctor(void) {
    QHsm_ctor(&me->super, Q_STATE_CAST(&Calc_initial)); // ctor of the superclass
    . . .
}

Backward Traceability

SDS_QP_QHsm: Design view: QHsm State machine class.

Forward Traceability

Definition at line 244 of file qp.h.

Member Function Documentation

◆ QHsm_ctor()

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

protected

Constructor of the QHsm base class.

Details
The constructor initializes the QHsm::state. The constructor is "protected" because it is only intended to be invoked from the subclasses of the abstract base class QAsm.

Parameters

[in,out]	me	current instance pointer (see SAS_QP_OOA)
[in]	initial	initial pseudostate of the instantiated state machine

Forward Traceability

Definition at line 139 of file qep_hsm.c.

◆ QHsm_init_()

void QHsm_init_	(	QAsm *const	me,
		void const *const	e,
		uint_fast8_t const	qsId )

private

Implementation of the top-most initial transition in QHsm.

Details
Synchronously executes the top-most initial transition in a state machine.

Parameters

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

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

Forward Traceability

Definition at line 165 of file qep_hsm.c.

◆ QHsm_dispatch_()

void QHsm_dispatch_	(	QAsm *const	me,
		QEvt const *const	e,
		uint_fast8_t const	qsId )

private

Implementation of dispatching events to a QHsm.

Details
Synchronously dispatches an event for processing to a state machine. The processing of an event represents one run-to-completion (RTC) step.

Parameters

[in,out]	me	current instance pointer (see SAS_QP_OOA)
[in]	e	pointer to the event to be dispatched to the MSM
[in]	qsId	QS-id of this state machine (for QS local filter)

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

Backward Traceability

SDS_QP_QHsm_dispatch: Design view: QHsm event dispatching

Forward Traceability

Definition at line 241 of file qep_hsm.c.

◆ QHsm_isIn_()

bool QHsm_isIn_	(	QAsm *const	me,
		QStateHandler const	stateHndl )

private

Check if a given state is part of the current active state configuration.

Details
Please note that for an HSM, to "be in a state" means also to be in a superstate of the state.

Parameters

[in]	me	current instance pointer (see SAS_QP_OOA)
[in]	stateHndl	pointer to the state-handler function to be tested

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

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

Attention: This function should be called only when the state machine is in a "stable state configuration". Among others, this means that the state machine cannot call it in the middle of its own transition.

Forward Traceability

Definition at line 567 of file qep_hsm.c.

◆ QHsm_getStateHandler_()

QStateHandler QHsm_getStateHandler_ ( QAsm const *const me )

private

Implementation of getting the state handler in an QHsm subclass.

Parameters

[in,out] me current instance pointer (see SAS_QP_OOA)

Note: This function is only called internally via the virtual table

Definition at line 642 of file qep_hsm.c.

◆ QHsm_top()

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

protected

Definition at line 156 of file qep_hsm.c.

◆ QHsm_state()

QStateHandler QHsm_state ( QHsm const *const me )

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

Parameters

[in] me current instance pointer (see SAS_QP_OOA)

Returns: the current active state-handler

Note: This function is used for state history (deep history) in the auto-generated code by the QM modeling tool.

Forward Traceability

Definition at line 634 of file qep_hsm.c.

◆ QHsm_childState()

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

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

Details
Finds the child state of the given parent, such that this child state is an ancestor of the currently active state. The primary purpose of this function is to support **shallow history*transitions in state machines derived from QHsm.

Parameters

[in]	me	current instance pointer (see SAS_QP_OOA)
[in]	parent	pointer to the state-handler

Returns: The child of a given parent state-handler, which is an ancestor of the currently active state. For the corner case when the currently active state is the given parent state, the function returns the parent state.

Note: This function is used in QM for auto-generating code for state history (shallow history)

Forward Traceability

Definition at line 600 of file qep_hsm.c.

◆ QHsm_tran_simple_()

size_t QHsm_tran_simple_	(	QAsm *const	me,
		QStateHandler *const	path,
		uint_fast8_t const	qsId )

private

Implementation of a simple state transition segment.

Details
Determines the type of a simple transition (A-D, see Figure SDS-SM-STRAN). If the simple transition type is found, the function exits the source states to the LCA, otherwise the function returns 2.

Parameters

[in,out]	me	current instance pointer (see SAS_QP_OOA)
[in,out]	path	array containing the target state-handler in path[0], and source state-handler in path[2]. Upon return, path[] contains the sequence of state handlers to be entered in QHsm::QHsm_enter_target_()
[in]	qsId	QS-id of this state machine (for QS local filter)

Returns: the number of state nesting levels of the path[] array to be entered in QHsm::QHsm_enter_target_(). Return value > 1 indicates higher complexity transition and the need to call QHsm_tran_complex_().

Note: This function is for internal use only and should be called exclusively from QHsm::QHsm_dispatch_().

Backward Traceability

SDS_QP_QHsm_dispatch: Design view: QHsm event dispatching

Forward Traceability

Definition at line 344 of file qep_hsm.c.

◆ QHsm_tran_complex_()

size_t QHsm_tran_complex_	(	QAsm *const	me,
		QStateHandler *const	path,
		uint_fast8_t const	qsId )

private

Implementation of a complex state transition segment.

Details
Determines the type of a complex transition (E-H, see Figure SDS-SM-CTRAN). Next, the function exits the source states to the LCA.

Parameters

[in,out]	me	current instance pointer (see SAS_QP_OOA)
[in,out]	path	array containing the target state-handler in path[0], and source state-handler in path[2]. Upon return, path[] contains the sequence of state handlers to be entered in QHsm::QHsm_enter_target_()
[in]	qsId	QS-id of this state machine (for QS local filter)

Returns: the number of state nesting levels of the path[] array to be entered in QHsm::QHsm_enter_target_().

Note: This function is for internal use only and should be called exclusively from QHsm::QHsm_dispatch_().

Backward Traceability

SDS_QP_QHsm_dispatch: Design view: QHsm event dispatching

Forward Traceability

Definition at line 412 of file qep_hsm.c.

◆ QHsm_enter_target_()

void QHsm_enter_target_	(	QAsm *const	me,
		QStateHandler *const	path,
		size_t const	depth,
		uint_fast8_t const	qsId )

private

Implementation of entry to the target state configuration.

Details
This function performs entry to the target state configuration by following the nested initial transition. This process can be recursive, which the function implements by iteration.

Parameters

[in,out]	me	current instance pointer (see SAS_QP_OOA)
[in,out]	path[]	contains the sequence of state handlers to be entered. It is also reused for entry-path for initial transition.
[in]	depth	the initial number of nesting levels in the path[] array.
[in]	qsId	QS-id of this state machine (for QS local filter)

Note: This function is for internal use only and should be called exclusively from QHsm::QHsm_init_() and QHsm::QHsm_dispatch_().

Backward Traceability

SDS_QP_QHsm_dispatch: Design view: QHsm event dispatching

Forward Traceability

Definition at line 501 of file qep_hsm.c.

Member Data Documentation

◆ super

QAsm super

protected

Definition at line 245 of file qp.h.

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


QP/C 8.1.4 Real-Time Event Framework

Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Detailed Description

Member Function Documentation

◆ QHsm_ctor()

◆ QHsm_init_()

◆ QHsm_dispatch_()

◆ QHsm_isIn_()

◆ QHsm_getStateHandler_()

◆ QHsm_top()

◆ QHsm_state()

◆ QHsm_childState()

◆ QHsm_tran_simple_()

◆ QHsm_tran_complex_()

◆ QHsm_enter_target_()

Member Data Documentation

◆ super