Public QEP-nano interface. More...

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 */

Q_DEFINE_THIS_FILE

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;

}

Q_DEFINE_THIS_FILE
#define Q_DEFINE_THIS_FILE
Definition: qassert.h:109

QHSM_DISPATCH
#define QHSM_DISPATCH(me_)
Definition: qepn.h:224

QHSM_INIT
#define QHSM_INIT(me_)
Definition: qepn.h:210

qpn.h
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));

}

Q_STATE_CAST
#define Q_STATE_CAST(handler_)
Definition: qepn.h:340

QHsm::QHsm_ctor
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_;
}
 

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

}

Q_EXIT_SIG
#define Q_EXIT_SIG
Definition: qepn.h:385

QHsm_state
#define QHsm_state(me_)
Definition: qepn.h:238

QStateHandler
QState(* QStateHandler)(void *const me)
Definition: qepn.h:158

Q_TRAN_HIST
#define Q_TRAN_HIST(hist_)
Definition: qepn.h:355

QHsm
Definition: qepn.h:183

QHsm::QHsm_top
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

typedef uint_fast8_t 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.

Data Structures

Macros

Typedefs

Functions

Variables

Data Structure Documentation

◆ QEvt

Macro Definition Documentation

◆ QP_VERSION

◆ QP_VERSION_STR

◆ QP_RELEASE

◆ Q_SIG

◆ Q_PAR

◆ QHSM_INIT

◆ QHSM_DISPATCH

◆ QHsm_state

◆ 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

◆ Q_HSM_UPCAST

◆ Q_STATE_CAST

◆ Q_TRAN

◆ Q_TRAN_HIST

◆ Q_SUPER

◆ Q_HANDLED

◆ Q_UNHANDLED

◆ Q_ENTRY_SIG

◆ Q_EXIT_SIG

◆ Q_INIT_SIG

◆ Q_TIMEOUT_SIG

◆ Q_TIMEOUT1_SIG

◆ Q_TIMEOUT2_SIG

◆ Q_TIMEOUT3_SIG

◆ Q_USER_SIG

◆ Q_UINT2PTR_CAST

◆ Q_ROM

◆ Q_ROM_BYTE

◆ Q_ROM_PTR

◆ QP_getVersion

Typedef Documentation

◆ char_t

◆ int_t

◆ enum_t

◆ float32_t

◆ float64_t

◆ QSignal

◆ QParam

◆ QState

◆ QStateHandler

Function Documentation

◆ QHsm_childState_()

Variable Documentation

◆ QP_versionStr