QHsm Class Reference

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

#include "qp.h"

Inheritance diagram for QHsm:

Public Member Functions
QStateHandler	QHsm_childState (QHsm *const me, QStateHandler const parent)
	Obtain the current active child state of a given parent in QHsm.

Static Public Member Functions
static QStateHandler	QHsm_state (QHsm const *const me)
	Obtain the current active state from a HSM (read only)

Public Attributes
QAsm	super

Protected Member Functions
void	QHsm_ctor (QHsm *const me, QStateHandler const initial)
	Constructor of the QHsm base class.
Protected Member Functions inherited from QAsm
void	QAsm_ctor (QAsm *const me)
	Constructor of the QAsm base class.
QState	QHsm_top (QHsm const *const me, QEvt const *const e)

Private Member Functions
void	QHsm_init_ (QAsm *const me, void const *const e, uint_fast8_t const qsId)
	Implementation of the top-most initial transition in QHsm.
void	QHsm_dispatch_ (QAsm *const me, QEvt const *const e, uint_fast8_t const qsId)
	Implementation of dispatching events to a QHsm.
QStateHandler	QHsm_getStateHandler_ (QAsm *const me)
	Implementation of getting the state handler in a QHsm subclass.
bool	QHsm_isIn_ (QAsm *const me, QStateHandler const state)
	Check if a given state is part of the current active state configuration.
int_fast8_t	QHsm_tran_ (QAsm *const me, QStateHandler *const path, uint_fast8_t const qsId)

Additional Inherited Members
Protected Attributes inherited from QAsm
struct QAsmVtable const *	vptr
	Virtual pointer inherited by all QAsm subclasses (see also Object Orientation)
union QAsmAttr	state
	Current state (pointer to the current state-handler function)
union QAsmAttr	temp
	Temporary storage for target/act-table etc.

Detailed Description

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

Details

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.

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.

Backward Traceability

• SRS_QP_SM_00 : QP/C Framework shall provide support for hierarchical state machines both for Active Objects and for passive event-driven objects in the Application
• SRS_QP_SM_10 : QP/C Framework shall support multiple and interchangeable State Machine Implementation Strategies
• SDS_QP_QEP : QEP Event Processor
• SDS_QP_QHsm : QHsm State machine class.

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;  // <=== inherit QHsm
 
    double operand1;
    double operand2;
    char display[DISP_WIDTH + 1];
    uint8_t len;
    uint8_t opKey;
} Calc;
 
void Calc_ctor(void) {
    QHsm_ctor(&me->super, Q_STATE_CAST(&Calc_initial)); // ctor of the superclass
    . . .
}

Definition at line 292 of file qp.h.

Member Function Documentation

QHsm_ctor()

void QHsm_ctor ( QHsm *const me, QStateHandler const initial )

protected

Constructor of the QHsm base class.

Details

The constructor initializes the QHsm::state. The constructor is "protected" because it is only intended to be invoked from the subclasses of the abstract base class QAsm.

Parameters

[in,out]	me	current instance pointer (see Object Orientation)
[in]	initial	initial pseudostate of the instantiated state machine

Backward Traceability

• QHsm : Hierarchical State Machine class (QHsm-style state machine implementation strategy)

Definition at line 113 of file qep_hsm.c.

QHsm_init_()

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

private

Implementation of the top-most initial transition in QHsm.

Details

Synchronously executes the top-most initial transition in a state machine.

Parameters

[in,out]	me	current instance pointer (see Object Orientation)
[in]	e	pointer to an extra parameter (might be NULL)
[in]	qsId	QS-id of this state machine (for QS local filter)

Precondition qep_msm:200

• the virtual pointer must be initialized,
• the top-most initial transition must be initialized,
• the initial transition must not be taken yet.

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

• QHsm : Hierarchical State Machine class (QHsm-style state machine implementation strategy)

Definition at line 132 of file qep_hsm.c.

QHsm_dispatch_()

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

private

Implementation of dispatching events to a QHsm.

Details

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 Object Orientation)
[in]	e	pointer to the event to be dispatched to the MSM
[in]	qsId	QS-id of this state machine (for QS local filter)

Precondition qep_msm:302

• current state must be initialized
• check the internal integrity (Software Self-Monitoring (SSM))

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

• QHsm : Hierarchical State Machine class (QHsm-style state machine implementation strategy)

Definition at line 257 of file qep_hsm.c.

QHsm_getStateHandler_()

QStateHandler QHsm_getStateHandler_ ( QAsm *const me )

private

Implementation of getting the state handler in a QHsm subclass.

Parameters

[in,out]

me

current instance pointer (see Object Orientation)

Note

This function is only called internally via the virtual table

Definition at line 467 of file qep_hsm.c.

QHsm_isIn_()

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

private

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

Details

Please note that for a HSM, to "be in a state" means also to be in a superstate of of the state.

Parameters

[in]	me	current instance pointer (see Object Orientation)
[in]	state	pointer to the state-handler function to be tested

Returns

'true' if the HSM "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 should be only called only when the state machine is in a "stable state configuration".

Precondition qep_hsm:602

• internal integrity check (Software Self-Monitoring (SSM))

Backward Traceability

• SRS_QP_SM_25 : All State Machine Implementation Strategies provided by QP/C Framework might supply a method for checking if a state machine is in a given state
• QHsm : Hierarchical State Machine class (QHsm-style state machine implementation strategy)

Definition at line 474 of file qep_hsm.c.

QHsm_state()

static QStateHandler QHsm_state ( QHsm const *const me )

inlinestatic

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

Parameters

[in]

me

current instance pointer (see Object Orientation)

Returns

the current active state-handler

Note

This function is used for state history (deep history) in the auto-generated code by the QM modeling tool.

Backward Traceability

• QHsm : Hierarchical State Machine class (QHsm-style state machine implementation strategy)

Definition at line 330 of file qp.h.

QHsm_childState()

QStateHandler QHsm_childState	(	QHsm *const	me,
		QStateHandler const	parent )

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

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 QHsm.

Parameters

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

Returns

the child of a given parent state-handler, 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.

Postcondition qep_msm:890

• the child must be found

Note

This function is used in QM for auto-generating code for state history (shallow history)

Backward Traceability

• QHsm : Hierarchical State Machine class (QHsm-style state machine implementation strategy)

Definition at line 514 of file qep_hsm.c.

QHsm_tran_()

int_fast8_t QHsm_tran_ ( QAsm *const me, QStateHandler *const path, uint_fast8_t const qsId )

private

Definition at line 556 of file qep_hsm.c.

Member Data Documentation

super

QAsm QHsm::super

Definition at line 294 of file qp.h.

---

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

• qp.h
• qep_hsm.c
• qp.dox