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

#include <qp.h>

Inheritance diagram for QMsm:

Public Member Functions
QMState const *	QMsm_topQMState (void)
QMState const *	QMsm_stateObj (QMsm const *const me)
	Obtain the current state from a MSM (read only).
QMState const *	QMsm_childStateObj (QMsm const const me, QMState const const parentHndl)
	Obtain the current active child state of a given parent in QMsm.

Protected Member Functions
void	QMsm_ctor (QMsm *const me, QStateHandler const initial)
	Constructor of QMsm.

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	QMsm_init_ (QAsm const me, void const const e, uint_fast8_t const qsId)
	Implementation of the top-most initial transition in QMsm.
void	QMsm_dispatch_ (QAsm const me, QEvt const const e, uint_fast8_t const qsId)
	Implementation of dispatching events to a QMsm.
bool	QMsm_isIn_ (QAsm *const me, QStateHandler const stateHndl)
	Tests if a given state is part of the current active state configuration.
QStateHandler	QMsm_getStateHandler_ (QAsm const *const me)
	Implementation of getting the state handler in an QMsm subclass.

Static Private Member Functions
static QState	QMsm_execTatbl_ (QAsm const me, QMTranActTable const const tatbl, uint_fast8_t const qsId)
	Execute a transition-action table in QMsm.
static void	QMsm_exitToTranSource_ (QAsm const me, QMState const const curr_state, QMState const *const tran_source, uint_fast8_t const qsId)
	Exit the given current-state up to the given tran-source in QMsm.
static QState	QMsm_enterHistory_ (QAsm const me, QMState const const hist, uint_fast8_t const qsId)
	Enter the history of a given state in QMsm.

Detailed Description

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

Details
QMsm (QM State Machine) provides a more efficient state machine implementation strategy than QHsm, but requires the use of the QM modeling tool. They are the fastest and need the least run-time support (the smallest event-processor taking up the least code space).

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

Usage
The following example illustrates how to derive a state machine class from QMsm. Please note that the QMsm member super is defined as the first member of the derived struct. Also, note that the derived class constructor calls the constructor of the base class QMsm_ctor().

typedef struct {
    QMsm super; // <=== inherit QMsm
 
// private state histories
    QStateHandler hist_doorClosed;
    QStateHandler hist_heating;
} ToasterOven;
 
void ToasterOven_ctor(ToastOven * const me) {
    QMsm_ctor(&me->super, Q_STATE_CAST(&ToasterOven_initial));
    . . .
}

Backward Traceability

SDS_QP_QMsm: QMsm State machine class.

Forward Traceability

Definition at line 315 of file qp.h.

Member Function Documentation

◆ QMsm_ctor()

void QMsm_ctor	(	QMsm *const	me,
		QStateHandler const	initial )

protected

Constructor of QMsm.

Details
Performs the first step of QMsm initialization by assigning the initial pseudostate to the currently active state of the state machine.

Parameters

[in,out]	me	current instance pointer (see SAS_QP_OOA)
[in]	initial	the top-most initial transition for the MSM.

Note: Must be called only ONCE before QASM_INIT().

Usage
The following example illustrates how to invoke QMsm_ctor() in the "constructor" of a derived state machine:

void Calc_ctor(Calc const me) {
    // call superclass' ctor
    QMsm_ctor(&me->super, Q_STATE_CAST(&Calc_initial));
 
    me->operand1 = 0.0;
    me->operand2 = 0.0;
    me->len      = 0U;
    me->opKey    = 0U;
}

Forward Traceability

Definition at line 140 of file qep_msm.c.

◆ QMsm_init_()

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

private

Implementation of the top-most initial transition in QMsm.

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

Definition at line 157 of file qep_msm.c.

◆ QMsm_dispatch_()

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

private

Implementation of dispatching events to a QMsm.

Details
This function 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_QMsm_dispatch: QMsm Event Dispatching

Forward Traceability

Definition at line 203 of file qep_msm.c.

◆ QMsm_isIn_()

bool QMsm_isIn_	(	QAsm *const	me,
		QStateHandler const	state )

private

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

Details
Please note that for an MSM, 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]	state	pointer to the state-handler function to be tested

Returns: 'true' if the MSM "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 must be called only on a state machine that is in the "stable state configuration". Among others, this means that the state machine cannot call it in the middle of its transition.

Forward Traceability

DVR_QP_MC5_R8_13: MISRA-C:2025 Rule 8.13(Advisory): A pointer should point to a const-qualified type whenever possible

Definition at line 428 of file qep_msm.c.

◆ QMsm_getStateHandler_()

QStateHandler QMsm_getStateHandler_ ( QAsm const *const me )

private

Implementation of getting the state handler in an QMsm 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 476 of file qep_msm.c.

◆ QMsm_topQMState()

QMState const * QMsm_topQMState ( void )

Definition at line 422 of file qep_msm.c.

◆ QMsm_stateObj()

QMState const * QMsm_stateObj ( QMsm const *const me )

Obtain the current state from a MSM (read only).

Parameters

[in] me current instance pointer (see SAS_QP_OOA)

Returns: the current state object

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

Forward Traceability

Definition at line 470 of file qep_msm.c.

◆ QMsm_childStateObj()

QMState const * QMsm_childStateObj	(	QMsm const *const	me,
		QMState const *const	parent )

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

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

Parameters

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

Returns: The child of a given parent state, 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 the QM modeling tool for auto-generating code for state history (shallow history)

Definition at line 444 of file qep_msm.c.

◆ QMsm_execTatbl_()

QState QMsm_execTatbl_	(	QAsm *const	me,
		QMTranActTable const *const	tatbl,
		uint_fast8_t const	qsId )

staticprivate

Execute a transition-action table in QMsm.

Execute transition-action table.

Details
This helper function executes the provided transition-action table calling each action in the table until the NULL pointer (the end of the table) is reached.

Parameters

[in,out]	me	current instance pointer (see SAS_QP_OOA)
[in]	tatbl	transition-action table to execute
[in]	qsId	QS-id of this state machine (for QS local filter)

Returns: The status of the last invoked action in the table. If this status is Q_RET_TRAN_INIT, the function is called again to enter the transition-action table associated with that nested initial transition

Note: This function is for internal use only and should be called exclusively from QMsm::QMsm_init_() and QMsm::QMsm_dispatch_().

Backward Traceability

SDS_QP_QMsm_dispatch: QMsm Event Dispatching

Forward Traceability

Details
Helper function to execute transition sequence in a transition-action table.

Parameters

[in,out]	me	current instance pointer (see SAS_QP_OOA)
[in]	tatbl	pointer to the transition-action table
[in]	qsId	QS-id of this state machine (for QS local filter)

Returns: status of the last action from the transition-action table.

Note: This function is for internal use inside the QEP event processor and should **not* be called directly from the applications.

Definition at line 305 of file qep_msm.c.

◆ QMsm_exitToTranSource_()

void QMsm_exitToTranSource_	(	QAsm *const	me,
		QMState const *const	curr_state,
		QMState const *const	tran_source,
		uint_fast8_t const	qsId )

staticprivate

Exit the given current-state up to the given tran-source in QMsm.

Details
This helper function scans the state hierarchy (by following the state.superstate links) and calls the exit action for each state object, starting with the current-state and ending at the tran-source state.

Parameters

[in,out]	me	current instance pointer (see SAS_QP_OOA)
[in]	curr_state	pointer to the current state object
[in]	tran_source	pointer to the transition source object
[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 QMsm::QMsm_dispatch_().

Backward Traceability

SDS_QP_QMsm_dispatch: QMsm Event Dispatching

Forward Traceability

Definition at line 348 of file qep_msm.c.

◆ QMsm_enterHistory_()

QState QMsm_enterHistory_	(	QAsm *const	me,
		QMState const *const	hist,
		uint_fast8_t const	qsId )

staticprivate

Enter the history of a given state in QMsm.

Enter history of a composite state.

Details
This helper function dynamically enters the given history state, which is the substate of me->state.obj.

Parameters

[in,out]	me	current instance pointer (see SAS_QP_OOA)
[in]	hist	pointer to the history state to be entered
[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 QMsm::QMsm_dispatch_().

Backward Traceability

SDS_QP_QMsm_dispatch: QMsm Event Dispatching

Forward Traceability

Details
Static helper function to execute the segment of transition to history after entering the composite state and

Parameters

[in,out]	me	current instance pointer (see SAS_QP_OOA)
[in]	hist	pointer to the history substate
[in]	qsId	QS-id of this state machine (for QS local filter)

Returns: Q_RET_TRAN_INIT, if an initial transition has been executed in the last entered state or 0 (Q_RET_SUPER) if no such transition was taken.

Forward Traceability

Definition at line 376 of file qep_msm.c.

Member Data Documentation

◆ super

QAsm super

protected

Definition at line 316 of file qp.h.

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


QP/C 8.1.3 Real-Time Event Framework

Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Static Private Member Functions

Detailed Description

Member Function Documentation

◆ QMsm_ctor()

◆ QMsm_init_()

◆ QMsm_dispatch_()

◆ QMsm_isIn_()

◆ QMsm_getStateHandler_()

◆ QMsm_topQMState()

◆ QMsm_stateObj()

◆ QMsm_childStateObj()

◆ QMsm_execTatbl_()

◆ QMsm_exitToTranSource_()

◆ QMsm_enterHistory_()

Member Data Documentation

◆ super