QP/C  6.9.3
Real-Time Embedded Framework
qep.h File Reference

Public QEP/C interface. More...

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

Go to the source code of this file.

Data Structures

struct  QEvt
 
union  QHsmAttr
 
struct  QHsm
 
struct  QHsmVtable
 
struct  QMsm
 
struct  QMState
 
struct  QMTranActTable
 

Macros

#define QP_VERSION   693U
 
#define QP_VERSION_STR   "6.9.3"
 
#define QP_RELEASE   0x8295AA8AU
 
#define Q_SIGNAL_SIZE   2U
 
#define Q_HSM_UPCAST(ptr_)   ((QHsm *)(ptr_))
 
#define Q_EVT_CAST(class_)   ((class_ const *)e)
 
#define Q_UINT2PTR_CAST(type_, uintptr_)   ((type_ *)(uintptr_))
 
#define Q_STATE_CAST(handler_)   ((QStateHandler)(handler_))
 
#define Q_ACTION_CAST(action_)   ((QActionHandler)(action_))
 
#define Q_TRAN(target_)    ((Q_HSM_UPCAST(me))->temp.fun = Q_STATE_CAST(target_), (QState)Q_RET_TRAN)
 
#define Q_TRAN_HIST(hist_)    ((Q_HSM_UPCAST(me))->temp.fun = (hist_), (QState)Q_RET_TRAN_HIST)
 
#define Q_SUPER(super_)    ((Q_HSM_UPCAST(me))->temp.fun = Q_STATE_CAST(super_), (QState)Q_RET_SUPER)
 
#define Q_HANDLED()   ((QState)Q_RET_HANDLED)
 
#define Q_UNHANDLED()   ((QState)Q_RET_UNHANDLED)
 
#define Q_ACTION_NULL   ((QActionHandler)0)
 
#define QM_ENTRY(state_)    ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_ENTRY)
 
#define QM_EXIT(state_)    ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)
 
#define QM_SM_EXIT(state_)    ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)
 
#define QM_TRAN(tatbl_)
 
#define QM_TRAN_INIT(tatbl_)
 
#define QM_TRAN_HIST(history_, tatbl_)
 
#define QM_TRAN_EP(tatbl_)
 
#define QM_TRAN_XP(xp_, tatbl_)
 
#define QM_HANDLED()   ((QState)Q_RET_HANDLED)
 
#define QM_UNHANDLED()   ((QState)Q_RET_UNHANDLED)
 
#define QM_SUPER()   ((QState)Q_RET_SUPER)
 
#define QM_SUPER_SUB(host_)    ((Q_HSM_UPCAST(me))->temp.obj = (host_), (QState)Q_RET_SUPER_SUB)
 
#define QM_STATE_NULL   ((QMState *)0)
 

Typedefs

typedef char char_t
 
typedef int int_t
 
typedef unsigned uint_t
 
typedef int enum_t
 
typedef float float32_t
 
typedef double float64_t
 
typedef uint16_t QSignal
 
typedef uint_fast8_t QState
 
typedef QState(* QStateHandler) (void *const me, QEvt const *const e)
 
typedef QState(* QActionHandler) (void *const me)
 
typedef void(* QXThreadHandler) (QXThread *const me)
 

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
}
 
enum  { Q_ENTRY_SIG = 1 , Q_EXIT_SIG , Q_INIT_SIG , Q_USER_SIG }
 

Functions

void QHsm_init_ (QHsm *const me, void const *const e, uint_fast8_t const qs_id)
 
void QHsm_dispatch_ (QHsm *const me, QEvt const *const e, uint_fast8_t const qs_id)
 
QStateHandler QHsm_getStateHandler_ (QHsm *const me)
 

Variables

char_t const QP_versionStr [7]
 

Detailed Description

Public QEP/C interface.

Definition in file qep.h.


Data Structure Documentation

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

Collaboration diagram for QHsmAttr:
Collaboration graph
Data Fields
QStateHandler fun

pointer to a state-handler function

QActionHandler act

pointer to an action-handler function

QXThreadHandler thr

pointer to an thread-handler function

struct QMState const * obj

pointer to QMState object

QMTranActTable const * tatbl

transition-action table

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

Collaboration diagram for QMState:
Collaboration graph
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 476 of file qep.h.

Collaboration diagram for QMTranActTable:
Collaboration graph
Data Fields
struct QMState const * target
QActionHandler const act[1]

Macro Definition Documentation

◆ QP_VERSION

#define QP_VERSION   693U

The current QP version as a decimal constant XXYZ, where XX is a 2-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.9.3"

The current QP version number string of the form XX.Y.Z, where XX is a 2-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   0x8295AA8AU

Encrypted current QP release (6.9.3) and date (2021-04-12)

Definition at line 57 of file qep.h.

◆ Q_SIGNAL_SIZE

#define Q_SIGNAL_SIZE   2U

The size (in bytes) of the signal of an event. Valid values: 1U, 2U, or 4U; default 2U

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 113 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_,
  uintptr_ 
)    ((type_ *)(uintptr_))

Perform cast from unsigned integer pointer uintptr_ 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.

Definition at line 199 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-2012 rule 11.1(req). 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;
}
#define Q_STATE_CAST(handler_)
Definition: qep.h:228
void QHsm_ctor(QHsm *const me, QStateHandler initial)
Definition: qep_hsm.c:133

Definition at line 228 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-2012 rule 11.1(req). This macro helps to localize this deviation.

Definition at line 237 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;
}
#define Q_HANDLED()
Definition: qep.h:578
#define Q_TRAN(target_)
Definition: qep.h:554
uint_fast8_t QState
Definition: qep.h:204
#define Q_SUPER(super_)
Definition: qep.h:572
@ Q_ENTRY_SIG
Definition: qep.h:714
Definition: qep.h:151
QSignal sig
Definition: qep.h:152
QState QHsm_top(void const *const me, QEvt const *const e)
Definition: qep_hsm.c:250

Definition at line 554 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;
}
QState(* QStateHandler)(void *const me, QEvt const *const e)
Definition: qep.h:210
#define Q_TRAN_HIST(hist_)
Definition: qep.h:563
@ Q_EXIT_SIG
Definition: qep.h:715
Definition: qep.h:282
#define QHsm_state(me_)
Definition: qep.h:388

Definition at line 563 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 572 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 578 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 584 of file qep.h.

◆ Q_ACTION_NULL

#define Q_ACTION_NULL   ((QActionHandler)0)

Macro to provide strictly-typed zero-action to terminate action lists ! in the transition-action-tables

Definition at line 589 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 628 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 634 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 subclasses of QMsm.

Definition at line 647 of file qep.h.

◆ QM_TRAN

#define QM_TRAN (   tatbl_)
Value:
((Q_HSM_UPCAST(me))->temp.tatbl \
= (QMTranActTable *)(tatbl_), (QState)Q_RET_TRAN)
@ Q_RET_TRAN
Definition: qep.h:615
#define Q_HSM_UPCAST(ptr_)
Definition: qep.h:180

Macro to call in a QM state-handler when it executes a regular transition. Applicable only to QMsm subclasses.

Definition at line 653 of file qep.h.

◆ QM_TRAN_INIT

#define QM_TRAN_INIT (   tatbl_)
Value:
((Q_HSM_UPCAST(me))->temp.tatbl \
@ Q_RET_TRAN_INIT
Definition: qep.h:616

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

Definition at line 659 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 *)(tatbl_))), \
@ Q_RET_TRAN_HIST
Definition: qep.h:620

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

Definition at line 665 of file qep.h.

◆ QM_TRAN_EP

#define QM_TRAN_EP (   tatbl_)
Value:
((Q_HSM_UPCAST(me))->temp.tatbl \
= (struct QMTranActTable *)(tatbl_), (QState)Q_RET_TRAN_EP)
@ Q_RET_TRAN_EP
Definition: qep.h:617

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

Definition at line 673 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 *)(tatbl_))), \
@ Q_RET_TRAN_XP
Definition: qep.h:621

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

Definition at line 679 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 687 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 694 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 699 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 704 of file qep.h.

◆ QM_STATE_NULL

#define QM_STATE_NULL   ((QMState *)0)

Macro to provide strictly-typed zero-state to use for submachines. ! Applicable to suclasses of QP::QMsm.

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

◆ uint_t

typedef unsigned uint_t

typedef for unsigned int promotions in expressions

Definition at line 76 of file qep.h.

◆ enum_t

typedef int enum_t

typedef for enumerations used for event signals

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

◆ QState

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

Definition at line 204 of file qep.h.

◆ QStateHandler

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

Pointer to a state-handler function.

Definition at line 210 of file qep.h.

◆ QActionHandler

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

Pointer to an action-handler function.

Definition at line 213 of file qep.h.

◆ QXThreadHandler

typedef void(* QXThreadHandler) (QXThread *const me)

Pointer to a thread-handler function.

Definition at line 216 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 597 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 713 of file qep.h.

Function Documentation

◆ QHsm_init_()

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

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

Description
Executes the top-most initial transition in a HSM.
Parameters
[in,out]mepointer (see Object Orientation)
[in]epointer to an extra parameter (might be NULL)
[in]qs_idQS-id of this state machine (for QS local filter)
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 158 of file qep_hsm.c.

◆ QHsm_dispatch_()

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

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
[in]qs_idQS-id of this state machine (for QS local filter)
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 271 of file qep_hsm.c.

◆ QHsm_getStateHandler_()

QStateHandler QHsm_getStateHandler_ ( QHsm *const  me)

Implementation of getting the state handler in a QHsm subclass

Definition at line 583 of file qep_hsm.c.

Variable Documentation

◆ QP_versionStr

char_t const QP_versionStr[7]
extern

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

Definition at line 53 of file qep_hsm.c.