QP-nano  6.9.0
Real-Time Embedded Framework
qepn.h File Reference

Public QEP-nano interface. More...

Go to the source code of this file.

Data Structures

struct  QEvt
 
struct  QHsm
 
struct  QHsmVtable
 

Macros

#define QP_VERSION   690U
 
#define QP_VERSION_STR   "6.9.0"
 
#define QP_RELEASE   0x884D22FDU
 
#define Q_SIG(me_)   (((QHsm *)(me_))->evt.sig)
 
#define Q_PAR(me_)   (((QHsm *)(me_))->evt.par)
 
#define QHSM_INIT(me_)
 
#define QHSM_DISPATCH(me_)   ((*(me_)->vptr->dispatch)((me_)))
 
#define QHsm_state(me_)   (Q_STATE_CAST(Q_HSM_UPCAST(me_)->state))
 
#define Q_RET_SUPER   ((QState)0)
 
#define Q_RET_SUPER_SUB   ((QState)1)
 
#define Q_RET_UNHANDLED   ((QState)2)
 
#define Q_RET_HANDLED   ((QState)3)
 
#define Q_RET_IGNORED   ((QState)4)
 
#define Q_RET_ENTRY   ((QState)5)
 
#define Q_RET_EXIT   ((QState)6)
 
#define Q_RET_NULL   ((QState)7)
 
#define Q_RET_TRAN   ((QState)8)
 
#define Q_RET_TRAN_INIT   ((QState)9)
 
#define Q_RET_TRAN_HIST   ((QState)10)
 
#define Q_HSM_UPCAST(ptr_)   ((QHsm *)(ptr_))
 
#define Q_STATE_CAST(handler_)   ((QStateHandler)(handler_))
 
#define Q_TRAN(target_)    ((Q_HSM_UPCAST(me))->temp = Q_STATE_CAST(target_), (QState)Q_RET_TRAN)
 
#define Q_TRAN_HIST(hist_)    ((Q_HSM_UPCAST(me))->temp = (hist_), (QState)Q_RET_TRAN_HIST)
 
#define Q_SUPER(super_)    ((Q_HSM_UPCAST(me))->temp = Q_STATE_CAST(super_), Q_RET_SUPER)
 
#define Q_HANDLED()   Q_RET_HANDLED
 
#define Q_UNHANDLED()   Q_RET_UNHANDLED
 
#define Q_ENTRY_SIG   ((QSignal)1)
 
#define Q_EXIT_SIG   ((QSignal)2)
 
#define Q_INIT_SIG   ((QSignal)3)
 
#define Q_TIMEOUT_SIG   ((QSignal)4)
 
#define Q_TIMEOUT1_SIG   ((QSignal)5)
 
#define Q_TIMEOUT2_SIG   ((QSignal)6)
 
#define Q_TIMEOUT3_SIG   ((QSignal)7)
 
#define Q_USER_SIG   ((QSignal)8)
 
#define Q_UINT2PTR_CAST(type_, uintptr_)   ((type_ *)(uintptr_))
 
#define Q_ROM
 
#define Q_ROM_BYTE(rom_var_)   (rom_var_)
 Some compilers for Harvard-architecture MCUs, such as gcc for AVR, do not generate correct code for accessing data allocated in the program space (ROM). More...
 
#define Q_ROM_PTR(rom_var_)   (rom_var_)
 Some compilers for Harvard-architecture MCUs, such as gcc for AVR, do not generate correct code for accessing data allocated in the program space (ROM). More...
 
#define QP_getVersion()   (QP_versionStr)
 

Typedefs

typedef char char_t
 
typedef int int_t
 
typedef int enum_t
 
typedef float float32_t
 
typedef double float64_t
 
typedef uint8_t QSignal
 
typedef uint16_t QParam
 
typedef uint_fast8_t QState
 
typedef QState(* QStateHandler) (void *const me)
 

Functions

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

Variables

char_t const Q_ROM QP_versionStr [7]
 

Data Structure Documentation

◆ QEvt

struct QEvt

Event structure.

Description
QEvt represents events, optionally with a single scalar parameter.
See also
Q_PARAM_SIZE
QParam

Definition at line 131 of file qepn.h.

Data Fields
QSignal sig

signal of the event

QParam par

scalar parameter of the event

Macro Definition Documentation

◆ QP_VERSION

#define QP_VERSION   690U

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 qepn.h.

◆ QP_VERSION_STR

#define QP_VERSION_STR   "6.9.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 54 of file qepn.h.

◆ QP_RELEASE

#define QP_RELEASE   0x884D22FDU

Encrypted current QP release (6.9.0) and date (2020-08-21)

Definition at line 57 of file qepn.h.

◆ Q_SIG

#define Q_SIG (   me_)    (((QHsm *)(me_))->evt.sig)

Macro to access the signal of the current event of a state machine

Parameters
[in,out]me_pointer to a subclass of QHsm (see Object Orientation)

Definition at line 143 of file qepn.h.

◆ Q_PAR

#define Q_PAR (   me_)    (((QHsm *)(me_))->evt.par)

Macro to access the parameter of the current event of a state machine

Parameters
[in,out]me_pointer to a subclass of QHsm (see Object Orientation)

Definition at line 150 of file qepn.h.

◆ QHSM_INIT

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

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

Parameters
[in,out]me_pointer (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 "qpn.h" /* QP-nano */
#include "calc.h" /* Application interface */
static Calc l_calc; /* an instance of Calc HSM */
int main() {
Calc_ctor(&l_calc); /* Calc HSM "constructor" invokes QHsm_ctor() */
QHSM_INIT(&l_calc.super); /* trigger initial transition, late biniding */
for (;;) { /* event loop */
. . .
/* wait for the next event and assign it to the current event */
QSIG(&l_calc) = ...
QPAR(&l_calc) = ...
QHSM_DISPATCH(&l_calc.super); /* dispatch the event, late binding */
}
return 0;
}
#define Q_DEFINE_THIS_FILE
Definition: qassert.h:109
#define QHSM_DISPATCH(me_)
Definition: qepn.h:224
#define QHSM_INIT(me_)
Definition: qepn.h:210
QP-nano public interface including backwards-compatibility layer.

Definition at line 210 of file qepn.h.

◆ QHSM_DISPATCH

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

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)
Note
Must be called after the "constructor" and after QHSM_INIT().

Definition at line 224 of file qepn.h.

◆ QHsm_state

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

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

Parameters
[in]me_pointer (see Object Orientation)
Returns
the current active state of a HSM

Definition at line 238 of file qepn.h.

◆ Q_RET_SUPER

#define Q_RET_SUPER   ((QState)0)

event passed to superstate to handle

Definition at line 278 of file qepn.h.

◆ Q_RET_SUPER_SUB

#define Q_RET_SUPER_SUB   ((QState)1)

event passed to submachine superstate

Definition at line 281 of file qepn.h.

◆ Q_RET_UNHANDLED

#define Q_RET_UNHANDLED   ((QState)2)

event unhandled due to a guard

Definition at line 284 of file qepn.h.

◆ Q_RET_HANDLED

#define Q_RET_HANDLED   ((QState)3)

event handled (internal transition)

Definition at line 288 of file qepn.h.

◆ Q_RET_IGNORED

#define Q_RET_IGNORED   ((QState)4)

event silently ignored (bubbled up to top)

Definition at line 291 of file qepn.h.

◆ Q_RET_ENTRY

#define Q_RET_ENTRY   ((QState)5)

state entry action executed

Definition at line 295 of file qepn.h.

◆ Q_RET_EXIT

#define Q_RET_EXIT   ((QState)6)

state exit action executed

Definition at line 298 of file qepn.h.

◆ Q_RET_NULL

#define Q_RET_NULL   ((QState)7)

return value without any effect

Definition at line 302 of file qepn.h.

◆ Q_RET_TRAN

#define Q_RET_TRAN   ((QState)8)

event handled (regular transition)

Definition at line 306 of file qepn.h.

◆ Q_RET_TRAN_INIT

#define Q_RET_TRAN_INIT   ((QState)9)

initial transition in a state or submachine

Definition at line 309 of file qepn.h.

◆ Q_RET_TRAN_HIST

#define Q_RET_TRAN_HIST   ((QState)10)

event handled (transition to history)

Definition at line 312 of file qepn.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 328 of file qepn.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 Alarm_ctor(Alarm * const me) {
QHsm_ctor(&me->super, Q_STATE_CAST(&Alarm_initial));
}
#define Q_STATE_CAST(handler_)
Definition: qepn.h:340
void QHsm_ctor(QHsm *const me, QStateHandler initial)
Definition: qepn.c:84

Definition at line 340 of file qepn.h.

◆ Q_TRAN

#define Q_TRAN (   target_)     ((Q_HSM_UPCAST(me))->temp = 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 to both HSMs and FSMs.

/* HSM definition ----------------------------------------------------------*/
QState Pelican_carsGreenNoPed(Pelican * const me) {
QState status_;
switch (Q_SIG(me)) {
case Q_ENTRY_SIG: {
BSP_showState(me->super.prio, "carsGreenNoPed");
status_ = Q_HANDLED();
break;
}
case PEDS_WAITING_SIG: {
status_ = Q_TRAN(&Pelican_carsGreenPedWait);
break;
}
case Q_TIMEOUT_SIG: {
status_ = Q_TRAN(&Pelican_carsGreenInt);
break;
}
default: {
status_ = Q_SUPER(&Pelican_carsGreen);
break;
}
}
return status_;
}
/*..........................................................................*/
QState Pelican_carsGreenPedWait(Pelican * const me) {
QState status_;
switch (Q_SIG(me)) {
case Q_ENTRY_SIG: {
BSP_showState(me->super.prio, "carsGreenPedWait");
status_ = Q_HANDLED();
break;
}
case Q_TIMEOUT_SIG: {
status_ = Q_TRAN(&Pelican_carsYellow);
break;
}
default: {
status_ = Q_SUPER(&Pelican_carsGreen);
break;
}
}
return status_;
}
#define Q_HANDLED()
Definition: qepn.h:370
#define Q_TRAN(target_)
Definition: qepn.h:346
#define Q_SIG(me_)
Definition: qepn.h:143
#define Q_ENTRY_SIG
Definition: qepn.h:382
uint_fast8_t QState
Definition: qepn.h:155
#define Q_SUPER(super_)
Definition: qepn.h:364
#define Q_TIMEOUT_SIG
Definition: qepn.h:391

Definition at line 346 of file qepn.h.

◆ Q_TRAN_HIST

#define Q_TRAN_HIST (   hist_)     ((Q_HSM_UPCAST(me))->temp = (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) {
QState status_;
switch (Q_SIG(me)) {
~ ~ ~
case Q_EXIT_SIG: {
me->hist_doorClosed = QHsm_state(&me->super);
status_ = Q_HANDLED();
break;
}
}
return status_;
}
/*..........................................................*/
static QState ToastOven_doorOpen(ToastOven * const me) {
QState status_;
switch (Q_SIG(me)) {
~ ~ ~
case CLOSE_SIG: {
status_ = Q_TRAN_HIST(hist_doorClosed); /*<== */
break;
}
default: {
status_ = Q_SUPER(&QHsm_top);
break;
}
}
return status_;
}
#define Q_EXIT_SIG
Definition: qepn.h:385
#define QHsm_state(me_)
Definition: qepn.h:238
QState(* QStateHandler)(void *const me)
Definition: qepn.h:158
#define Q_TRAN_HIST(hist_)
Definition: qepn.h:355
Definition: qepn.h:183
QState QHsm_top(void const *const me)
Definition: qepn.c:172

Definition at line 355 of file qepn.h.

◆ Q_SUPER

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

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

Usage
/* HSM definition ----------------------------------------------------------*/
QState Pelican_carsGreenNoPed(Pelican * const me) {
QState status_;
switch (Q_SIG(me)) {
case Q_ENTRY_SIG: {
BSP_showState(me->super.prio, "carsGreenNoPed");
status_ = Q_HANDLED();
break;
}
case PEDS_WAITING_SIG: {
status_ = Q_TRAN(&Pelican_carsGreenPedWait);
break;
}
case Q_TIMEOUT_SIG: {
status_ = Q_TRAN(&Pelican_carsGreenInt);
break;
}
default: {
status_ = Q_SUPER(&Pelican_carsGreen);
break;
}
}
return status_;
}
/*..........................................................................*/
QState Pelican_carsGreenPedWait(Pelican * const me) {
QState status_;
switch (Q_SIG(me)) {
case Q_ENTRY_SIG: {
BSP_showState(me->super.prio, "carsGreenPedWait");
status_ = Q_HANDLED();
break;
}
case Q_TIMEOUT_SIG: {
status_ = Q_TRAN(&Pelican_carsYellow);
break;
}
default: {
status_ = Q_SUPER(&Pelican_carsGreen);
break;
}
}
return status_;
}

Definition at line 364 of file qepn.h.

◆ Q_HANDLED

#define Q_HANDLED ( )    Q_RET_HANDLED

Macro to call in a state-handler when it handles an event. Applicable to both HSMs and FSMs.

Definition at line 370 of file qepn.h.

◆ Q_UNHANDLED

#define Q_UNHANDLED ( )    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 HSMs.

Definition at line 376 of file qepn.h.

◆ Q_ENTRY_SIG

#define Q_ENTRY_SIG   ((QSignal)1)

QP reserved signals

signal for coding entry actions

Definition at line 382 of file qepn.h.

◆ Q_EXIT_SIG

#define Q_EXIT_SIG   ((QSignal)2)

signal for coding exit actions

Definition at line 385 of file qepn.h.

◆ Q_INIT_SIG

#define Q_INIT_SIG   ((QSignal)3)

signal for coding nested initial transitions

Definition at line 388 of file qepn.h.

◆ Q_TIMEOUT_SIG

#define Q_TIMEOUT_SIG   ((QSignal)4)

timeout signal at the default tick rate 0

Definition at line 391 of file qepn.h.

◆ Q_TIMEOUT1_SIG

#define Q_TIMEOUT1_SIG   ((QSignal)5)

timeout signal at tick rate 1

Definition at line 394 of file qepn.h.

◆ Q_TIMEOUT2_SIG

#define Q_TIMEOUT2_SIG   ((QSignal)6)

timeout signal at tick rate 2

Definition at line 397 of file qepn.h.

◆ Q_TIMEOUT3_SIG

#define Q_TIMEOUT3_SIG   ((QSignal)7)

timeout signal at tick rate 3 first signal for the user applications

Definition at line 402 of file qepn.h.

◆ Q_USER_SIG

#define Q_USER_SIG   ((QSignal)8)

Definition at line 403 of file qepn.h.

◆ Q_UINT2PTR_CAST

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

Perform cast from unsigned integer to a pointer of type type_@par 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 413 of file qepn.h.

◆ Q_ROM

#define Q_ROM

Macro to specify compiler-specific directive for placing a constant object in ROM.

Description
Many compilers for 8-bit Harvard-architecture MCUs provide non-standard extensions to support placement of objects in different memories. In order to conserve the precious RAM, QP-nano uses the Q_ROM macro for all constant objects that can be allocated in ROM.
Note
To override the following empty definition, you need to define the Q_ROM macro in the qpn_port.h header file. Some examples of valid Q_ROM macro definitions are: __code (IAR 8051 compiler), code (Keil 8051 compiler), PROGMEM (gcc for AVR), __flash (IAR for AVR).

Definition at line 434 of file qepn.h.

◆ Q_ROM_BYTE

#define Q_ROM_BYTE (   rom_var_)    (rom_var_)

Macro to access a byte allocated in ROM The workaround for such compilers is to explicitly add assembly code to access each data element allocated in the program space. The macro Q_ROM_BYTE() retrieves a byte from the given ROM address.

Note
The Q_ROM_BYTE() macro should be defined in the qpn_port.h header file for each compiler that cannot handle correctly data allocated in ROM (such as the gcc). If the macro is left undefined, the default definition simply returns the parameter and lets the compiler synthesize the correct code.

Definition at line 454 of file qepn.h.

◆ Q_ROM_PTR

#define Q_ROM_PTR (   rom_var_)    (rom_var_)

Macro to access a pointer allocated in ROM The workaround for such compilers is to explicitly add assembly code to access each data element allocated in the program space. The macro Q_ROM_PTR() retrieves an object-pointer from the given ROM address. Please note that the pointer can be pointing to the object in RAM or ROM.

Note
The Q_ROM_PTR() macro should be defined in the qpn_port.h header file for each compiler that cannot handle correctly data allocated in ROM (such as the gcc). If the macro is left undefined, the default definition simply returns the parameter and lets the compiler synthesize the correct code.

Definition at line 475 of file qepn.h.

◆ QP_getVersion

#define QP_getVersion ( )    (QP_versionStr)

get the current QP-nano version number string of the form "X.Y.Z"

Definition at line 484 of file qepn.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 qepn.h.

◆ int_t

typedef int int_t

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

Definition at line 73 of file qepn.h.

◆ enum_t

typedef int enum_t

typedef for enumerations used for event signals

Definition at line 76 of file qepn.h.

◆ float32_t

typedef float float32_t

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

Note
QP-nano does not use floating-point types anywhere in the internal implementation.

Definition at line 83 of file qepn.h.

◆ float64_t

typedef double float64_t

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

Note
QP-nano does not use floating-point types anywhere in the internal implementation.

Definition at line 90 of file qepn.h.

◆ QSignal

typedef uint8_t QSignal

Scalar type describing the signal of an event.

Definition at line 93 of file qepn.h.

◆ QParam

typedef uint16_t QParam

Definition at line 103 of file qepn.h.

◆ QState

Type returned from a state-handler function.

Definition at line 155 of file qepn.h.

◆ QStateHandler

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

the signature of a state handler function

Definition at line 158 of file qepn.h.

Function Documentation

◆ QHsm_childState_()

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

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

Variable Documentation

◆ QP_versionStr

char_t const Q_ROM QP_versionStr[7]
extern

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

Definition at line 47 of file qepn.c.