QP/C  7.0.0
Real-Time Embedded Framework
QMsm Struct Reference

#include <qep.h>

Inheritance diagram for QMsm:
QHsm

Public Member Functions

QMState const * QMsm_childStateObj (QHsm const *const me, QMState const *const parent)
 
bool QMsm_isInState (QMsm const *const me, QMState const *const state)
 
- Public Member Functions inherited from QHsm
QStateHandler QHsm_childState (QHsm *const me, QStateHandler const parent)
 
bool QHsm_isIn (QHsm *const me, QStateHandler const state)
 

Static Public Member Functions

static QMState const * QMsm_stateObj (QHsm *const me)
 
- Static Public Member Functions inherited from QHsm
static QStateHandler QHsm_state (QHsm *const me)
 

Protected Member Functions

void QMsm_ctor (QMsm *const me, QStateHandler initial)
 
- Protected Member Functions inherited from QHsm
void QHsm_ctor (QHsm *const me, QStateHandler initial)
 
QState QHsm_top (void const *const me, QEvt const *const e)
 

Protected Attributes

QHsm super
 

Private Member Functions

void QMsm_init_ (QHsm *const me, void const *const e, uint_fast8_t const qs_id)
 
void QMsm_dispatch_ (QHsm *const me, QEvt const *const e, uint_fast8_t const qs_id)
 
QStateHandler QMsm_getStateHandler_ (QHsm *const me)
 

Static Private Member Functions

static QState QMsm_execTatbl_ (QHsm *const me, struct QMTranActTable const *tatbl, uint_fast8_t const qs_id)
 
static void QMsm_exitToTranSource_ (QHsm *const me, QMState const *cs, QMState const *ts, uint_fast8_t const qs_id)
 
static QState QMsm_enterHistory_ (QHsm *const me, QMState const *const hist, uint_fast8_t const qs_id)
 

Detailed Description

QM State Machine implementation strategy

QMsm (QM State Machine) provides a more efficient state machine implementation strategy than QHsm, but requires the use of the QM modeling tool, but 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 base class for derivation of state machines in the application code.
Traceability:
traces to: RQP104
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.
typedef struct {
QMsm super; /* inherits QMsm */
double operand1;
double operand2;
char display[DISP_WIDTH + 1];
uint8_t len;
uint8_t opKey;
} Calc;
Definition: qep.h:425
QHsm super
Definition: qep.h:426

Definition at line 425 of file qep.h.

Member Function Documentation

◆ QMsm_stateObj()

static QMState const * QMsm_stateObj ( QHsm *const  me)
inlinestatic

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

Parameters
[in]mepointer (see oop)
Returns
the current active state-object
Note
this function is used in QM for auto-generating code for state history

Definition at line 464 of file qep.h.

◆ QMsm_childStateObj()

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

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

Parameters
[in]mepointer (see oop)
[in]parentpointer to the parent state-object
Returns
the current active child state-object 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 QMsm.

Parameters
[in]mepointer (see oop)
[in]parentpointer 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, function returns the parent state.
See also
QMsm_childStateObj()
Postcondition
the child must be found

Definition at line 657 of file qep_msm.c.

◆ QMsm_isInState()

bool QMsm_isInState ( QMsm const *const  me,
QMState const *const  state 
)

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

Tests if a state machine derived from QMsm is-in a given state.

Note
For a MSM, to "be-in" a state means also to "be-in" a superstate of of the state.
Parameters
[in]mepointer (see oop)
[in]statepointer to the QMState object that corresponds to the tested state.
Returns
'true' if the MSM "is in" the state and 'false' otherwise

Definition at line 623 of file qep_msm.c.

◆ QMsm_ctor()

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

Constructor of QMsm

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

Parameters
[in,out]mepointer (see oop)
[in]initialthe top-most initial transition for the MSM.
Note
Must be called only ONCE before QHSM_INIT().
QMsm inherits QHsm, so by the oop convention it should call the constructor of the superclass, i.e., QHsm_ctor(). However, this would pull in the QHsmVtable, which in turn will pull in the code for QHsm_init_() and QHsm_dispatch_() implemetations. To avoid this code size penalty, in case QHsm is not used in a given project, the QMsm_ctor() performs direct intitialization of the Vtable, which avoids pulling in the code for QMsm.
Usage
The following example illustrates how to invoke QMsm_ctor() in the "constructor" of a derived state machine:
void Calc_ctor(Calc * const me) {
/* 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;
}
#define Q_STATE_CAST(handler_)
Definition: qep.h:196
void QMsm_ctor(QMsm *const me, QStateHandler initial)
Definition: qep_msm.c:114

Definition at line 114 of file qep_msm.c.

◆ QMsm_init_()

void QMsm_init_ ( QHsm *const  me,
void const *const  e,
uint_fast8_t const  qs_id 
)
private

Implementation of the top-most initial transition in QMsm

Executes the top-most initial transition in a MSM.

Parameters
[in,out]mepointer (see oop)
[in]epointer to an extra parameter (might be NULL)
[in]qs_idQS-id of this state machine (for QS local filter)
Note
Must be called only ONCE after the QMsm_ctor().
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 142 of file qep_msm.c.

◆ QMsm_dispatch_()

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

Implementation of disparching events to QMsm

Dispatches an event for processing to a meta state machine (MSM). The processing of an event represents one run-to-completion (RTC) step.

Parameters
[in,out]mepointer (see oop)
[in]epointer to the event to be dispatched to the MSM
[in]qs_idQS-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.
Precondition
current state must be initialized

Definition at line 206 of file qep_msm.c.

◆ QMsm_getStateHandler_()

QStateHandler QMsm_getStateHandler_ ( QHsm *const  me)
private

Implementation of getting the state handler in a QMsm

Definition at line 397 of file qep_msm.c.

◆ QMsm_execTatbl_()

static QState QMsm_execTatbl_ ( QHsm *const  me,
struct QMTranActTable const *  tatbl,
uint_fast8_t const  qs_id 
)
staticprivate

helper function to execute a transition-action table.

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

Parameters
[in,out]mepointer (see oop)
[in]tatblpointer to the transition-action table
[in]qs_idQS-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.
Precondition
the transition-action table pointer must not be NULL

Definition at line 420 of file qep_msm.c.

◆ QMsm_exitToTranSource_()

static void QMsm_exitToTranSource_ ( QHsm *const  me,
QMState const *  cs,
QMState const *  ts,
uint_fast8_t const  qs_id 
)
staticprivate

helper function to exit the current state up to the transition source

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]mepointer (see oop)
[in]cspointer to the current state
[in]tspointer to the transition source state
[in]qs_idQS-id of this state machine (for QS local filter)

Definition at line 504 of file qep_msm.c.

◆ QMsm_enterHistory_()

static QState QMsm_enterHistory_ ( QHsm *const  me,
QMState const *const  hist,
uint_fast8_t const  qs_id 
)
staticprivate

helper function to execute a transition to history

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

Parameters
[in,out]mepointer (see oop)
[in]histpointer to the history substate
[in]qs_idQS-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 Q_RET_NULL if no such transition was taken.

Definition at line 553 of file qep_msm.c.

Field Documentation

◆ super

QHsm super
protected

inherits QHsm

Definition at line 426 of file qep.h.


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