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

#include <qep.h>

Inheritance diagram for QHsm:
QActive QHsmDummy QMsm QActiveDummy QMActive QTicker QXThread

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;
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]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 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]mepointer (see oop)
[in]epointer to the event to be dispatched to the HSM
[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.
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]mepointer (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]mepointer (see oop)
[in]parentpointer 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]mepointer (see oop)
[in]parentpointer 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]mepointer (see oop)
[in]statepointer 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]mepointer (see oop)
[in]initialpointer 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;
}
#define Q_STATE_CAST(handler_)
Definition: qep.h:196
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]mepointer (see oop)
[in]epointer 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]mepointer (see oop)
[in,out]patharray of pointers to state-handler functions to execute the entry actions
[in]qs_idQS-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: