QP/C  6.0.2
qep.h File Reference

Public QEP/C interface. More...

Go to the source code of 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   602
 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.
 
#define QP_VERSION_STR   "6.0.2"
 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.
 
#define QP_RELEASE   0x99F36B05U
 Tamperproof current QP release (6.0.2) and date (2017-12-10)
 
#define QEP_getVersion()   (QP_versionStr)
 get the current QEP version number string of the form "X.Y.Z"
 
#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_DIM(array_)   (sizeof(array_) / sizeof((array_)[0]))
 Helper macro to calculate static dimension of a 1-dim array_.
 
#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_)   ((*(me_)->vptr->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()
 
typedef int enum_t
 typedef for enumerations used for event signals
 
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
 

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.

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 249 of file qep.h.

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 281 of file qep.h.

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.

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.

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

Macro Definition Documentation

◆ 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 204 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 227 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 236 of file qep.h.

◆ QHSM_INIT

#define QHSM_INIT (   me_,
  e_ 
)    ((*(me_)->vptr->init)((me_), (e_)))

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 */
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 311 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_), \
regular transition
Definition: qep.h:512
#define Q_HSM_UPCAST(ptr_)
Perform upcast from a subclass of QHsm to the base class QHsm.
Definition: qep.h:180
uint_fast8_t QState
typedef of the return type from a state/action-handler function.
Definition: qep.h:209
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_), \
initial transition in a state or submachine
Definition: qep.h:513
#define Q_HSM_UPCAST(ptr_)
Perform upcast from a subclass of QHsm to the base class QHsm.
Definition: qep.h:180
uint_fast8_t QState
typedef of the return type from a state/action-handler function.
Definition: qep.h:209
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_))), \
transition to history of a given state
Definition: qep.h:517
#define Q_HSM_UPCAST(ptr_)
Perform upcast from a subclass of QHsm to the base class QHsm.
Definition: qep.h:180
uint_fast8_t QState
typedef of the return type from a state/action-handler function.
Definition: qep.h:209
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 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_), \
entry-point transition into a submachine
Definition: qep.h:514
#define Q_HSM_UPCAST(ptr_)
Perform upcast from a subclass of QHsm to the base class QHsm.
Definition: qep.h:180
uint_fast8_t QState
typedef of the return type from a state/action-handler function.
Definition: qep.h:209
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_))),\
#define Q_HSM_UPCAST(ptr_)
Perform upcast from a subclass of QHsm to the base class QHsm.
Definition: qep.h:180
uint_fast8_t QState
typedef of the return type from a state/action-handler function.
Definition: qep.h:209
exit-point transition out of a submachine
Definition: qep.h:518
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 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.

◆ 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 of the return type from a state/action-handler function.

Definition at line 209 of file qep.h.

◆ QStateHandler

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

Pointer to a state-handler function.

Definition at line 212 of file qep.h.

◆ QActionHandler

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

Pointer to an action-handler function.

Definition at line 215 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]mepointer (see Object Orientation)
[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;
}

Definition at line 126 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]mepointer (see Object Orientation)
[in]epointer 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 146 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]mepointer (see Object Orientation)
[in]epointer 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 251 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]mepointer (see Object Orientation)
[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.
See also
QHsm_childState()
Postcondition
the child must be found

Definition at line 605 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]mepointer (see Object Orientation)
[in]statepointer 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 560 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]mepointer (see Object Orientation)
[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.

Definition at line 232 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]mepointer (see Object Orientation)
[in]initialthe 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 110 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]mepointer (see Object Orientation)
[in]epointer 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 132 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]mepointer (see Object Orientation)
[in]epointer 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 183 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]mepointer (see Object Orientation)
[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 557 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]mepointer (see Object Orientation)
[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 526 of file qep_msm.c.