QP/C++  5.9.5
qep.h File Reference

QEP/C++ platform-independent public interface. More...

Go to the source code of this file.

Classes

struct  QP::QEvt
 QEvt base class. More...
 
union  QP::QHsmAttr
 Attribute of for the QHsm class (Hierarchical State Machine). More...
 
class  QP::QHsm
 Hierarchical State Machine base class. More...
 
class  QP::QMsm
 QM State Machine implementation strategy. More...
 
struct  QP::QMState
 State object for the QMsm class (Meta State Machine). More...
 
struct  QP::QMTranActTable
 Transition-Action Table for the Meta State Machine. More...
 
class  QP::QEP
 Provides miscellaneous QEP services. More...
 

Namespaces

 QP
 namespace associated with the QP/C++ framework
 

Macros

#define QP_VERSION   595
 The current QP version as a decimal constant XYZ, where X is a 1-digit.
 
#define QP_VERSION_STR   "5.9.5"
 The current QP version number string of the form X.Y.Z, where X is.
 
#define QP_RELEASE   0x9A3E2FACU
 Tamperproof current QP release (5.9.5) and date (2017-07-20)
 
#define Q_SIGNAL_SIZE   2
 The size (in bytes) of the signal of an event. Valid values: 1, 2, or 4; default 1. More...
 
#define Q_DIM(array_)   (sizeof(array_) / sizeof((array_)[0]))
 helper macro to calculate static dimension of a 1-dim array array_
 
#define Q_EVT_CAST(class_)   (static_cast<class_ const *>(e))
 Perform downcast of an event onto a subclass of QEvt class_. More...
 
#define Q_UINT2PTR_CAST(type_, uint_)   (reinterpret_cast<type_ *>(uint_))
 Perform cast from unsigned integer uint_ to pointer of type type_. More...
 
#define QEVT_INITIALIZER(sig_)
 Initializer of static constant QEvt instances. More...
 
#define Q_STATE_CAST(handler_)   (reinterpret_cast<QP::QStateHandler>(handler_))
 Perform cast to QStateHandler. More...
 
#define Q_ACTION_CAST(action_)   (reinterpret_cast<QP::QActionHandler>(action_))
 Perform cast to QActionHandler. More...
 
#define QM_ENTRY(state_)   (me->qm_entry_((state_)))
 Macro to call in a QM state entry-handler. Applicable only to QMSMs.
 
#define QM_EXIT(state_)   (me->qm_exit_((state_)))
 Macro to call in a QM state exit-handler. Applicable only to QMSMs.
 
#define QM_SM_EXIT(state_)   (me->qm_exit_((state_)))
 Macro to call in a QM submachine exit-handler. Applicable only to QMSMs.
 
#define QM_TRAN(tatbl_)   (me->qm_tran_(reinterpret_cast<QP::QMTranActTable const *>(tatbl_)))
 Macro to call in a QM state-handler when it executes a regular transition. Applicable only to QMSMs.
 
#define QM_TRAN_INIT(tatbl_)   (me->qm_tran_init_(reinterpret_cast<QP::QMTranActTable const *>(tatbl_)))
 Macro to call in a QM state-handler when it executes an initial transition. Applicable only to QMSMs.
 
#define QM_TRAN_HIST(history_, tatbl_)
 Macro to call in a QM state-handler when it executes a transition to history. Applicable only to QMSMs. More...
 
#define QM_TRAN_EP(tatbl_)   (me->qm_tran_ep_(reinterpret_cast<QP::QMTranActTable const *>(tatbl_)))
 Macro to call in a QM state-handler when it executes an initial transition. Applicable only to QMSMs.
 
#define QM_TRAN_XP(xp_, tatbl_)
 Macro to call in a QM state-handler when it executes a transition to exit point. Applicable only to QMSMs. More...
 
#define QM_SUPER_SUB(state_)   (me->qm_super_sub_((state_)))
 Designates the superstate of a given state in an MSM.
 
#define Q_TRAN(target_)   (me->tran_(Q_STATE_CAST(target_)))
 Designates a target for an initial or regular transition. Q_TRAN() can be used both in the FSMs and HSMs. More...
 
#define Q_TRAN_HIST(hist_)   (me->tran_hist_((hist_)))
 Designates a target for an initial or regular transition. Q_TRAN() can be used both in the FSMs and HSMs. More...
 
#define Q_SUPER(state_)   (me->super_(Q_STATE_CAST(state_)))
 Designates the superstate of a given state in an HSM. 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
 typedef for 32-bit IEEE 754 floating point numbers More...
 
typedef double float64_t
 typedef for 64-bit IEEE 754 floating point numbers More...
 
typedef uint16_t QP::QSignal
 QSignal represents the signal of an event. More...
 
typedef uint_fast8_t QP::QState
 Type returned from state-handler functions.
 
typedef QState(* QP::QStateHandler) (void *const me, QEvt const *const e)
 pointer to state-handler function
 
typedef QState(* QP::QActionHandler) (void *const me)
 pointer to an action-handler function
 

Variables

char_t const QP::versionStr [6] = QP_VERSION_STR
 the current QP version number string based on QP_VERSION_STR
 
QState const QP::Q_RET_SUPER = static_cast<QState>(0)
 event passed to the superstate to handle
 
QState const QP::Q_RET_SUPER_SUB = static_cast<QState>(1)
 event passed to submachine superstate
 
QState const QP::Q_RET_UNHANDLED = static_cast<QState>(2)
 event unhandled due to a guard evaluating to FALSE
 
QState const QP::Q_RET_HANDLED = static_cast<QState>(3)
 event handled (internal transition)
 
QState const QP::Q_RET_IGNORED = static_cast<QState>(4)
 event silently ignored (bubbled up to top)
 
QState const QP::Q_RET_ENTRY = static_cast<QState>(5)
 state entry action executed
 
QState const QP::Q_RET_EXIT = static_cast<QState>(6)
 state exit action executed
 
QState const QP::Q_RET_NULL = static_cast<QState>(7)
 return value without any effect
 
QState const QP::Q_RET_TRAN = static_cast<QState>(8)
 regular transition taken
 
QState const QP::Q_RET_TRAN_INIT = static_cast<QState>(9)
 initial transition taken
 
QState const QP::Q_RET_TRAN_HIST = static_cast<QState>(10)
 event handled (transition to history)
 
QState const QP::Q_RET_TRAN_EP = static_cast<QState>(11)
 entry-point transition into a submachine
 
QState const QP::Q_RET_TRAN_XP = static_cast<QState>(12)
 exit-point transition out of a submachine
 
QMState *const QP::QMsm_top = static_cast<QMState *>(0)
 Top-most state of QMSM is NULL.
 
enum_t const QP::Q_USER_SIG = static_cast<enum_t>(4)
 Offset or the user signals.
 

Detailed Description

QEP/C++ platform-independent public interface.

Definition in file qep.h.


Class Documentation

◆ QP::QHsmAttr

union QP::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 and QMsm classes.

Definition at line 238 of file qep.h.

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

◆ QP::QMState

struct QP::QMState

State object for the QMsm class (Meta 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 QP::QMsm::dispatch() and QP::QMsm::init() functions.
Attention
The QMStateObj class is only intended for the QM code generator and should not be used in hand-crafted code.

Definition at line 554 of file qep.h.

Class Members
QActionHandler const entryAction entry action handler function
QActionHandler const exitAction exit action handler function
QActionHandler const initAction init action handler function
QStateHandler const stateHandler state handler function
QMState const * superstate superstate of this state

◆ QP::QMTranActTable

struct QP::QMTranActTable

Transition-Action Table for the Meta State Machine.

Definition at line 563 of file qep.h.

Class Members
QActionHandler const act[1]
QMState const * target

Macro Definition Documentation

◆ Q_ACTION_CAST

#define Q_ACTION_CAST (   action_)    (reinterpret_cast<QP::QActionHandler>(action_))

Perform cast to QActionHandler.

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

Definition at line 599 of file qep.h.

◆ Q_EVT_CAST

#define Q_EVT_CAST (   class_)    (static_cast<class_ const *>(e))

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

Description
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 112 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 QP::QSignal type. When the macro is not defined, the default of 1 byte is chosen.

Definition at line 64 of file qep.h.

◆ Q_STATE_CAST

#define Q_STATE_CAST (   handler_)    (reinterpret_cast<QP::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.

Definition at line 591 of file qep.h.

◆ Q_SUPER

#define Q_SUPER (   state_)    (me->super_(Q_STATE_CAST(state_)))

Designates the superstate of a given state in an HSM.

Usage
class Calc : public QHsm { // derived from QHsm
private:
double m_operand1;
double m_operand2;
char m_display[DISP_WIDTH + 1];
uint8_t m_len;
uint8_t m_opKey;
public:
Calc() : QHsm(Q_STATE_CAST(&QCalc::initial)) { // ctor
}
protected:
static QState initial (Calc * const me, QEvt const *e);
static QState on (Calc * const me, QEvt const *e);
static QState error (Calc * const me, QEvt const *e);
static QState ready (Calc * const me, QEvt const *e);
static QState result (Calc * const me, QEvt const *e);
static QState begin (Calc * const me, QEvt const *e);
. . .
};

Definition at line 662 of file qep.h.

◆ Q_TRAN

#define Q_TRAN (   target_)    (me->tran_(Q_STATE_CAST(target_)))

Designates a target for an initial or regular transition. Q_TRAN() can be used both in the FSMs and HSMs.

Usage
// state handler function for the Bomb FSM ..................................
QState Bomb::setting(Bomb * const me, QEvt const *e) {
switch (e->sig) {
. . .
case ARM_SIG: {
return Q_TRAN(&Bomb::timing);
}
}
return Q_IGNORED();
}
// state handler function for the Calc HSM ..................................
QState Calc::begin(Calc * const me, QEvt const *e) {
switch (e->sig) {
. . .
case OPER_SIG: {
if (((CalcEvt *)e)->keyId == KEY_MINUS) {
return Q_TRAN(&Calc::negated1);
}
return Q_HANDLED();
}
}
return Q_SUPER(&Calc::ready);
}

Definition at line 651 of file qep.h.

◆ Q_TRAN_HIST

#define Q_TRAN_HIST (   hist_)    (me->tran_hist_((hist_)))

Designates a target for an initial or regular transition. Q_TRAN() can be used both in the FSMs and HSMs.

Usage
// state handler function for the Bomb FSM ..................................
QState Bomb::setting(Bomb * const me, QEvt const *e) {
switch (e->sig) {
. . .
case ARM_SIG: {
return Q_TRAN(&Bomb::timing);
}
}
return Q_IGNORED();
}
// state handler function for the Calc HSM ..................................
QState Calc::begin(Calc * const me, QEvt const *e) {
switch (e->sig) {
. . .
case OPER_SIG: {
if (((CalcEvt *)e)->keyId == KEY_MINUS) {
return Q_TRAN(&Calc::negated1);
}
return Q_HANDLED();
}
}
return Q_SUPER(&Calc::ready);
}

Definition at line 657 of file qep.h.

◆ Q_UINT2PTR_CAST

#define Q_UINT2PTR_CAST (   type_,
  uint_ 
)    (reinterpret_cast<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 121 of file qep.h.

◆ QEVT_INITIALIZER

#define QEVT_INITIALIZER (   sig_)
Value:
{ static_cast<QP::QSignal>(sig_), \
static_cast<uint8_t>(0), static_cast<uint8_t>(0) }
uint16_t QSignal
QSignal represents the signal of an event.
Definition: qep.h:151
unsigned char uint8_t
exact-width 8-bit unsigned int
Definition: stdint.h:29

Initializer of static constant QEvt instances.

Description
This macro encapsulates the ugly casting of enumerated signals to QSignal and constants for QEvt.poolID and QEvt.refCtr_.

Definition at line 128 of file qep.h.

◆ QM_TRAN_HIST

#define QM_TRAN_HIST (   history_,
  tatbl_ 
)
Value:
(me->qm_tran_hist_((history_), \
reinterpret_cast<QP::QMTranActTable const *>(tatbl_)))

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

Definition at line 628 of file qep.h.

◆ QM_TRAN_XP

#define QM_TRAN_XP (   xp_,
  tatbl_ 
)
Value:
(me->qm_tran_xp_((xp_), \
reinterpret_cast<QP::QMTranActTable const *>(tatbl_)))

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

Definition at line 639 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 79 of file qep.h.

◆ float32_t

typedef float float32_t

typedef for 32-bit IEEE 754 floating point numbers

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.

◆ float64_t

typedef double float64_t

typedef for 64-bit IEEE 754 floating point numbers

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