Reference Manual For QP/C 8.1.6
Loading...
Searching...
No Matches
QMsm Class Reference

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

Inheritance diagram for QMsm:
QAsm

Public Member Functions

QMState const * QMsm_topQMState (void)
 return top-most state object in a QMsm
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_TECH_20]) .
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 transition-action table.
static void QMsm_exitToTranSource_ (QAsm *const me, QMState const *const curr_state, QMState const *const tran_source, uint_fast8_t const qsId)
 Exit the current state up to the explicit transition source.
static QState QMsm_enterHistory_ (QAsm *const me, QMState const *const hist, uint_fast8_t const qsId)
 Enter the state history in QMsm state machine.

Detailed Description

Hierarchical State Machine class (QMsm-style 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));
. . .
}
#define Q_STATE_CAST(handler_)
Perform cast to QStateHandler.
Definition qp.h:172
QState(*) QStateHandler(void *const me, QEvt const *const e)
Pointer to a state-handler function \clearpage .
Definition qp.h:142
Hierarchical State Machine class (QMsm-style implementation strategy).
Definition qp.h:313
void QMsm_ctor(QMsm *const me, QStateHandler const initial)
Constructor of QMsm.
Definition qep_msm.c:137

Backward Traceability

  • [SDS_QP_QMsm] Design view: QMsm State machine class.
  • [SRS_QP_REQ_221] QP/C Framework should provide a State Machine Implementation Strategy optimized for "automatic code generation"

Forward Traceability

  • [TUN_QP_qep_msm] Unit test for qep_msm module: QMsm-based state machine implementation.

Definition at line 313 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]meinstance pointer (see [SAS_QP_TECH_20])
[in]initialthe 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

  • [TUN_QP_qep_msm] Unit test for qep_msm module: QMsm-based state machine implementation.

Definition at line 137 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]meinstance pointer (see [SAS_QP_TECH_20])
[in]epointer to an extra parameter (might be NULL)
[in]qsIdQS-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.

Backward Traceability

  • [SRS_QP_REQ_238] All State Machine Implementation Strategies provided by the QP/C Framework shall support top-most initial transition that shall be explicitly triggered independently from instantiation of the state machine object.
  • [QAsmVtable] Virtual table for the QAsm class

Forward Traceability

  • [TUN_QP_qep_msm] Unit test for qep_msm module: QMsm-based state machine implementation.

Definition at line 154 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]meinstance pointer (see [SAS_QP_TECH_20])
[in]epointer to the event to be dispatched to the MSM
[in]qsIdQS-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

  • [SRS_QP_REQ_221] QP/C Framework should provide a State Machine Implementation Strategy optimized for "automatic code generation"
  • [SRS_QP_REQ_230] All State Machine Implementation Strategies provided by QP/C Framework shall support hierarchical state machines with features specified in the sub-requirements SRS_QP_REQ_23x
  • [SRS_QP_REQ_231] All State Machine Implementation Strategies provided by QP/C Framework shall support states capable of holding hierarchically nested substates
  • [SRS_QP_REQ_232] All State Machine Implementation Strategies provided by QP/C Framework shall support entry actions to states
  • [SRS_QP_REQ_233] All State Machine Implementation Strategies provided by QP/C Framework shall support exit actions from states
  • [SRS_QP_REQ_234] All State Machine Implementation Strategies provided by QP/C Framework shall support nested initial transitions in composite states
  • [SRS_QP_REQ_235] All State Machine Implementation Strategies provided by QP/C Framework shall support transitions between states at any supported level of nesting
  • [SRS_QP_REQ_236] All State Machine Implementation Strategies provided by QP/C Framework shall support internal transitions in states
  • [SRS_QP_REQ_237] All State Machine Implementation Strategies provided by QP/C Framework shall support guard conditions to be attached to regular and internal transitions
  • [SRS_QP_REQ_239] All State Machine Implementation Strategies provided by QP/C Framework should support transitions to history. Both shallow and deep histories shall be supported.
  • [SRS_QP_REQ_241] All State Machine Implementation Strategies provided by QP/C Framework shall support state nesting up to 5 levels below the top state.
  • [SSRS_QP_SREQ_301] QP/C software component shall apply the fixed upper loop bound to all internal loops that are intended to terminate.
  • [SDS_QP_ALG_QMsm_dispatch] Design view: QMsm Event Dispatching
  • [QAsmVtable] Virtual table for the QAsm class

Forward Traceability

  • [TUN_QP_qep_msm] Unit test for qep_msm module: QMsm-based state machine implementation.

Definition at line 200 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]meinstance pointer (see [SAS_QP_TECH_20])
[in]statepointer to the state-handler function to be tested
Return values
trueIf the MSM "is in" the state
falseOtherwise
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 a stable state configuration, that is, after its top-most initial transition and between its RTC steps. The function verifies this at its start (Duplicate Inverse Storage of the current state) by a Safety Function: the assertion 700 fires if the function is called on a state machine that has not been initialized yet, or from within the state machine's own RTC step, including from its guard conditions, actions, entry/exit actions, and initial transitions. Consequently, a state machine must never query its own state with the "is-in" query (see SSM_QP_ASR_418).

Backward Traceability

  • [SRS_QP_REQ_225] All State Machine Implementation Strategies provided by the QP/C Framework might supply a method for checking if a state machine is in a given state.
  • [QAsmVtable] Virtual table for the QAsm class

Forward Traceability

  • [MISRA_QP_DVR_MC5_R8_13] MISRA-C:2025 Rule 8.13(Advisory): A pointer should point to a const-qualified type whenever possible
  • [TUN_QP_qep_msm] Unit test for qep_msm module: QMsm-based state machine implementation.

Definition at line 424 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]meinstance pointer (see [SAS_QP_TECH_20])
Note
This function is only called internally via the virtual table

Backward Traceability

Forward Traceability

  • [TUN_QP_qep_msm] Unit test for qep_msm module: QMsm-based state machine implementation.

Definition at line 484 of file qep_msm.c.

◆ QMsm_topQMState()

QMState const * QMsm_topQMState ( void )

return top-most state object in a QMsm

Details

The top-state-object is the ultimate root of state hierarchy in QMsm state machines.

Note
The top state object is not linked as the superstate of the top-level states (their superstate pointer is NULL). The top state object can be used as the parent argument of QMsm_childStateObj() (to obtain the active top-level state) and for comparison with QMsm_stateObj() (e.g., to check that the top-most initial transition has not been taken yet).
Return values
pointerPointer to the top-state object in QMsm.

Backward Traceability

  • [SRS_QP_REQ_240] State Machine Implementation Strategies provided by QP/C Framework might supply the top-state

Forward Traceability

  • [TUN_QP_qep_msm] Unit test for qep_msm module: QMsm-based state machine implementation.

Definition at line 418 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]meinstance pointer (see [SAS_QP_TECH_20])
Return values
statePointer to current state object
Note
This function is used in QM for auto-generating code for state history (deep history)

Backward Traceability

  • [SRS_QP_REQ_226] All State Machine Implementation Strategies provided by the QP/C Framework might supply a method for obtaining the current state.

Forward Traceability

  • [TUN_QP_qep_msm] Unit test for qep_msm module: QMsm-based state machine implementation.

Definition at line 478 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]meinstance pointer (see [SAS_QP_TECH_20])
[in]parentpointer to the state-handler object
Return values
childPointer to the child state object of a given parent state, which is an ancestor of the currently active state.
parentFor the corner case when the currently active state is the given parent state, the function returns the parent state.
Note
The parent can also be the top state object returned from QMsm_topQMState(). In that case the function returns the top-level state (a state without a superstate) that contains the currently active state.
This function is used in the QM modeling tool for auto-generating code for state history (shallow history)

Backward Traceability

  • [SRS_QP_REQ_226] All State Machine Implementation Strategies provided by the QP/C Framework might supply a method for obtaining the current state.

Forward Traceability

  • [TUN_QP_qep_msm] Unit test for qep_msm module: QMsm-based state machine implementation.

Definition at line 445 of file qep_msm.c.

◆ QMsm_execTatbl_()

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

Execute transition-action table.

Details

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

Parameters
[in,out]meinstance pointer (see [SAS_QP_TECH_20])
[in]tatblpointer to the transition-action table
[in]qsIdQS-id of this state machine (for QS local filter)
Return values
statusStatus 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.

Forward Traceability

  • [TUN_QP_qep_msm] Unit test for qep_msm module: QMsm-based state machine implementation.

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

Exit the current state up to the explicit transition source.

Details

Static helper function to exit the current state configuration to the transition source, which in a hierarchical state machine might be a superstate of the current state.

Parameters
[in,out]meinstance pointer (see [SAS_QP_TECH_20])
[in]curr_statepointer to the current state
[in]tran_sourcepointer to the transition source state
[in]qsIdQS-id of this state machine (for QS local filter)

Forward Traceability

  • [TUN_QP_qep_msm] Unit test for qep_msm module: QMsm-based state machine implementation.

Definition at line 344 of file qep_msm.c.

◆ QMsm_enterHistory_()

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

Enter the state history in QMsm state machine.

Details

Static helper function to dynamically enter the provided state object provided in the history parameter. Please note that because the history state is not fixed, the transition must be dynamic (determined on-the-fly) as opposed to pre-computed statically as a tran-action table.

Parameters
[in,out]meinstance pointer (see [SAS_QP_TECH_20])
[in]histpointer to the history (state object) to be entered
[in]qsIdQS-id of this state machine (for QS local filter)
Return values
Q_RET_TRAN_INITIf an initial transition has been executed in the history state
Q_RET_SUPERIf the history state has no initial transition

Forward Traceability

  • [TUN_QP_qep_msm] Unit test for qep_msm module: QMsm-based state machine implementation.

Definition at line 372 of file qep_msm.c.

Member Data Documentation

◆ super

QAsm super
protected

Definition at line 314 of file qp.h.