QP/C  7.2.2
Real-Time Embedded Framework
Loading...
Searching...
No Matches
QHsm Class Reference

Hierarchical State Machine class. More...

#include "qep.h"

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

Public Member Functions

bool QHsm_isIn (QHsm *const me, QStateHandler const state)
 
QStateHandler QHsm_childState (QHsm *const me, QStateHandler const parent)
 

Static Public Member Functions

static QStateHandler QHsm_state (QHsm *const me)
 

Protected Member Functions

void QHsm_ctor (QHsm *const me, QStateHandler const initial)
 
QState QHsm_top (QHsm const *const me, QEvt const *const e)
 
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)
 

Private Member Functions

QStateHandler QHsm_getStateHandler_ (QHsm *const me)
 
void QHsm_state_entry_ (QHsm *const me, QStateHandler const state, uint_fast8_t const qs_id)
 
bool QHsm_state_exit_ (QHsm *const me, QStateHandler const state, uint_fast8_t const qs_id)
 
int_fast8_t QHsm_tran_ (QHsm *const me, QStateHandler *const path, uint_fast8_t const qs_id)
 

Static Private Member Functions

static QState QHsm_reservedEvt_ (QHsm *const me, QStateHandler const state, enum QReservedSig const sig)
 

Private Attributes

struct QHsmVtable const * vptr
 
union QHsmAttr state
 
union QHsmAttr temp
 

Detailed Description

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 abstract base class for derivation of state machines in the QP application.
Traceability
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;
Hierarchical State Machine class.
Definition: qep.h:353

Definition at line 353 of file qep.h.

Member Function Documentation

◆ 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]mecurrent instance pointer (see oop)
[in]statepointer to the state-handler function to be tested
Returns
'true' if the HSM "is in" the state and 'false' otherwise
Precondition qep_hsm:600
  • the state configuration must be stable
Traceability

Definition at line 107 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]mecurrent instance pointer (see oop)
Returns
the current active state of the QHsm class
Note
This function is used in QM for auto-generating code for state history.

Definition at line 414 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

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]mecurrent instance pointer (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.
Postcondition qep_hsm:890
  • the child must be found
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

Definition at line 133 of file qep_hsm.c.

◆ QHsm_ctor()

void QHsm_ctor ( QHsm *const  me,
QStateHandler const  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]mecurrent instance pointer (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:1050
void QHsm_ctor(QHsm *const me, QStateHandler const initial)
Definition: qep_hsm.c:166
Traceability

Definition at line 166 of file qep_hsm.c.

◆ QHsm_top()

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

The top-state of QHsm.

QHsm_top() is the ultimate root of state hierarchy in all HSMs derived from QHsm.

Parameters
[in]mecurrent instance pointer (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

Definition at line 183 of file qep_hsm.c.

◆ QHsm_init_()

void QHsm_init_ ( QHsm *const  me,
void const *const  e,
uint_fast8_t const  qs_id 
)
protected

Implementation of the top-most initial tran. in QHsm.

Executes the top-most initial transition in a HSM.

Parameters
[in,out]mecurrent instance pointer (see oop)
[in]epointer to an extra parameter (might be NULL)
[in]qs_idQS-id of this state machine (for QS local filter)
Precondition qep_hsm:200
  • the virtual pointer must be initialized,
  • the top-most initial transition must be initialized,
  • the initial transition must not be taken yet.
Note
Must be called only ONCE after the QHsm_ctor().
Traceability

Definition at line 193 of file qep_hsm.c.

◆ QHsm_dispatch_()

void QHsm_dispatch_ ( QHsm *const  me,
QEvt const *const  e,
uint_fast8_t const  qs_id 
)
protected

Implementation of dispatching events to a QHsm

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]mecurrent instance pointer (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)
Precondition qep_hsm:400
  • the current state must be initialized and
  • the state configuration must be stable
Note
This function should be called only via the virtual table (see QHSM_DISPATCH()) and should NOT be called directly in the applications.
Traceability

Definition at line 274 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 425 of file qep_hsm.c.

◆ QHsm_state_entry_()

void QHsm_state_entry_ ( QHsm *const  me,
QStateHandler const  state,
uint_fast8_t const  qs_id 
)
private

Helper function to execute entry into a given state in a hierarchical state machine (HSM).

Parameters
[in]statestate handler function
[in]qs_idQS-id of this state machine (for QS local filter)

Definition at line 567 of file qep_hsm.c.

◆ QHsm_state_exit_()

bool QHsm_state_exit_ ( QHsm *const  me,
QStateHandler const  state,
uint_fast8_t const  qs_id 
)
private

Helper function to execute exit from a given state in a hierarchical state machine (HSM).

Parameters
[in]statestate handler function
[in]qs_idQS-id of this state machine (for QS local filter)
Returns
'true' if the exit action has been found in the state and 'flase' otherwise.

Definition at line 587 of file qep_hsm.c.

◆ QHsm_reservedEvt_()

static QState QHsm_reservedEvt_ ( QHsm *const  me,
QStateHandler const  state,
enum QReservedSig const  sig 
)
inlinestaticprivate

helper function to trigger reserved event in an QHsm

Parameters
[in]statestate handler function
[in]sigreserved signal to trigger

Definition at line 88 of file qep_hsm.c.

◆ QHsm_tran_()

int_fast8_t QHsm_tran_ ( QHsm *const  me,
QStateHandler *const  path,
uint_fast8_t const  qs_id 
)
private

Definition at line 432 of file qep_hsm.c.

Member Data Documentation

◆ vptr

struct QHsmVtable const* vptr
private

Virtual pointer

Traceability

Definition at line 362 of file qep.h.

◆ state

union QHsmAttr state
private

Current active state (state-variable).

Definition at line 369 of file qep.h.

◆ temp

union QHsmAttr temp
private

Temporary: target/act-table, etc.

Definition at line 374 of file qep.h.


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