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

Public QEP/C interface. More...

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   700U
 
#define QP_VERSION_STR   "7.0.0"
 
#define QP_RELEASE   0x7CCAAA13U
 
#define Q_SIGNAL_SIZE   2U
 
#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 QHSM_INIT(me_, par_, qs_id_)
 
#define QHSM_DISPATCH(me_, e_, qs_id_)    ((*(me_)->vptr->dispatch)((me_), (e_), (qs_id_)))
 
#define Q_HSM_UPCAST(ptr_)   ((QHsm *)(ptr_))
 
#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 signed int int_t
 
typedef signed 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 }
 

Variables

char const QP_versionStr [7]
 

Detailed Description

Date
Last updated on: 2021-12-23
Version
Last updated for: Version 7.0.0, 2022-04-30
Traceability:

traces to: RQP001

traces to: RQP101

Definition in file qep.h.

Macro Definition Documentation

◆ QP_VERSION

#define QP_VERSION   700U

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

◆ QP_VERSION_STR

#define QP_VERSION_STR   "7.0.0"

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

◆ QP_RELEASE

#define QP_RELEASE   0x7CCAAA13U

Encrypted current QP release (7.0.0) and date (2022-01-31)

Definition at line 51 of file qep.h.

◆ Q_SIGNAL_SIZE

#define Q_SIGNAL_SIZE   2U

Definition at line 83 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_

QEvt represents events without parameters and serves as the base class This macro encapsulates the downcast of QEvt pointers, which violates MISRA-C 2012 Rule 11.3(R) "A cast shall not be performed between a pointer to object type and a pointer to a different object type". This macro helps to localize this deviation.

Traceability:

traces to: RQP003

traces to: PQA11_3

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

This macro encapsulates the cast to (type_ *), which QP ports or application might use to access embedded hardware registers.

Definition at line 166 of file qep.h.

◆ Q_STATE_CAST

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

Perform cast to QStateHandler.

This macro encapsulates the cast of a specific state handler function pointer to QStateHandler, which violates MISRA:C-2012 Rule 11.1(req) "Conversions shall not be performed between a pointer to function and any other type". This macro helps to localize this deviation.

Traceability:

traces to: PQP11_1

traces to: PQA11_1

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:196
void QHsm_ctor(QHsm *const me, QStateHandler initial)
Definition: qep_hsm.c:139

Definition at line 196 of file qep.h.

◆ Q_ACTION_CAST

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

Perform cast to QActionHandler.

This macro encapsulates the cast of a specific action handler function pointer to QActionHandler, which violates MISRA:C-2012 Rule 11.1(R) "Conversions shall not be performed between a pointer to function and any other type". This macro helps to localize this deviation.

Traceability:

traces to: PQP11_1

traces to: PQA11_1

Definition at line 207 of file qep.h.

◆ QHSM_INIT

#define QHSM_INIT (   me_,
  par_,
  qs_id_ 
)
Value:
do { \
Q_ASSERT((me_)->vptr); \
(*(me_)->vptr->init)((me_), (par_), (qs_id_)); \
} while (false)

Polymorphically executes the top-most initial transition in a HSM

Parameters
[in,out]me_pointer (see oop)
[in]e_constant pointer the QEvt or a class derived from QEvt (see oop)
[in]qs_id_QS local filter ID
Note
Must be called only ONCE after the SM "constructor".
Traceability:
traces to: RQP102
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 Calc_inst; /* an instance of Calc SM */
int main() {
Calc_ctor(&Calc_inst); /* Calc "constructor" invokes QHsm_ctor() */
QMSM_INIT(&Calc_inst.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(&Calc_inst.super, &e); /* dispatch e */
}
return 0;
}
#define Q_DEFINE_THIS_FILE
Definition: qassert.h:87
QP/C public interface including backwards-compatibility layer.
#define QMSM_INIT(me_, e_)
Definition: qpc.h:144
#define QMSM_DISPATCH(me_, e_)
Definition: qpc.h:148
Definition: qep.h:119

Definition at line 296 of file qep.h.

◆ QHSM_DISPATCH

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

Polymorphically dispatches an event to a HSM

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

Parameters
[in,out]me_pointer (see oop)
[in]e_constant pointer the QEvt or a class derived from QEvt (see oop)
Note
Must be called after the "constructor" and after QHSM_INIT().
Traceability:
traces to: RQP102

Definition at line 330 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

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 oop), 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 2012 Rule 11.3(req) "A cast shall not be performed between a pointer to object type and a pointer to a different object type". This macro encapsulates this deviation and provides a descriptive name for the reason of this cast.

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

Traceability:

traces to: RQP103

traces to: RQP120E

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;
}
#define Q_HANDLED()
Definition: qep.h:554
#define Q_TRAN(target_)
Definition: qep.h:526
uint_fast8_t QState
Definition: qep.h:170
#define Q_SUPER(super_)
Definition: qep.h:548
@ Q_ENTRY_SIG
Definition: qep.h:688
QSignal sig
Definition: qep.h:123
QState QHsm_top(void const *const me, QEvt const *const e)
Definition: qep_hsm.c:261

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

Traceability:

traces to: RQP103

traces to: RQP120H

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:176
#define Q_TRAN_HIST(hist_)
Definition: qep.h:537
@ Q_EXIT_SIG
Definition: qep.h:689
Definition: qep.h:253
static QStateHandler QHsm_state(QHsm *const me)
Definition: qep.h:373

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

Traceability:
traces to: RQP103
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 548 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.

Traceability:

traces to: RQP103

traces to: RQP120B

traces to: RQP120C

Definition at line 554 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 560 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 565 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 602 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 608 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 621 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
Definition: qep.h:589
#define Q_HSM_UPCAST(ptr_)
Definition: qep.h:365

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

Definition at line 627 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
Definition: qep.h:590

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

Definition at line 633 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_))), \
@ Q_RET_TRAN_HIST
Definition: qep.h:594

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

Definition at line 639 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
Definition: qep.h:591

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

Definition at line 647 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_))), \
@ Q_RET_TRAN_XP
Definition: qep.h:595

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

Definition at line 653 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 661 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 668 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 673 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 678 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 subclasses of QP::QMsm.

Definition at line 684 of file qep.h.

Typedef Documentation

◆ int_t

typedef signed int int_t

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

Definition at line 57 of file qep.h.

◆ enum_t

typedef signed int enum_t

typedef for enumerations used for event signals

Definition at line 60 of file qep.h.

◆ float32_t

typedef float float32_t

IEEE 754 32-bit floating point number, MISRA-C 2012 Dir 4.6(A)

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-specific trace records.

Definition at line 68 of file qep.h.

◆ float64_t

typedef double float64_t

IEEE 754 64-bit floating point number, MISRA-C 2012 Dir 4.6(A)

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-specific trace records.

Definition at line 76 of file qep.h.

◆ QSignal

typedef uint16_t QSignal

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

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.

Traceability:
traces to: RQP002A

Definition at line 97 of file qep.h.

◆ QState

typedef uint_fast8_t QState

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

Definition at line 170 of file qep.h.

◆ QStateHandler

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

Pointer to a state-handler function.

Definition at line 176 of file qep.h.

◆ QActionHandler

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

Pointer to an action-handler function.

Definition at line 179 of file qep.h.

◆ QXThreadHandler

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

Pointer to a thread-handler function.

Definition at line 182 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 571 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 687 of file qep.h.

Variable Documentation

◆ QP_versionStr

char const QP_versionStr[7]
extern

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

Definition at line 47 of file qep_hsm.c.