Public QEP/C interface. More...

This graph shows which files directly or indirectly include this file:

Data Structures
struct	QEvt
	Event structure. More...

union	QHsmAttr
	Attribute of for the QHsm class (Hierarchical State Machine). More...

struct	QHsm

struct	QMsmVtbl
	Virtual table for the QHsm class. More...

struct	QMState
	State object for the QMsm class (QM State Machine). More...

struct	QMTranActTable
	Transition-Action Table for the Meta State Machine. More...

Macros
#define	QP_VERSION 640U
	The current QP version as a decimal constant XYZ, where X is a 1-digit major version number, Y is a 1-digit minor version number, and Z is a 1-digit release number. More...

#define	QP_VERSION_STR "6.4.0"
	The current QP version number string of the form X.Y.Z, where X is a 1-digit major version number, Y is a 1-digit minor version number, and Z is a 1-digit release number. More...

#define	QP_RELEASE 0x8EA03F5FU
	Tamperproof current QP release (6.4.0) and date (2019-02-10) More...

#define	QEP_getVersion() (QP_versionStr)
	get the current QEP version number string of the form "X.Y.Z" More...

#define	Q_SIGNAL_SIZE 2
	The size (in bytes) of the signal of an event. More...

#define	Q_HSM_UPCAST(ptr_) ((QHsm *)(ptr_))
	Perform upcast from a subclass of QHsm to the base class QHsm. More...

#define	Q_EVT_CAST(class_) ((class_ const *)e)
	Perform downcast of an event onto a subclass of QEvt `class_`. More...

#define	Q_UINT2PTR_CAST(type_, uint_) ((type_ *)(uint_))
	Perform cast from unsigned integer `uint_` to pointer of type `type_`. More...

#define	Q_STATE_CAST(handler_) ((QStateHandler)(handler_))
	Perform cast to QStateHandler. More...

#define	Q_ACTION_CAST(action_) ((QActionHandler)(action_))
	Perform cast to QActionHandler. More...

#define	QHSM_INIT(me_, e_)
	Polymorphically executes the top-most initial transition in a HSM. More...

#define	QHSM_DISPATCH(me_, e_) ((*(me_)->vptr->dispatch)((me_), (e_)))
	Polymorphically dispatches an event to a HSM. More...

#define	QHsm_state(me_) (Q_STATE_CAST(Q_HSM_UPCAST(me_)->state.fun))
	Obtain the current active state from a HSM (read only). More...

#define	QHsm_childState(me_, parent_) QHsm_childState_(Q_HSM_UPCAST(me_), Q_STATE_CAST(parent_))
	Obtain the current active child state of a given parent in QHsm. More...

#define	QMsm_stateObj(me_) (Q_HSM_UPCAST(me_)->state.obj)
	Obtain the current active state from a MSM (read only) More...

#define	QMsm_childStateObj(me_, parent_) QMsm_childStateObj_(Q_HSM_UPCAST(me_), (parent_))
	Obtain the current active child state of a given parent in QMsm. More...

#define	Q_TRAN(target_) ((Q_HSM_UPCAST(me))->temp.fun = Q_STATE_CAST(target_), (QState)Q_RET_TRAN)
	Macro to call in a state-handler when it executes a regular or and initial transition. More...

#define	Q_TRAN_HIST(hist_) ((Q_HSM_UPCAST(me))->temp.fun = (hist_), (QState)Q_RET_TRAN_HIST)
	Macro to call in a state-handler when it executes a transition to history. More...

#define	Q_SUPER(super_) ((Q_HSM_UPCAST(me))->temp.fun = Q_STATE_CAST(super_), (QState)Q_RET_SUPER)
	Macro to call in a state-handler when it designates the superstate of a given state. More...

#define	Q_HANDLED() ((QState)Q_RET_HANDLED)
	Macro to call in a state-handler when it handles an event. More...

#define	Q_UNHANDLED() ((QState)Q_RET_UNHANDLED)
	Macro to call in a state-handler when it attempts to handle an event but a guard condition evaluates to 'false' and there is no other explicit way of handling the event. More...

#define	QM_ENTRY(state_) ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_ENTRY)
	Macro to call in a QM action-handler when it executes an entry action. More...

#define	QM_EXIT(state_) ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)
	Macro to call in a QM action-handler when it executes an exit action. More...

#define	QM_SM_EXIT(state_) ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)
	Macro to call in a QM submachine exit-handler. More...

#define	QM_TRAN(tatbl_)
	Macro to call in a QM state-handler when it executes a regular transition. More...

#define	QM_TRAN_INIT(tatbl_)
	Macro to call in a QM state-handler when it executes an initial transition. More...

#define	QM_TRAN_HIST(history_, tatbl_)
	Macro to call in a QM state-handler when it executes a transition to history. More...

#define	QM_TRAN_EP(tatbl_)
	Macro to call in a QM state-handler when it executes a transition to the submachine via an entry point. More...

#define	QM_TRAN_XP(xp_, tatbl_)
	Macro to call in a QM state-handler when it executes a transition to exit point. More...

#define	QM_HANDLED() ((QState)Q_RET_HANDLED)
	Macro to call in a QM state-handler when it handled an event. More...

#define	QM_UNHANDLED() ((QState)Q_RET_UNHANDLED)
	Macro to call in a QM state-handler when when it attempts to handle an event but a guard condition evaluates to 'false' and there is no other explicit way of handling the event. More...

#define	QM_SUPER() ((QState)Q_RET_SUPER)
	Macro to call in a QM state-handler when it designates the superstate to handle an event. More...

#define	QM_SUPER_SUB(host_) ((Q_HSM_UPCAST(me))->temp.obj = (host_), (QState)Q_RET_SUPER_SUB)
	Macro to call in a QM submachine-handler when it designates the host state to handle an event. More...

Typedefs
typedef char	char_t
	typedef for character strings. More...

typedef int	int_t
	typedef for line numbers in assertions and return from QF_run() More...

typedef int	enum_t
	typedef for enumerations used for event signals More...

typedef float	float32_t
	IEEE 754 32-bit floating point number, MISRA-C 2004 rule 6.3(req) More...

typedef double	float64_t
	IEEE 754 64-bit floating point number, MISRA-C 2004 rule 6.3(req) More...

typedef uint16_t	QSignal
	QSignal represents the signal of an event. More...

typedef uint_fast8_t	QState
	typedef of the return type from a state/action-handler function. More...

typedef QState(*	QStateHandler) (void const me, QEvt const const e)
	Pointer to a state-handler function. More...

typedef QState(*	QActionHandler) (void *const me)
	Pointer to an action-handler function. More...

typedef QHsm	QMsm
	QM State Machine implementation strategy. More...

Enumerations
enum	{ Q_RET_SUPER, Q_RET_SUPER_SUB, Q_RET_UNHANDLED, Q_RET_HANDLED, Q_RET_IGNORED, Q_RET_ENTRY, Q_RET_EXIT, Q_RET_NULL, Q_RET_TRAN, Q_RET_TRAN_INIT, Q_RET_TRAN_EP, Q_RET_TRAN_HIST, Q_RET_TRAN_XP }
	All possible values returned from state/action handlers. More...

enum	{ Q_ENTRY_SIG = 1, Q_EXIT_SIG, Q_INIT_SIG, Q_USER_SIG }
	QEP reserved signals. More...

Functions
void	QHsm_ctor (QHsm *const me, QStateHandler initial)
	Protected "constructor" of QHsm. More...

void	QHsm_init_ (QHsm const me, QEvt const const e)
	Implementation of the top-most initial transition in QHsm subclass. More...

void	QHsm_dispatch_ (QHsm const me, QEvt const const e)
	Implementation of dispatching events to a QHsm subclass. More...

QStateHandler	QHsm_childState_ (QHsm *const me, QStateHandler const parent)
	Helper function to obtain the current active child state of a parent. More...

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

QState	QHsm_top (void const const me, QEvt const const e)
	the top-state. More...

void	QMsm_ctor (QMsm *const me, QStateHandler initial)
	Protected "constructor" of QMsm. More...

void	QMsm_init_ (QMsm const me, QEvt const const e)
	Implementation of the top-most initial transition in QMsm. More...

void	QMsm_dispatch_ (QMsm const me, QEvt const const e)
	Implementation of disparching events to QMsm. More...

QMState const *	QMsm_childStateObj_ (QMsm const const me, QMState const const parent)
	Helper function to obtain the current active child state of a parent. More...

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

Variables
char_t const	QP_versionStr [6]
	the current QP version number string in ROM, based on QP_VERSION_STR More...

Detailed Description

Public QEP/C interface.

Definition in file qep.h.

Data Structure Documentation

◆ QEvt

struct QEvt

Event structure.

Description: QEvt represents events without parameters and serves as the base structure for derivation of events with parameters.

Usage: The following example illustrates how to add an event parameter by derivation of the QEvt structure. Please note that the QEvt member super_ is defined as the FIRST member of the derived struct.
typedef struct {
QEvt super; /* inherits QEvt */
uint8_t keyId; /* ID of the key depressed */
} CalcEvt;

See also: Object Orientation

Definition at line 153 of file qep.h.

Collaboration diagram for QEvt:

Data Fields
QSignal	sig	signal of the event instance
uint8_t	poolId_	pool ID (0 for static event)
uint8_t volatile	refCtr_	reference counter

◆ QHsmAttr

union QHsmAttr

Attribute of for the QHsm class (Hierarchical State Machine).

Description: This union represents possible values stored in the 'state' and 'temp' attributes of the QHsm class.

Definition at line 246 of file qep.h.

Collaboration diagram for QHsmAttr:

Data Fields
QStateHandler	fun	pointer to a state-handler function
QActionHandler	act	pointer to an action-handler function
struct QMState const *	obj	pointer to QMState object
struct QMTranActTable const *	tatbl	transition-action table

◆ QHsm

struct QHsm

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 base structure for derivation of state machines in the application code.

Usage: The following example illustrates how to derive a state machine structure from QHsm. Please note that the QHsm member super is defined as the FIRST member of the derived struct.
typedef struct {
QHsm super; /* inhertits QHsm */
double operand1;
double operand2;
char display[DISP_WIDTH + 1];
uint8_t len;
uint8_t opKey;
} Calc;

Definition at line 278 of file qep.h.

Collaboration diagram for QHsm:

Data Fields
struct QHsmVtbl const *	vptr	virtual pointer
union QHsmAttr	state	current active state (state-variable)
union QHsmAttr	temp	temporary: tran. chain, target state, etc.

◆ QMState

struct QMState

State object for the QMsm class (QM State Machine).

Description: This class groups together the attributes of a QMsm state, such as the parent state (state nesting), the associated state handler function and the exit action handler function. These attributes are used inside the QMsm_dispatch() and QMsm_init() functions.

Attention: The QMState class is only intended for the QM code generator and should not be used in hand-crafted code.

Definition at line 402 of file qep.h.

Collaboration diagram for QMState:

Data Fields
struct QMState const *	superstate	superstate of this state
QStateHandler const	stateHandler	state handler function
QActionHandler const	entryAction	entry action handler function
QActionHandler const	exitAction	exit action handler function
QActionHandler const	initAction	init action handler function

◆ QMTranActTable

struct QMTranActTable

Transition-Action Table for the Meta State Machine.

Definition at line 411 of file qep.h.

Collaboration diagram for QMTranActTable:

Data Fields
QMState const *	target
QActionHandler const	act[1]

Macro Definition Documentation

◆ QP_VERSION

#define QP_VERSION 640U

The current QP version as a decimal constant XYZ, where X is a 1-digit major version number, Y is a 1-digit minor version number, and Z is a 1-digit release number.

Definition at line 48 of file qep.h.

◆ QP_VERSION_STR

#define QP_VERSION_STR "6.4.0"

The current QP version number string of the form X.Y.Z, where X is a 1-digit major version number, Y is a 1-digit minor version number, and Z is a 1-digit release number.

Definition at line 54 of file qep.h.

◆ QP_RELEASE

#define QP_RELEASE 0x8EA03F5FU

Tamperproof current QP release (6.4.0) and date (2019-02-10)

Definition at line 57 of file qep.h.

◆ QEP_getVersion

#define QEP_getVersion ( ) (QP_versionStr)

get the current QEP version number string of the form "X.Y.Z"

Definition at line 101 of file qep.h.

◆ Q_SIGNAL_SIZE

#define Q_SIGNAL_SIZE 2

The size (in bytes) of the signal of an event.

Valid values: 1, 2, or 4; default 1

Description: This macro can be defined in the QEP port file (qep_port.h) to configure the QSignal type. When the macro is not defined, the default of 2 bytes is applied.

Definition at line 115 of file qep.h.

◆ Q_HSM_UPCAST

#define Q_HSM_UPCAST ( ptr_ ) ((QHsm *)(ptr_))

Perform upcast from a subclass of QHsm to the base class QHsm.

Description: Upcasting from a subclass to superclass is a very frequent and safe operation in object-oriented programming and object-oriented languages (such as C++) perform such upcasting automatically. However, OOP is implemented in C just as a set of coding conventions (see Object Orientation), and the C compiler does not "know" that certain types are related by inheritance. Therefore for C, the upcast must be performed explicitly. Unfortunately, pointer casting violates the advisory MISRA-C 2004 rule 11.4 "cast pointer to pointer". This macro encapsulates this deviation and provides a descriptive name for the reason of this cast.

Definition at line 180 of file qep.h.

◆ Q_EVT_CAST

#define Q_EVT_CAST ( class_ ) ((class_ const *)e)

Perform downcast of an event onto a subclass of QEvt class_.

Description: QEvt represents events without parameters and serves as the base structure This macro encapsulates the downcast of QEvt pointers, which violates MISRA-C 2004 rule 11.4(advisory). This macro helps to localize this deviation.

Definition at line 190 of file qep.h.

◆ Q_UINT2PTR_CAST

#define Q_UINT2PTR_CAST	(	type_,
		uint_
	)	((type_ *)(uint_))

Perform cast from unsigned integer uint_ to pointer of type type_.

Description: This macro encapsulates the cast to (type_ *), which QP ports or application might use to access embedded hardware registers. Such uses can trigger PC-Lint "Note 923: cast from int to pointer" and this macro helps to encapsulate this deviation.

Definition at line 201 of file qep.h.

◆ Q_STATE_CAST

#define Q_STATE_CAST ( handler_ ) ((QStateHandler)(handler_))

Perform cast to QStateHandler.

Description: This macro encapsulates the cast of a specific state handler function pointer to QStateHandler, which violates MISRA-C 2004 rule 11.4(advisory). This macro helps to localize this deviation.

Usage: 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;
}

Definition at line 224 of file qep.h.

◆ Q_ACTION_CAST

#define Q_ACTION_CAST ( action_ ) ((QActionHandler)(action_))

Perform cast to QActionHandler.

Description: This macro encapsulates the cast of a specific action handler function pointer to QActionHandler, which violates MISRA-C 2004 rule 11.4(adv). This macro helps to localize this deviation.

Definition at line 233 of file qep.h.

◆ QHSM_INIT

#define QHSM_INIT	(	me_,
		e_
	)

Value:

do {        \
    Q_ASSERT((me_)->vptr);             \
    (*(me_)->vptr->init)((me_), (e_)); \
} while (0)

Polymorphically executes the top-most initial transition in a HSM.

Parameters

[in,out]	me_	pointer (see Object Orientation)
[in]	e_	constant pointer the QEvt or a class derived from QEvt (see Object Orientation)

Note: Must be called only ONCE after the SM "constructor".

Usage: The following example illustrates how to initialize a SM, and dispatch events to it:
#include "qpc.h" /* QP/C public interface */
#include "calc.h" /* Calc derived from QHsm */
Q_DEFINE_THIS_FILE
static Calc l_calc; /* an instance of Calc SM */
int main() {
Calc_ctor(&l_calc); /* Calc "constructor" invokes QHsm_ctor() */
QMSM_INIT(&l_calc.super, (QEvt *)0); /* trigger initial transition */
for (;;) { /* event loop */
QEvt e;
. . .
/* wait for the next event and assign it to the event object e */
. . .
QMSM_DISPATCH(&l_calc.super, &e); /* dispatch e */
}
return 0;
}

Definition at line 308 of file qep.h.

◆ QHSM_DISPATCH

#define QHSM_DISPATCH	(	me_,
		e_
	)	((*(me_)->vptr->dispatch)((me_), (e_)))

Polymorphically dispatches an event to a HSM.

Description: Processes one event at a time in Run-to-Completion fashion.

Parameters

[in,out]	me_	pointer (see Object Orientation)
[in]	e_	constant pointer the QEvt or a structure derived from QEvt (see Object Orientation)

Note: Must be called after the "constructor" and after QHSM_INIT().

Definition at line 326 of file qep.h.

◆ QHsm_state

#define QHsm_state ( me_ ) (Q_STATE_CAST(Q_HSM_UPCAST(me_)->state.fun))

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

Parameters

[in] me_ pointer (see Object Orientation)

Returns: the current active state of a QHsm subclass

Note: this macro is used in QM for auto-generating code for state history

Definition at line 337 of file qep.h.

◆ QHsm_childState

#define QHsm_childState	(	me_,
		parent_
	)	QHsm_childState_(Q_HSM_UPCAST(me_), Q_STATE_CAST(parent_))

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

Parameters

[in]	me_	pointer (see Object Orientation)
[in]	parent_	pointer to the parent state-handler

Returns: the current active child state-handler of a given parent

Note: this macro is used in QM for auto-generating code for state history

Definition at line 346 of file qep.h.

◆ QMsm_stateObj

#define QMsm_stateObj ( me_ ) (Q_HSM_UPCAST(me_)->state.obj)

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

Parameters

[in] me_ pointer (see Object Orientation)

Returns: the current active state-object

Note: this macro is used in QM for auto-generating code for state history

Definition at line 431 of file qep.h.

◆ QMsm_childStateObj

#define QMsm_childStateObj	(	me_,
		parent_
	)	QMsm_childStateObj_(Q_HSM_UPCAST(me_), (parent_))

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

Parameters

[in]	me_	pointer (see Object Orientation)
[in]	parent_	pointer to the parent state-object

Returns: the current active child state-object of a given parent

Note: this macro is used in QM for auto-generating code for state history

Definition at line 440 of file qep.h.

◆ Q_TRAN

#define Q_TRAN ( target_ ) ((Q_HSM_UPCAST(me))->temp.fun = Q_STATE_CAST(target_), (QState)Q_RET_TRAN)

Macro to call in a state-handler when it executes a regular or and initial transition.

Applicable only to QHsm subclasses.

QState Blinky_off(Blinky * const me, QEvt const * const e) {
    QState status;
    switch (e->sig) {
        case Q_ENTRY_SIG: {
            BSP_ledOff();
            status = Q_HANDLED();
            break;
        }
        case TIMEOUT_SIG: {
            status = Q_TRAN(&Blinky_on); /*<== */
            break;
        }
        default: {
            status = Q_SUPER(&QHsm_top);
            break;
        }
    }
    return status;
}

Definition at line 456 of file qep.h.

◆ Q_TRAN_HIST

#define Q_TRAN_HIST ( hist_ ) ((Q_HSM_UPCAST(me))->temp.fun = (hist_), (QState)Q_RET_TRAN_HIST)

Macro to call in a state-handler when it executes a transition to history.

Applicable only to HSMs.

Usage: typedef struct {
QHsm super; /* inherit QHsm */
QStateHandler hist_doorClosed; /* history of doorClosed */
} ToastOven;
/*..........................................................*/
static QState ToastOven_doorClosed(ToastOven * const me,
QEvt const * const e)
{
QState status;
switch (e->sig) {
~ ~ ~
case Q_EXIT_SIG: {
me->hist_doorClosed = QHsm_state(&me->super);
status = Q_HANDLED();
break;
}
}
return status;
}
/*..........................................................*/
static QState ToastOven_doorOpen(ToastOven * const me,
QEvt const * const e)
{
QState status;
switch (e->sig) {
~ ~ ~
case CLOSE_SIG: {
status = Q_TRAN_HIST(hist_doorClosed); /*<== */
break;
}
default: {
status = Q_SUPER(&QHsm_top);
break;
}
}
return status;
}

Definition at line 465 of file qep.h.

◆ Q_SUPER

#define Q_SUPER ( super_ ) ((Q_HSM_UPCAST(me))->temp.fun = Q_STATE_CAST(super_), (QState)Q_RET_SUPER)

Macro to call in a state-handler when it designates the superstate of a given state.

Applicable only to QHsm subclasses.

Usage: QState Blinky_off(Blinky * const me, QEvt const * const e) {
QState status;
switch (e->sig) {
case Q_ENTRY_SIG: {
BSP_ledOff();
status = Q_HANDLED();
break;
}
case TIMEOUT_SIG: {
status = Q_TRAN(&Blinky_on); /*<== */
break;
}
default: {
status = Q_SUPER(&QHsm_top);
break;
}
}
return status;
}

Definition at line 474 of file qep.h.

◆ Q_HANDLED

#define Q_HANDLED ( ) ((QState)Q_RET_HANDLED)

Macro to call in a state-handler when it handles an event.

Applicable to both HSMs and FSMs.

Definition at line 480 of file qep.h.

◆ Q_UNHANDLED

#define Q_UNHANDLED ( ) ((QState)Q_RET_UNHANDLED)

Macro to call in a state-handler when it attempts to handle an event but a guard condition evaluates to 'false' and there is no other explicit way of handling the event.

Applicable only to QHsm subclasses.

Definition at line 486 of file qep.h.

◆ QM_ENTRY

#define QM_ENTRY ( state_ ) ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_ENTRY)

Macro to call in a QM action-handler when it executes an entry action.

Applicable only to QMsm subclasses.

Definition at line 525 of file qep.h.

◆ QM_EXIT

#define QM_EXIT ( state_ ) ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)

Macro to call in a QM action-handler when it executes an exit action.

Applicable only to QMsm subclasses.

Definition at line 531 of file qep.h.

◆ QM_SM_EXIT

#define QM_SM_EXIT ( state_ ) ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)

Macro to call in a QM submachine exit-handler.

Applicable only to QMsm subclasses.

Definition at line 544 of file qep.h.

◆ QM_TRAN

#define QM_TRAN ( tatbl_ )

Value:

((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_), \

(QState)Q_RET_TRAN)

Q_RET_TRAN

regular transition

Definition: qep.h:512

Q_HSM_UPCAST

#define Q_HSM_UPCAST(ptr_)

Perform upcast from a subclass of QHsm to the base class QHsm.

Definition: qep.h:180

QState

uint_fast8_t QState

typedef of the return type from a state/action-handler function.

Definition: qep.h:206

QMTranActTable

Transition-Action Table for the Meta State Machine.

Definition: qep.h:411

Macro to call in a QM state-handler when it executes a regular transition.

Applicable only to QMsm subclasses.

Definition at line 550 of file qep.h.

◆ QM_TRAN_INIT

#define QM_TRAN_INIT ( tatbl_ )

Value:

((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_), \

(QState)Q_RET_TRAN_INIT)

Q_RET_TRAN_INIT

initial transition in a state or submachine

Definition: qep.h:513

Q_HSM_UPCAST

#define Q_HSM_UPCAST(ptr_)

Perform upcast from a subclass of QHsm to the base class QHsm.

Definition: qep.h:180

QState

uint_fast8_t QState

typedef of the return type from a state/action-handler function.

Definition: qep.h:206

QMTranActTable

Transition-Action Table for the Meta State Machine.

Definition: qep.h:411

Macro to call in a QM state-handler when it executes an initial transition.

Applicable only to QMsm subclasses.

Definition at line 557 of file qep.h.

◆ QM_TRAN_HIST

#define QM_TRAN_HIST	(	history_,
		tatbl_
	)

Value:

((((Q_HSM_UPCAST(me))->state.obj = (history_)),                         \
      ((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_))), \
       (QState)Q_RET_TRAN_HIST)

Macro to call in a QM state-handler when it executes a transition to history.

Applicable only to QMsm subclasses.

Definition at line 564 of file qep.h.

◆ QM_TRAN_EP

#define QM_TRAN_EP ( tatbl_ )

Value:

((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_), \

(QState)Q_RET_TRAN_EP)

Q_RET_TRAN_EP

entry-point transition into a submachine

Definition: qep.h:514

Q_HSM_UPCAST

#define Q_HSM_UPCAST(ptr_)

Perform upcast from a subclass of QHsm to the base class QHsm.

Definition: qep.h:180

QState

uint_fast8_t QState

typedef of the return type from a state/action-handler function.

Definition: qep.h:206

QMTranActTable

Transition-Action Table for the Meta State Machine.

Definition: qep.h:411

Macro to call in a QM state-handler when it executes a transition to the submachine via an entry point.

Definition at line 572 of file qep.h.

◆ QM_TRAN_XP

#define QM_TRAN_XP	(	xp_,
		tatbl_
	)

Value:

((((Q_HSM_UPCAST(me))->state.act = (xp_)),                               \
        ((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_))),\
        (QState)Q_RET_TRAN_XP)

Macro to call in a QM state-handler when it executes a transition to exit point.

Applicable only to QMsm subclasses.

Definition at line 579 of file qep.h.

◆ QM_HANDLED

#define QM_HANDLED ( ) ((QState)Q_RET_HANDLED)

Macro to call in a QM state-handler when it handled an event.

Applicable only to QMsm subclasses.

Definition at line 587 of file qep.h.

◆ QM_UNHANDLED

#define QM_UNHANDLED ( ) ((QState)Q_RET_UNHANDLED)

Macro to call in a QM state-handler when when it attempts to handle an event but a guard condition evaluates to 'false' and there is no other explicit way of handling the event.

Applicable only to QMsm subclasses.

Definition at line 594 of file qep.h.

◆ QM_SUPER

#define QM_SUPER ( ) ((QState)Q_RET_SUPER)

Macro to call in a QM state-handler when it designates the superstate to handle an event.

Applicable only to QMSMs.

Definition at line 599 of file qep.h.

◆ QM_SUPER_SUB

#define QM_SUPER_SUB ( host_ ) ((Q_HSM_UPCAST(me))->temp.obj = (host_), (QState)Q_RET_SUPER_SUB)

Macro to call in a QM submachine-handler when it designates the host state to handle an event.

Applicable only to QMSMs.

Definition at line 604 of file qep.h.

Typedef Documentation

◆ char_t

typedef char char_t

typedef for character strings.

Description: This typedef specifies character type for exclusive use in character strings. Use of this type, rather than plain 'char', is in compliance with the MISRA-C 2004 Rules 6.1(req), 6.3(adv).

Definition at line 70 of file qep.h.

◆ int_t

typedef int int_t

typedef for line numbers in assertions and return from QF_run()

Definition at line 73 of file qep.h.

◆ enum_t

typedef int enum_t

typedef for enumerations used for event signals

Definition at line 76 of file qep.h.

◆ float32_t

typedef float float32_t

IEEE 754 32-bit floating point number, MISRA-C 2004 rule 6.3(req)

Note: QP does not use floating-point types anywhere in the internal implementation, except in QS software tracing, where utilities for output of floating-point numbers are provided for application-level trace records.

Definition at line 85 of file qep.h.

◆ float64_t

typedef double float64_t

IEEE 754 64-bit floating point number, MISRA-C 2004 rule 6.3(req)

Note: QP does not use floating-point types anywhere in the internal implementation, except in QS software tracing, where utilities for output of floating-point numbers are provided for application-level trace records.

Definition at line 94 of file qep.h.

◆ QSignal

typedef uint16_t QSignal

QSignal represents the signal of an event.

Description: The relationship between an event and a signal is as follows. A signal in UML is the specification of an asynchronous stimulus that triggers reactions, and as such is an essential part of an event. (The signal conveys the type of the occurrence-what happened?) However, an event can also contain additional quantitative information about the occurrence in form of event parameters.

Definition at line 130 of file qep.h.

◆ QState

typedef uint_fast8_t QState

typedef of the return type from a state/action-handler function.

Definition at line 206 of file qep.h.

◆ QStateHandler

typedef QState(* QStateHandler) (void *const me, QEvt const *const e)

Pointer to a state-handler function.

Definition at line 209 of file qep.h.

◆ QActionHandler

typedef QState(* QActionHandler) (void *const me)

Pointer to an action-handler function.

Definition at line 212 of file qep.h.

◆ QMsm

typedef QHsm QMsm

QM State Machine implementation strategy.

Description: 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 structure for derivation of state machines in the application code.

Usage: The following example illustrates how to derive a state machine structure 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;

See also: Object Orientation

Definition at line 385 of file qep.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

All possible values returned from state/action handlers.

Note: The order matters for algorithmic correctness.

Enumerator
Q_RET_SUPER	event passed to superstate to handle
Q_RET_SUPER_SUB	event passed to submachine superstate
Q_RET_UNHANDLED	event unhandled due to a guard
Q_RET_HANDLED	event handled (internal transition)
Q_RET_IGNORED	event silently ignored (bubbled up to top)
Q_RET_ENTRY	state entry action executed
Q_RET_EXIT	state exit action executed
Q_RET_NULL	return value without any effect
Q_RET_TRAN	regular transition
Q_RET_TRAN_INIT	initial transition in a state or submachine
Q_RET_TRAN_EP	entry-point transition into a submachine
Q_RET_TRAN_HIST	transition to history of a given state
Q_RET_TRAN_XP	exit-point transition out of a submachine

Definition at line 494 of file qep.h.

◆ anonymous enum

anonymous enum

QEP reserved signals.

Enumerator
Q_ENTRY_SIG	signal for coding entry actions
Q_EXIT_SIG	signal for coding exit actions
Q_INIT_SIG	signal for coding initial transitions
Q_USER_SIG	first signal that can be used for user signals

Definition at line 608 of file qep.h.

Function Documentation

◆ QHsm_ctor()

void QHsm_ctor	(	QHsm *const	me,
		QStateHandler	initial
	)

Protected "constructor" of QHsm.

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

Parameters

[in,out]	me	pointer (see Object Orientation)
[in]	initial	pointer 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;
}

Definition at line 127 of file qep_hsm.c.

◆ QHsm_init_()

void QHsm_init_	(	QHsm *const	me,
		QEvt const *const	e
	)

Implementation of the top-most initial transition in QHsm subclass.

Description: Executes the top-most initial transition in a HSM.

Parameters

[in,out]	me	pointer (see Object Orientation)
[in]	e	pointer to the initialization event (might be NULL)

Note: Must be called only ONCE after the QHsm_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 147 of file qep_hsm.c.

◆ QHsm_dispatch_()

void QHsm_dispatch_	(	QHsm *const	me,
		QEvt const *const	e
	)

Implementation of dispatching events to a QHsm subclass.

Description: 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]	me	pointer (see Object Orientation)
[in]	e	pointer to the event to be dispatched to the HSM

Note: This function should be called only via the virtual table (see QHSM_DISPATCH()) and should NOT be called directly in the applications.

Precondition: the current state must be initialized and the state configuration must be stable

Definition at line 252 of file qep_hsm.c.

◆ QHsm_childState_()

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

Helper function to obtain the current active child state of a parent.

Description: 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	pointer (see Object Orientation)
[in]	parent	pointer 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.

See also: QHsm_childState()

Postcondition: the child must be found

Definition at line 607 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.

Description: 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]	me	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

Precondition: the state configuration must be stable

Definition at line 562 of file qep_hsm.c.

◆ QHsm_top()

QState QHsm_top	(	void const *const	me,
		QEvt const *const	e
	)

the top-state.

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

Parameters

[in]	me	pointer (see Object Orientation)
[in]	e	pointer 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.

Definition at line 233 of file qep_hsm.c.

◆ QMsm_ctor()

void QMsm_ctor	(	QMsm *const	me,
		QStateHandler	initial
	)

Protected "constructor" of QMsm.

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

Parameters

[in,out]	me	pointer (see Object Orientation)
[in]	initial	the top-most initial transition for the MSM.

Note: Must be called only ONCE before QHSM_INIT().; QMsm inherits QHsm, so by the Object Orientation convention it should call the constructor of the superclass, i.e., QHsm_ctor(). However, this would pull in the QHsmVtbl, 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 Vtbl, 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;
}

Definition at line 111 of file qep_msm.c.

◆ QMsm_init_()

void QMsm_init_	(	QMsm *const	me,
		QEvt const *const	e
	)

Implementation of the top-most initial transition in QMsm.

Description: Executes the top-most initial transition in a MSM.

Parameters

[in,out]	me	pointer (see Object Orientation)
[in]	e	pointer to the initialization event (might be NULL)

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 133 of file qep_msm.c.

◆ QMsm_dispatch_()

void QMsm_dispatch_	(	QMsm *const	me,
		QEvt const *const	e
	)

Implementation of disparching events to QMsm.

Description: 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]	me	pointer (see Object Orientation)
[in]	e	pointer to the event to be dispatched to the MSM

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 184 of file qep_msm.c.

◆ QMsm_childStateObj_()

QMState const* QMsm_childStateObj_	(	QMsm const *const	me,
		QMState const *const	parent
	)

Helper function to obtain the current active child state of a parent.

Description: 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]	me	pointer (see Object Orientation)
[in]	parent	pointer 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 570 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.

Description: 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]	me	pointer (see Object Orientation)
[in]	state	pointer 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 539 of file qep_msm.c.

Variable Documentation

◆ QP_versionStr

char_t const QP_versionStr[6]

the current QP version number string in ROM, based on QP_VERSION_STR

Definition at line 52 of file qep_hsm.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Data Structure Documentation

◆ QEvt

◆ QHsmAttr

◆ QHsm

◆ QMState

◆ QMTranActTable

Macro Definition Documentation

◆ QP_VERSION

◆ QP_VERSION_STR

◆ QP_RELEASE

◆ QEP_getVersion

◆ Q_SIGNAL_SIZE

◆ Q_HSM_UPCAST

◆ Q_EVT_CAST

◆ Q_UINT2PTR_CAST

◆ Q_STATE_CAST

◆ Q_ACTION_CAST

◆ QHSM_INIT

◆ QHSM_DISPATCH

◆ QHsm_state

◆ QHsm_childState

◆ QMsm_stateObj

◆ QMsm_childStateObj

◆ Q_TRAN

◆ Q_TRAN_HIST

◆ Q_SUPER

◆ Q_HANDLED

◆ Q_UNHANDLED

◆ QM_ENTRY

◆ QM_EXIT

◆ QM_SM_EXIT

◆ QM_TRAN

◆ QM_TRAN_INIT

◆ QM_TRAN_HIST

◆ QM_TRAN_EP

◆ QM_TRAN_XP

◆ QM_HANDLED

◆ QM_UNHANDLED

◆ QM_SUPER

◆ QM_SUPER_SUB

Typedef Documentation

◆ char_t

◆ int_t

◆ enum_t

◆ float32_t

◆ float64_t

◆ QSignal

◆ QState

◆ QStateHandler

◆ QActionHandler

◆ QMsm

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

Function Documentation

◆ QHsm_ctor()

◆ QHsm_init_()

◆ QHsm_dispatch_()

◆ QHsm_childState_()

◆ QHsm_isIn()

◆ QHsm_top()

◆ QMsm_ctor()

◆ QMsm_init_()

◆ QMsm_dispatch_()

◆ QMsm_childStateObj_()

◆ QMsm_isInState()

Variable Documentation

◆ QP_versionStr