QP-nano  6.1.1
qepn.h File Reference

Public QEP-nano interface. More...

Go to the source code of this file.

Data Structures

struct  QEvt
 Event structure. More...
 
struct  QHsm
 Hierarchical State Machine. More...
 
struct  QHsmVtbl
 Virtual table for the QHsm class. More...
 

Macros

#define QP_VERSION   611
 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.1.1"
 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   0x9494E7FCU
 Tamperproof current QP release (6.1.1) and date (2018-02-18)
 
#define Q_SIG(me_)   (((QHsm *)(me_))->evt.sig)
 Macro to access the signal of the current event of a state machine. More...
 
#define Q_PAR(me_)   (((QHsm *)(me_))->evt.par)
 Macro to access the parameter of the current event of a state machine. More...
 
#define QHSM_INIT(me_)   ((*(me_)->vptr->init)((me_)))
 Polymorphically executes the top-most initial transition in a SM. More...
 
#define QHSM_DISPATCH(me_)   ((*(me_)->vptr->dispatch)((me_)))
 Polymorphically dispatches an event to a HSM. More...
 
#define QHsm_state(me_)   (Q_STATE_CAST(Q_HSM_UPCAST(me_)->state))
 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 Q_HSM_UPCAST(ptr_)   ((QHsm *)(ptr_))
 Perform upcast from a subclass of QHsm to the base class QHsm. More...
 
#define Q_STATE_CAST(handler_)   ((QStateHandler)(handler_))
 Perform cast to QStateHandler. More...
 
#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. More...
 
#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. More...
 
#define Q_SUPER(super_)   ((Q_HSM_UPCAST(me))->temp = 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 Q_UINT2PTR_CAST(type_, uint_)   ((type_ *)(uint_))
 Perform cast from unsigned integer to a pointer of type type_. More...
 
#define Q_ROM
 Macro to specify compiler-specific directive for placing a constant object in ROM. More...
 
#define Q_ROM_BYTE(rom_var_)   (rom_var_)
 Macro to access a byte allocated in ROM. More...
 
#define Q_ROM_PTR(rom_var_)   (rom_var_)
 Macro to access a pointer allocated in ROM. More...
 
#define QP_getVersion()   (QP_versionStr)
 get the current QP-nano version number string of the form "X.Y.Z"
 
#define Q_DIM(array_)   (sizeof(array_) / sizeof((array_)[0]))
 Helper macro to calculate static dimension of a 1-dim array array_.
 

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 uint8_t QSignal
 Scalar type describing the signal of an event. More...
 
typedef uint16_t QParam
 
typedef uint_fast8_t QState
 Type returned from a state-handler function. More...
 
typedef QState(* QStateHandler) (void *const me)
 the signature of a state handler function
 

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_HIST
}
 All possible values returned from state/action handlers. More...
 
enum  {
  Q_ENTRY_SIG = 1, Q_EXIT_SIG, Q_INIT_SIG, Q_TIMEOUT_SIG,
  Q_TIMEOUT1_SIG, Q_TIMEOUT2_SIG, Q_TIMEOUT3_SIG, Q_USER_SIG
}
 QP reserved signals. More...
 

Functions

void QHsm_ctor (QHsm *const me, QStateHandler initial)
 protected "constructor" of a HSM. More...
 
QStateHandler QHsm_childState_ (QHsm *const me, QStateHandler const parent)
 Helper function to obtain the current active child state of a parent. More...
 
void QHsm_init_ (QHsm *const me)
 Implementation of the top-most initial transition in QHsm. More...
 
void QHsm_dispatch_ (QHsm *const me)
 Implementation of dispatching events to QHsm. More...
 
QState QHsm_top (void const *const me)
 the top-state. More...
 

Variables

char_t const Q_ROM QP_versionStr [6]
 the current QP version number string in ROM, based on QP_VERSION_STR
 

Detailed Description

Public QEP-nano interface.

Definition in file qepn.h.


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 128 of file qepn.h.

Data Fields
QSignal sig signal of the event
QParam par scalar parameter of the event

◆ QHsm

struct QHsm

Hierarchical State Machine.

Description
QHsm represents a Hierarchical Finite State Machine (HSM) with full support for hierarchical nesting of states, entry/exit actions, and initial transitions in any composite state.
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; /* inherits QHsm */
double operand1;
double operand2;
char display[DISP_WIDTH + 1];
uint8_t len;
uint8_t opKey;
} Calc;
See also
Object Orientation

Definition at line 180 of file qepn.h.

Data Fields
QHsmVtbl const * vptr virtual pointer
QStateHandler state current active state (state-variable)
QStateHandler temp temporary: tran.

chain, target state, etc.

QEvt evt currently processed event in the HSM (protected)

Macro Definition Documentation

◆ 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 140 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 147 of file qepn.h.

◆ QHSM_INIT

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

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;
}

Definition at line 207 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 218 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 230 of file qepn.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 239 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 294 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 Pelican_ctor(Pelican * const me, uint8_t timeout) {
QActive_ctor(&me->super, Q_STATE_CAST(&Pelican_initial));
me->pedFlashCtr = timeout;
}

Definition at line 306 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_;
}

Definition at line 312 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_;
}

Definition at line 321 of file qepn.h.

◆ Q_SUPER

#define Q_SUPER (   super_)    ((Q_HSM_UPCAST(me))->temp = 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 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 330 of file qepn.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 336 of file qepn.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 HSMs.

Definition at line 342 of file qepn.h.

◆ Q_UINT2PTR_CAST

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

Perform cast from unsigned integer to a 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 365 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 386 of file qepn.h.

◆ Q_ROM_BYTE

#define Q_ROM_BYTE (   rom_var_)    (rom_var_)

Macro to access a byte allocated in ROM.

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). 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 406 of file qepn.h.

◆ Q_ROM_PTR

#define Q_ROM_PTR (   rom_var_)    (rom_var_)

Macro to access a pointer allocated in ROM.

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). 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 427 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.

◆ 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.

◆ QState

Type returned from a state-handler function.

Definition at line 152 of file qepn.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

All possible values returned from state/action handlers.

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 

event handled (regular transition)

Q_RET_TRAN_INIT 

initial transition in a state or submachine

Q_RET_TRAN_HIST 

event handled (transition to history)

Definition at line 258 of file qepn.h.

◆ anonymous enum

anonymous enum

QP 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 nested initial transitions

Q_TIMEOUT_SIG 

timeout signal at the default tick rate 0

Q_TIMEOUT1_SIG 

timeout signal at tick rate 1

Q_TIMEOUT2_SIG 

timeout signal at tick rate 2

Q_TIMEOUT3_SIG 

timeout signal at tick rate 3

Q_USER_SIG 

first signal for the user applications

Definition at line 346 of file qepn.h.

Function Documentation

◆ QHsm_ctor()

void QHsm_ctor ( QHsm *const  me,
QStateHandler  initial 
)

protected "constructor" of a HSM.

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 Pelican_ctor(Pelican * const me, uint8_t timeout) {
QActive_ctor(&me->super, Q_STATE_CAST(&Pelican_initial));
me->pedFlashCtr = timeout;
}

Definition at line 83 of file qepn.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 445 of file qepn.c.

◆ QHsm_init_()

void QHsm_init_ ( QHsm *const  me)

Implementation of the top-most initial transition in QHsm.

Description
Executes the top-most initial transition in a HSM.
Parameters
[in,out]mepointer (see Object Orientation)
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 103 of file qepn.c.

◆ QHsm_dispatch_()

void QHsm_dispatch_ ( QHsm *const  me)

Implementation of dispatching events to QHsm.

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)
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 186 of file qepn.c.

◆ QHsm_top()

QState QHsm_top ( void const *const  me)

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)
Returns
Always returns Q_RET_IGNORED, which means that the top state ignores all events.
Note
The parameter me to this state handler is not used. It is provided for conformance with the state-handler function signature QStateHandler.

Definition at line 169 of file qepn.c.