QP/C Framework platform-independent public interface. More...

Classes
class	QEvtPtr
	Event class. More...
struct	QMState
	State object for the QMsm class (QM State Machine). More...
struct	QMTranActTable
	Transition-Action Table for the QMsm State Machine. More...
union	QAsmAttr
	Attribute of for the QAsm class (Abstract State Machine). More...
class	QAsm
	Abstract State Machine class (state machine interface). More...
struct	QAsmVtable
	Virtual table for the QAsm class. More...
class	QHsm
	Hierarchical State Machine class (QHsm-style state machine implementation strategy). More...
class	QMsm
	Hierarchical State Machine class (QMsm-style state machine implementation strategy). More...
class	QPSet
	Set of Active Objects of up to QF_MAX_ACTIVE elements. More...
struct	QSubscrList
	Subscriber List (for publish-subscribe). More...
class	QActive
	Active object class (based on the QHsm implementation strategy). More...
class	QMActive
	Active object class (based on QMsm implementation strategy). More...
class	QTimeEvt
	Time Event class. More...
class	QTicker
	"Ticker" Active Object class More...

Macros
#define	QP_VERSION_STR "8.1.3"
	Version string complying with Software Versioning specification.
#define	QP_VERSION 813U
	Version number for internal use (must correspond to QP_VERSION_STR).
#define	QP_RELEASE 0x64D7FC82U
	Encrypted current QP version and release date for internal use.
#define	Q_UNUSED_PAR(par_)
	Helper macro to mark unused parameters of functions.
#define	Q_DIM(array_)
	Helper macro to calculate static dimension of a 1-dim array.
#define	Q_UINT2PTR_CAST(type_, uint_)
	Perform cast from unsigned integer uint_ to pointer of type type_.
#define	QEVT_INITIALIZER(sig_)
	Initializer for QEvt instances (base class).
#define	QEVT_DYNAMIC ((uint8_t)0)
	Dummy parameter for dynamic event initialization (see QEvt::QEvt_init()).
#define	Q_EVT_CAST(class_)
	Perform downcast of an event onto a subclass of QEvt class_.
#define	Q_USER_SIG ((enum_t)4)
	Offset for the user signals (QP/C Application).
#define	Q_STATE_CAST(handler_)
	Perform cast to QStateHandler.
#define	Q_ACTION_CAST(action_)
	Perform cast to QActionHandler.
#define	Q_ACTION_NULL ((QActionHandler)0)
	Macro to provide strictly-typed zero-action to terminate action lists in the transition-action-tables.
#define	Q_RET_SUPER ((QState)0U)
#define	Q_RET_UNHANDLED ((QState)1U)
#define	Q_RET_HANDLED ((QState)2U)
#define	Q_RET_TRAN ((QState)3U)
#define	Q_RET_TRAN_HIST ((QState)4U)
#define	Q_RET_IGNORED ((QState)5U)
#define	Q_RET_ENTRY ((QState)6U)
#define	Q_RET_EXIT ((QState)7U)
#define	Q_RET_TRAN_INIT ((QState)8U)
#define	Q_EMPTY_SIG ((QSignal)0U)
	Reserved signal sent to state handler to execute the default case.
#define	Q_ENTRY_SIG ((QSignal)1U)
	Reserved signal sent to state handler to execute the entry case.
#define	Q_EXIT_SIG ((QSignal)2U)
	Reserved signal sent to state handler to execute the exit case.
#define	Q_INIT_SIG ((QSignal)3U)
	Reserved signal sent to state handler to execute the initial transition.
#define	QASM_INIT(me_, par_, qsId_)
	Virtual call to the top-most initial transition in a state machine.
#define	QASM_DISPATCH(me_, e_, qsId_)
	Virtual call to dispatch an event to a state machine.
#define	QASM_IS_IN(me_, stateHndl_)
	Virtual call to check whether a state machine is in a given state.
#define	QASM_GET_STATE_HANDLER(me_)
	Virtual call to obtain the current state-handler of a state machine.
#define	Q_ASM_UPCAST(ptr_)
	Perform upcasting from a subclass of QAsm to the base class QAsm.
#define	Q_HSM_UPCAST(ptr_)
	Perform upcasting from a subclass of QHsm to the base class QHsm.
#define	Q_TRAN(target_)
	Take transition to the specified target_ state.
#define	Q_TRAN_HIST(hist_)
	Take transition to the specified history of a given state. Applicable only to HSMs.
#define	Q_SUPER(super_)
	Designates the superstate of a given state. Applicable only to QHsm subclasses.
#define	Q_HANDLED()
	Indicate that an action has been "handled." Applies to entry/exit actions and internal transitions.
#define	Q_UNHANDLED()
	Indicate that an internal transition has been "unhandled" due to a guard condition.
#define	Q_MSM_UPCAST(ptr_)
	Perform upcasting from a subclass of QMsm to the base class QMsm.
#define	QM_ENTRY(state_)
	Macro to call in a QM action-handler when it executes an entry action. Applicable only to QMsm subclasses.
#define	QM_EXIT(state_)
	Macro to call in a QM action-handler when it executes an exit action. Applicable only to QMsm subclasses.
#define	QM_TRAN(tatbl_)
	Macro to call in a QM state-handler when it executes a regular transition. Applicable only to QMsm subclasses.
#define	QM_TRAN_INIT(tatbl_)
	Macro to call in a QM state-handler when it executes an initial transition. Applicable only to QMsm subclasses.
#define	QM_TRAN_HIST(history_, tatbl_)
	Macro to call in a QM state-handler when it executes a transition to history. Applicable only to QMsm subclasses.
#define	QM_HANDLED()
	Macro to call in a QM state-handler when it handled an event. Applicable only to QMsm subclasses.
#define	QM_UNHANDLED()
	Indicate that an internal transition has been "unhandled" due to a guard condition. Applicable only to QMsm subclasses.
#define	QM_SUPER()
	Macro to call in a QM state-handler when it designates the superstate to handle an event. Applicable only to ::QMSMs.
#define	QM_STATE_NULL ((QMState *)0)
#define	Q_ACTIVE_UPCAST(ptr_)
	Perform upcasting from a subclass of QActive to the base class QActive.
#define	QF_NO_MARGIN ((uint_fast16_t)0xFFFFU)
	Special value of margin that causes asserting failure in case event allocation or event posting fails.
#define	Q_NEW(evtT_, sig_, ...)
	Allocate a mutable (dynamic) event.
#define	Q_NEW_X(evtT_, margin_, sig_, ...)
	Non-asserting allocate a mutable (dynamic) event.
#define	Q_NEW_REF(evtRef_, evtT_)
	Create a new reference of the current event e.
#define	Q_DELETE_REF(evtRef_)
	Delete the event reference.
#define	QACTIVE_POST(me_, e_, sender_)
	Invoke the direct event posting facility QActive_post_().
#define	QACTIVE_POST_X(me_, e_, margin_, sender_)
	Invoke the direct event posting facility QActive_post_() without delivery guarantee.
#define	QACTIVE_PUBLISH(e_, sender_)
	Publish an event to all subscriber Active Objects.
#define	QTIMEEVT_TICK_X(tickRate_, sender_)
	Invoke the system clock tick processing QTimeEvt_tick_().
#define	QTICKER_TRIG(ticker_, sender_)
	Asynchronously trigger the QTicker AO to perform tick processing.
#define	QACTIVE_POST_LIFO(me_, e_)
	Post an event to an active object using the Last-In-First-Out (LIFO) policy.
#define	QTIMEEVT_TICK(sender_)
	Invoke the system clock tick processing for tick rate 0.

Typedefs
typedef int	int_t
	Alias for assertion-ID numbers in QP assertions and return from QF_run().
typedef int	enum_t
typedef uint16_t	QSignal
	The signal of event QEvt.
typedef QEvt const *	QEvtPtr
	Pointer to const event instances passed around in QP/C Framework.
typedef uint_fast8_t	QState
	Type returned from state-handler functions.
typedef QState(*	QStateHandler) (void const me, QEvt const const e)
	Pointer to a state-handler function.
typedef QState(*	QActionHandler) (void *const me)
	Pointer to an action-handler function.
typedef void(*	QXThreadHandler) (struct QXThread *const me)
	Pointer to an extended-thread handler function.
typedef uint16_t	QPrioSpec
	Priority specification for Active Objects in QP.
typedef uint32_t	QTimeEvtCtr
	Data type to store the block-size defined based on the macro QF_TIMEEVT_CTR_SIZE.
typedef uint32_t	QPSetBits
	Bitmask for the internal representation of QPSet elements.

Functions
uint_fast8_t	QF_LOG2 (QPSetBits const bitmask)
	Log-base-2 calculation when hardware acceleration is NOT provided (QF_LOG2 not defined).
static QPrioSpec	Q_PRIO (uint8_t const prio, uint8_t const pthre)

Variables
char const	QP_versionStr [24]

Detailed Description

QP/C Framework platform-independent public interface.

Forward Traceability

DVR_QP_MC5_D4_8: MISRA-C:2025 Directive 4.8(Advisory): If a pointer to a structure or union is never dereferenced within a translation unit then the implementation of the object should be hidden
DVR_QP_B18_R5_1B: BARR-C:2018 Rule 5.1b: non-anonymous struct/union/enum declared outside typedef

Definition in file qp.h.

Macro Definition Documentation

◆ QP_VERSION_STR

#define QP_VERSION_STR "8.1.3"

Version string complying with Software Versioning specification.

Details
QP_VERSION_STR is a zero-terminated version string in the form MAJOR.MINOR.PATCH compliant with Software Versioning specification.

Examples

7.3.5-rc.1 — version 7.3.5 release-candidate-1
7.3.5 — version 7.3.5 (final release)

Backward Traceability

SCM_SW_VER: Software Versioning

Forward Traceability

Definition at line 33 of file qp.h.

◆ QP_VERSION

#define QP_VERSION 813U

Version number for internal use (must correspond to QP_VERSION_STR).

Details
QP_VERSION is an unsigned integer constant of the form MAJOR|MINOR|PATCH corresponding to QP_VERSION_STR, with digits merged together. For example QP_VERSION_STR == "7.3.5-rc.1" results in QP_VERSION == 735.

Backward Traceability

SCM_SW_VER: Software Versioning

Definition at line 34 of file qp.h.

◆ QP_RELEASE

#define QP_RELEASE 0x64D7FC82U

Encrypted current QP version and release date for internal use.

Details
QP_RELEASE contains information about QP_VERSION (e.g., 735) and release date (e.g., 2023-06-30).

Definition at line 36 of file qp.h.

◆ Q_UNUSED_PAR

#define Q_UNUSED_PAR ( par_ )

Value:

((void)(par_))

Helper macro to mark unused parameters of functions.

Parameters

par_	the unused parameter

Usage

QState QAsm_top(void * const me, QEvt const * const e) {
    Q_UNUSED_PAR(me); // <==
    Q_UNUSED_PAR(e);  // <==
    return Q_RET_IGNORED;
}

Forward Traceability

DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 90 of file qp.h.

◆ Q_DIM

#define Q_DIM ( array_ )

Value:

(sizeof(array_) / sizeof((array_)[0U]))

Helper macro to calculate static dimension of a 1-dim array.

Parameters

array_ 1-dimensional array

Returns: the length of the array (number of elements it can hold)

Usage

static QEvtPtr l_blinkyQSto[10];
QActive_start(AO_Blinky,
    1U,
    l_blinkyQSto,
    Q_DIM(l_blinkyQSto), // <==
    . . .

Forward Traceability

DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 91 of file qp.h.

◆ Q_UINT2PTR_CAST

#define Q_UINT2PTR_CAST	(		type_,
			uint_ )

Value:

((type_ *)(uint_))

Perform cast from unsigned integer uint_ to pointer of type type_.

Details
This macro encapsulates the cast to (type_ *), which QP ports or applications might use to access embedded hardware registers. This macro also helps to encapsulate the MISRA deviations listed in the "Forward Traceability" section.

Parameters

type_	the pointer type to cast the integer onto
uint_	the integer value

Usage

// trigger the ARM Cortex-M PendSV exception

*Q_UINT2PTR_CAST(uint32_t, 0xE000ED04U) = (1U << 28U);

Q_UINT2PTR_CAST

#define Q_UINT2PTR_CAST(type_, uint_)

Perform cast from unsigned integer uint_ to pointer of type type_.

Definition qp.h:92

Forward Traceability

DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)
DVR_QP_B18_R6_3B: BARR-C:2018 Rule 6.3b: unparenthesized macro parameter in definition of macro

Definition at line 92 of file qp.h.

◆ QEVT_INITIALIZER

#define QEVT_INITIALIZER ( sig_ )

Value:

{ \
(QSignal)(sig_), \
(uint8_t)0x00U, \
(uint8_t)0xE0U, \
(uint32_t)0xE0E0E0E0U }

Initializer for QEvt instances (base class).

Details
This macro initializes all attributes of the QEvt base class (including the Duplicate Inverse Storage (DIS) in the SafeQP/C edition). The event is initialized as a static event (NOT coming from any event pool). QP/C Framework will not try to recycle such event instances. Usage

// immutable (const) event without parameters in ROM
static QEvt const immTestEvt = QEVT_INITIALIZER(TEST_SIG);
. . .
QACTIVE_POST(AO_Xyz, &immTestEvt, 0U);
. . .
. . .
typedef struct {
    QEvt super;  // inherit QEvt
    uint8_t id;  // id of the pressed button
} ButtonPressEvt;
. . .
// immutable (const) event with parameters in ROM
static ButtonWorkEvt const immPressEvt = {
    QEVT_INITIALIZER(BUTTON_PRESSED_SIG),
    .id = 123U
};
QACTIVE_POST(AO_Button, &immPressEvt.super, &l_SysTick_Handler);
. . .
// mutable event with parameters
ButtonWorkEvt mutPressEvt = {
    QEVT_INITIALIZER(BUTTON_PRESSED_SIG),
    .id = 123U
};
QACTIVE_POST(AO_Button, &mutPressEvt.super, &l_SysTick_Handler);

Forward Traceability

DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 107 of file qp.h.

◆ QEVT_DYNAMIC

#define QEVT_DYNAMIC ((uint8_t)0)

Dummy parameter for dynamic event initialization (see QEvt::QEvt_init()).

Forward Traceability

Definition at line 138 of file qp.h.

◆ Q_EVT_CAST

#define Q_EVT_CAST ( class_ )

Value:

((class_ const *)(e))

Perform downcast of an event onto a subclass of QEvt class_.

Details
This macro encapsulates the downcast of QEvt pointers. This macro also helps to localize MISRA deviation listed in the "Forward Traceability" section below.

Parameters

class_ a subclass of QEvt

Forward Traceability

DVP_QP_MC5_R11_3B: MISRA-C:2025 Rule 11.3(Required): A cast shall not be performed between a pointer to object type and a pointer to a different object type (object-oriented downcast)
DVP_QP_PCLP_826: PCLP-826: suspicious pointer-to-pointer conversion (area too small)
DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)
DVR_QP_MC5_R11_5: MISRA-C:2025 Rule 11.5(Advisory): A conversion should not be performed from pointer to void into pointer to object
DVR_QP_B18_R6_3B: BARR-C:2018 Rule 6.3b: unparenthesized macro parameter in definition of macro

Definition at line 139 of file qp.h.

◆ Q_USER_SIG

#define Q_USER_SIG ((enum_t)4)

Offset for the user signals (QP/C Application).

Usage
The following example illustrates the use of Q_USER_SIG:

enum AppSignals {
    SOMETHING_HAPPENED_SIG = Q_USER_SIG,
    SOMETHING_ELSE_SIG,
    TIMEOUT_SIG,
    . . .
};

Forward Traceability

Definition at line 173 of file qp.h.

◆ Q_STATE_CAST

#define Q_STATE_CAST ( handler_ )

Value:

((QStateHandler)(handler_))

QStateHandler

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

Pointer to a state-handler function.

Definition qp.h:145

Perform cast to QStateHandler.

Details
This macro encapsulates the cast of a specific state handler function pointer to QStateHandler. This macro also helps to localize MISRA deviations listed in the "Forward Traceability" section below.

Parameters

[in] handler_ specific state-handler function to be cast to the generic QStateHandler

Usage

void Philo_ctor(Philo * const me) {
    QActive_ctor(&me->super, Q_STATE_CAST(&Philo_initial)); // <===
    QTimeEvt_ctorX(&me->timeEvt, me, (enum_t)TIMEOUT_SIG, 0U);
}

Forward Traceability

DVP_QP_MC5_R1_3: MISRA-C:2025 Rule 1.3(Required): There shall be no occurrence of undefined or critical unspecified behavior
DVP_QP_MC5_R11_1: MISRA-C:2025 Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type
DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 175 of file qp.h.

◆ Q_ACTION_CAST

#define Q_ACTION_CAST ( action_ )

Value:

((QActionHandler)(action_))

QActionHandler

QState(* QActionHandler)(void *const me)

Pointer to an action-handler function.

Definition qp.h:146

Perform cast to QActionHandler.

Details
This macro encapsulates the cast of a specific action handler function pointer to QActionHandler. This macro also helps to localize MISRA deviations listed in the "Forward Traceability" section below.

Parameters

[in] action_ specific action-handler function to be cast to the generic QActionHandler

Usage

static QMState const MyStateMachine_s_s = {
    QM_STATE_NULL, // superstate (top)
    Q_STATE_CAST(&MyStateMachine_s),
    Q_ACTION_CAST(&MyStateMachine_s_e), // <===
    Q_ACTION_CAST(&MyStateMachine_s_x), // <===
    Q_ACTION_CAST(&MyStateMachine_s_i)  // <===
};

Forward Traceability

DVP_QP_MC5_R1_3: MISRA-C:2025 Rule 1.3(Required): There shall be no occurrence of undefined or critical unspecified behavior
DVP_QP_MC5_R11_1: MISRA-C:2025 Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type
DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 176 of file qp.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 177 of file qp.h.

◆ Q_RET_SUPER

#define Q_RET_SUPER ((QState)0U)

Definition at line 189 of file qp.h.

◆ Q_RET_UNHANDLED

#define Q_RET_UNHANDLED ((QState)1U)

Definition at line 190 of file qp.h.

◆ Q_RET_HANDLED

#define Q_RET_HANDLED ((QState)2U)

Definition at line 191 of file qp.h.

◆ Q_RET_TRAN

#define Q_RET_TRAN ((QState)3U)

Definition at line 192 of file qp.h.

◆ Q_RET_TRAN_HIST

#define Q_RET_TRAN_HIST ((QState)4U)

Definition at line 193 of file qp.h.

◆ Q_RET_IGNORED

#define Q_RET_IGNORED ((QState)5U)

Definition at line 196 of file qp.h.

◆ Q_RET_ENTRY

#define Q_RET_ENTRY ((QState)6U)

Definition at line 199 of file qp.h.

◆ Q_RET_EXIT

#define Q_RET_EXIT ((QState)7U)

Definition at line 200 of file qp.h.

◆ Q_RET_TRAN_INIT

#define Q_RET_TRAN_INIT ((QState)8U)

Definition at line 201 of file qp.h.

◆ Q_EMPTY_SIG

#define Q_EMPTY_SIG ((QSignal)0U)

Reserved signal sent to state handler to execute the default case.

Forward Traceability

Definition at line 204 of file qp.h.

◆ Q_ENTRY_SIG

#define Q_ENTRY_SIG ((QSignal)1U)

Reserved signal sent to state handler to execute the entry case.

Forward Traceability

Definition at line 205 of file qp.h.

◆ Q_EXIT_SIG

#define Q_EXIT_SIG ((QSignal)2U)

Reserved signal sent to state handler to execute the exit case.

Forward Traceability

Definition at line 206 of file qp.h.

◆ Q_INIT_SIG

#define Q_INIT_SIG ((QSignal)3U)

Reserved signal sent to state handler to execute the initial transition.

Forward Traceability

Definition at line 207 of file qp.h.

◆ QASM_INIT

#define QASM_INIT	(	me_,
		par_,
		qsId_ )

Value:

(*((QAsm *)(me_))->vptr->init)((QAsm *)(me_), (par_), (qsId_))

QAsm

Abstract State Machine class (state machine interface).

Definition qp.h:181

Virtual call to the top-most initial transition in a state machine.

Details

Details
Take the top-most initial transition in a state machine. This virtual call invokes the operation QAsmVtable::init. It applies to subclasses of QAsm, such as: QHsm and QMsm. Subclasses of QActive, and QMActive should not make this virtual call directly because it is executed in the QActive::QActive_start() operation.

Note: Must be called after the "constructor".

Parameters

[in,out]	me_	current instance pointer (see SAS_QP_OOA)
[in]	par_	pointer the optional initialization parameter
[in]	qsId_	QS local filter ID (used only when Q_SPY is defined)

Usage
The following example illustrates how to initialize a state machine and dispatch events to it:

#include "qpc.h"   // QP/C public interface
#include "calc.h"  // Calc derived from QHsm
 
Q_DEFINE_THIS_FILE
 
static Calc Calc_inst;  // an instance of Calc state machine
 
int main() {
    Calc_ctor(&Calc_inst);  // Calc "constructor" invokes QHsm_ctor()
 
    QASM_INIT(&Calc_inst, (QEvt *)0); // <=== initial transition
 
    for (;;) { // event loop
        QEvt e = QEVT_INITIALIZER(MY_SIG);
        . . .
        // wait for the next event and assign it to the event object e
        . . .
        QASM_DISPATCH(&Calc_inst, &e); // dispatch e
    }
    return 0;
}

Forward Traceability

DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 221 of file qp.h.

◆ QASM_DISPATCH

#define QASM_DISPATCH	(	me_,
		e_,
		qsId_ )

Value:

(*((QAsm *)(me_))->vptr->dispatch)((QAsm *)(me_), (e_), (qsId_))

Virtual call to dispatch an event to a state machine.

Details
Processes one event at a time in Run-to-Completion fashion. This virtual call invokes the operation QAsmVtable::dispatch. It applies to subclasses of QAsm, such as: QHsm, QMsm, QActive, and QMActive.

Note: Must be called after the "constructor" and after QASM_INIT().

Parameters

[in,out]	me_	current instance pointer (see SAS_QP_OOA)
[in]	e_	constant pointer the QEvt or a class derived from QEvt (see SAS_QP_OOA)
[in]	qsId_	QS local filter ID (used only when Q_SPY is defined)

Usage
The following example illustrates how to initialize an SM and dispatch events to it:

#include "qpc.h"   // QP/C public interface
#include "calc.h"  // Calc state machine derived from QHsm
 
Q_DEFINE_THIS_FILE
 
static Calc Calc_inst;  // an instance of Calc SM
 
int main() {
    Calc_ctor(&Calc_inst);  // Calc "constructor" invokes QHsm_ctor()
 
    QASM_INIT(&Calc_inst, (QEvt *)0); // initial transition
 
    for (;;) { // event loop
        QEvt e = QEVT_INITIALIZER(MY_SIG);
        . . .
        // wait for the next event and assign it to the event object e
        . . .
        QASM_DISPATCH(&Calc_inst, &e); // <=== dispatch e
    }
    return 0;
}

Forward Traceability

DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 223 of file qp.h.

◆ QASM_IS_IN

#define QASM_IS_IN	(		me_,
			stateHndl_ )

Value:

(*((QAsm *)(me_))->vptr->isIn)((QAsm *)(me_), (stateHndl_))

Virtual call to check whether a state machine is in a given state.

Details
This virtual call invokes the operation QAsmVtable::isIn. It applies to subclasses of QAsm, such as: QHsm, QMsm, QActive, and QMActive.

Parameters

[in]	me_	current instance pointer (see SAS_QP_OOA)
[in]	stateHndl_	state handler (QStateHandler type)

Returns: 'true' if the state machine is in a given state and 'false' otherwise

Attention

The QASM_IS_IN() macro is available only for tracing/testing (when Q_SPY is defined). This is to prevent the following problematic uses of the "is-in" query:

Querying the current state inside the state machine in question (e.g., as a guard condition based on QASM_IS_IN()) is generally a bad design and often makes no sense because the state machine might be in the middle of a transition, where the current state is not well-defined.
Querying the current state of a concurrently executing state machine (e.g., from one active object to the other) is a bad idea because such a state can change asynchronously. Also, the other state machine might be in the middle of a state transition, where the "current state" is not well-defined.
Querying the current state requires exposing the state handlers to the rest of the system. (The QASM_IS_IN() requires the state-handler parameter).

Usage
The following example illustrates how to check whether SM is in a given state:

stat = QASM_IS_IN(the_hsm, Q_STATE_CAST(&QHsmTst_s11));

QASM_IS_IN

#define QASM_IS_IN(me_, stateHndl_)

Virtual call to check whether a state machine is in a given state.

Definition qp.h:225

Forward Traceability

DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 225 of file qp.h.

◆ QASM_GET_STATE_HANDLER

#define QASM_GET_STATE_HANDLER ( me_ )

Value:

(*((QAsm *)(me_))->vptr->getStateHandler)((QAsm *)(me_))

Virtual call to obtain the current state-handler of a state machine.

Details
This virtual call applies to all subclasses of QAsm, such as: QHsm, QMsm, QActive, and QMActive.

Parameters

[in] me_ current instance pointer (see SAS_QP_OOA)

Returns: the current state-handler of the type QStateHandler (pointer to function)

Note: This function can be called in any context (including from a critical section) and also not necessarily in the "stable state configuration". When called during a state transition in the SM, it returns the source state.

Usage
The following example illustrates how to obtain the current state handler of an Active Object:

QStateHandler handler = QASM_GET_STATE_HANDLER(my_AO);

QASM_GET_STATE_HANDLER

#define QASM_GET_STATE_HANDLER(me_)

Virtual call to obtain the current state-handler of a state machine.

Definition qp.h:234

Forward Traceability

DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 234 of file qp.h.

◆ Q_ASM_UPCAST

#define Q_ASM_UPCAST ( ptr_ )

Value:

((QAsm *)(ptr_))

Perform upcasting from a subclass of QAsm to the base class QAsm.

Parameters

[in,out] ptr_ pointer to subclass of QAsm

Returns: The upcasted pointer to the QAsm base class

Remarks: Upcasting from a subclass to a 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 SAS_QP_OOA), 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:2025 Rule 11.3(R). This macro encapsulates this deviation and provides a descriptive name for the reason for this cast.

Forward Traceability

DVP_QP_MC5_R11_3A: MISRA-C:2025 Rule 11.3(Required): A cast shall not be performed between a pointer to object type and a pointer to a different object type (object-oriented upcast)
DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 237 of file qp.h.

◆ Q_HSM_UPCAST

#define Q_HSM_UPCAST ( ptr_ )

Value:

((QHsm *)(ptr_))

QHsm

Hierarchical State Machine class (QHsm-style state machine implementation strategy).

Definition qp.h:242

Perform upcasting from a subclass of QHsm to the base class QHsm.

Parameters

[in,out] ptr_ pointer to subclass of QHsm

Returns: The upcasted pointer to the QHsm base class

See also

Q_ASM_UPCAST()

Forward Traceability

DVP_QP_MC5_R11_3A: MISRA-C:2025 Rule 11.3(Required): A cast shall not be performed between a pointer to object type and a pointer to a different object type (object-oriented upcast)
DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 298 of file qp.h.

◆ Q_TRAN

#define Q_TRAN ( target_ )

Value:

((Q_ASM_UPCAST(me))->temp.fun = Q_STATE_CAST(target_), \

(QState)Q_RET_TRAN)

Q_ASM_UPCAST

#define Q_ASM_UPCAST(ptr_)

Perform upcasting from a subclass of QAsm to the base class QAsm.

Definition qp.h:237

Q_RET_TRAN

#define Q_RET_TRAN

Definition qp.h:192

Take transition to the specified target_ state.

Parameters

[in] target_ target state (state handler)

Forward Traceability

DVP_QP_MC5_R11_1: MISRA-C:2025 Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type
DVP_QP_MC5_R12_3: MISRA-C:2025 Rule 12.3(Advisory): The comma operator should not be used
DVP_QP_MC5_R13_4: MISRA-C:2025 Rule 13.4(Advisory): The result of an assignment operator shall not be used
DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 300 of file qp.h.

◆ Q_TRAN_HIST

#define Q_TRAN_HIST ( hist_ )

Value:

((Q_ASM_UPCAST(me))->temp.fun = (hist_), \

(QState)Q_RET_TRAN_HIST)

Q_RET_TRAN_HIST

#define Q_RET_TRAN_HIST

Definition qp.h:193

Take transition to the specified history of a given state. Applicable only to HSMs.

Parameters

[in] hist_ recorded state history (state handler stored in a variable)

Usage

typedef struct  {
    QHsm super;  // inherit QHsm
 
    QStateHandler hist_doorClosed; // history of doorClosed
} ToastOven;
 
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;
}
 
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;
}

Forward Traceability

DVP_QP_MC5_R11_1: MISRA-C:2025 Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type
DVP_QP_MC5_R12_3: MISRA-C:2025 Rule 12.3(Advisory): The comma operator should not be used
DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 303 of file qp.h.

◆ Q_SUPER

#define Q_SUPER ( super_ )

Value:

((Q_ASM_UPCAST(me))->temp.fun = Q_STATE_CAST(super_), \

(QState)Q_RET_SUPER)

Q_RET_SUPER

#define Q_RET_SUPER

Definition qp.h:189

Designates the superstate of a given state. Applicable only to QHsm subclasses.

Parameters

[in] super_ superstate handler for a given state (might be QHsm_top())

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

Forward Traceability

DVP_QP_MC5_R11_1: MISRA-C:2025 Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type
DVP_QP_MC5_R12_3: MISRA-C:2025 Rule 12.3(Advisory): The comma operator should not be used
DVP_QP_MC5_R13_4: MISRA-C:2025 Rule 13.4(Advisory): The result of an assignment operator shall not be used
DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 306 of file qp.h.

◆ Q_HANDLED

#define Q_HANDLED ( )

Value:

((QState)Q_RET_HANDLED)

Q_RET_HANDLED

#define Q_RET_HANDLED

Definition qp.h:191

Indicate that an action has been "handled." Applies to entry/exit actions and internal transitions.

Example

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

Forward Traceability

DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 309 of file qp.h.

◆ Q_UNHANDLED

#define Q_UNHANDLED ( )

Value:

((QState)Q_RET_UNHANDLED)

Q_RET_UNHANDLED

#define Q_RET_UNHANDLED

Definition qp.h:190

Indicate that an internal transition has been "unhandled" due to a guard condition.

Details
This macro must be called when a state-handler 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.

Forward Traceability

DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 310 of file qp.h.

◆ Q_MSM_UPCAST

#define Q_MSM_UPCAST ( ptr_ )

Value:

((QMsm *)(ptr_))

QMsm

Hierarchical State Machine class (QMsm-style state machine implementation strategy).

Definition qp.h:315

Perform upcasting from a subclass of QMsm to the base class QMsm.

Parameters

[in,out] ptr_ pointer to subclass of QMsm

Returns: The upcasted pointer to the QMsm base class

Forward Traceability

DVP_QP_MC5_R11_3A: MISRA-C:2025 Rule 11.3(Required): A cast shall not be performed between a pointer to object type and a pointer to a different object type (object-oriented upcast)
DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 356 of file qp.h.

◆ QM_ENTRY

#define QM_ENTRY ( state_ )

Value:

((Q_ASM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_ENTRY)

Q_RET_ENTRY

#define Q_RET_ENTRY

Definition qp.h:199

Macro to call in a QM action-handler when it executes an entry action. Applicable only to QMsm subclasses.

Forward Traceability

DVP_QP_MC5_R11_1: MISRA-C:2025 Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type
DVP_QP_MC5_R12_3: MISRA-C:2025 Rule 12.3(Advisory): The comma operator should not be used
DVP_QP_MC5_R13_4: MISRA-C:2025 Rule 13.4(Advisory): The result of an assignment operator shall not be used
DVR_QP_MC5_D4_9B: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (CORRECT diagnostics)

Definition at line 358 of file qp.h.

◆ QM_EXIT

#define QM_EXIT ( state_ )

Value:

((Q_ASM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)

Q_RET_EXIT

#define Q_RET_EXIT

Definition qp.h:200

Macro to call in a QM action-handler when it executes an exit action. Applicable only to QMsm subclasses.

Forward Traceability

DVP_QP_MC5_R11_1: MISRA-C:2025 Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type
DVP_QP_MC5_R12_3: MISRA-C:2025 Rule 12.3(Advisory): The comma operator should not be used
DVP_QP_MC5_R13_4: MISRA-C:2025 Rule 13.4(Advisory): The result of an assignment operator shall not be used
DVR_QP_MC5_D4_9B: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (CORRECT diagnostics)

Definition at line 360 of file qp.h.

◆ QM_TRAN

#define QM_TRAN ( tatbl_ )

Value:

((Q_ASM_UPCAST(me))->temp.tatbl \

= (struct QMTranActTable const *)(tatbl_), (QState)Q_RET_TRAN)

QMTranActTable

Transition-Action Table for the QMsm State Machine.

Definition qp.h:159

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

Forward Traceability

DVP_QP_MC5_R11_1: MISRA-C:2025 Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type
DVP_QP_MC5_R11_3A: MISRA-C:2025 Rule 11.3(Required): A cast shall not be performed between a pointer to object type and a pointer to a different object type (object-oriented upcast)
DVP_QP_MC5_R12_3: MISRA-C:2025 Rule 12.3(Advisory): The comma operator should not be used
DVP_QP_MC5_R13_4: MISRA-C:2025 Rule 13.4(Advisory): The result of an assignment operator shall not be used
DVR_QP_MC5_D4_9B: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (CORRECT diagnostics)

Definition at line 367 of file qp.h.

◆ QM_TRAN_INIT

#define QM_TRAN_INIT ( tatbl_ )

Value:

((Q_ASM_UPCAST(me))->temp.tatbl \

= (struct QMTranActTable const *)(tatbl_), (QState)Q_RET_TRAN_INIT)

Q_RET_TRAN_INIT

#define Q_RET_TRAN_INIT

Definition qp.h:201

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

Forward Traceability

DVP_QP_MC5_R11_1: MISRA-C:2025 Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type
DVP_QP_MC5_R11_3A: MISRA-C:2025 Rule 11.3(Required): A cast shall not be performed between a pointer to object type and a pointer to a different object type (object-oriented upcast)
DVP_QP_MC5_R12_3: MISRA-C:2025 Rule 12.3(Advisory): The comma operator should not be used
DVP_QP_MC5_R13_4: MISRA-C:2025 Rule 13.4(Advisory): The result of an assignment operator shall not be used
DVR_QP_MC5_D4_9B: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (CORRECT diagnostics)

Definition at line 370 of file qp.h.

◆ QM_TRAN_HIST

#define QM_TRAN_HIST	(		history_,
			tatbl_ )

Value:

((((Q_ASM_UPCAST(me))->state.obj  = (history_)), \
  ((Q_ASM_UPCAST(me))->temp.tatbl = \
      (struct QMTranActTable const *)(tatbl_))), (QState)Q_RET_TRAN_HIST)

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

Forward Traceability

DVP_QP_MC5_R11_1: MISRA-C:2025 Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type
DVP_QP_MC5_R12_3: MISRA-C:2025 Rule 12.3(Advisory): The comma operator should not be used
DVP_QP_MC5_R13_4: MISRA-C:2025 Rule 13.4(Advisory): The result of an assignment operator shall not be used
DVR_QP_MC5_D4_9B: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (CORRECT diagnostics)

Definition at line 373 of file qp.h.

◆ QM_HANDLED

#define QM_HANDLED ( )

Value:

((QState)Q_RET_HANDLED)

Macro to call in a QM state-handler when it handled an event. Applicable only to QMsm subclasses.

Forward Traceability

DVR_QP_MC5_D4_9B: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (CORRECT diagnostics)

Definition at line 378 of file qp.h.

◆ QM_UNHANDLED

#define QM_UNHANDLED ( )

Value:

((QState)Q_RET_UNHANDLED)

Indicate that an internal transition has been "unhandled" due to a guard condition. Applicable only to QMsm subclasses.

Details
This macro must be called when a state-handler attempts to handle an event but a guard condition evaluates to 'false' and there is no other explicit way of handling the event.

Forward Traceability

DVR_QP_MC5_D4_9B: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (CORRECT diagnostics)

Definition at line 379 of file qp.h.

◆ QM_SUPER

#define QM_SUPER ( )

Value:

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

Forward Traceability

DVR_QP_MC5_D4_9B: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (CORRECT diagnostics)

Definition at line 380 of file qp.h.

◆ QM_STATE_NULL

#define QM_STATE_NULL ((QMState *)0)

Definition at line 381 of file qp.h.

◆ Q_ACTIVE_UPCAST

#define Q_ACTIVE_UPCAST ( ptr_ )

Value:

((QActive *)(ptr_))

QActive

Active object class (based on the QHsm implementation strategy).

Definition qp.h:450

Perform upcasting from a subclass of QActive to the base class QActive.

Parameters

[in,out] ptr_ pointer to subclass of QActive

Returns: The upcasted pointer to the QActive base class

Forward Traceability

DVP_QP_MC5_R11_3A: MISRA-C:2025 Rule 11.3(Required): A cast shall not be performed between a pointer to object type and a pointer to a different object type (object-oriented upcast)
DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 558 of file qp.h.

◆ QF_NO_MARGIN

#define QF_NO_MARGIN ((uint_fast16_t)0xFFFFU)

Special value of margin that causes asserting failure in case event allocation or event posting fails.

Definition at line 696 of file qp.h.

◆ Q_NEW

#define Q_NEW	(	evtT_,
		sig_,
		... )

Value:

(evtT_##_init((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \

QF_NO_MARGIN, (sig_)), __VA_ARGS__))

QF_NO_MARGIN

#define QF_NO_MARGIN

Special value of margin that causes asserting failure in case event allocation or event posting fails...

Definition qp.h:696

Allocate a mutable (dynamic) event.

Details
This macro allocates a mutable (dynamic) event and internally asserts that the allocation is successful. This means that the caller does not need to check the returned event pointer for validity because it is guaranteed to be not NULL.

The macro calls the internal QF function QF_newX_() with argument margin == QF_NO_MARGIN, which causes an assertion failure when the event cannot be successfully allocated.

Parameters

[in]	evtT_	event type (class name) of the event to allocate
[in]	sig_	signal to assign to the newly allocated event

Returns: A valid event pointer cast to the type evtT_.

Attention: When the configuration macro QEVT_PAR_INIT is defined, the macro Q_NEW() becomes variadic and takes additional parameters, which are passed to the event initialization. In that case, all your custom event classes (subclasses of QEvt) must to provide the init() member functions. This init() function needs to take at least one parameter and must return the event pointer (me).

Usage
The following example illustrates non-variadic version of Q_NEW() (when QEVT_PAR_INIT is NOT defined):

// event without parameters
QEvt *myEvt = Q_NEW(QEvt, MY_SIG); // <===
// post or publish the event...
 
// event with parameter(s) (event parameter(s) initialized separately)
KeypressEvt *ke = Q_NEW(KeypressEvt, KEYPRESS_SIG); // <===
ke->keyId = keyId;
// post or publish the event...

The following example illustrates variadic version of Q_NEW() and the RAII principle (Resource Acquisition Is Initialization) (when QEVT_PAR_INIT IS defined) :

// event without parameters (QEVT_DYNAMIC passed to QEvt_init())
QEvt *myEvt = Q_NEW(QEvt, MY_SIG, QEVT_DYNAMIC); // <==
// post or publish the event...
 
// event with parameters
typedef struct {
    QEvt super; // <=== inherit QEvt
    // event parameters follow...
    uint8_t keyId; // ID of the key pressed
} KeypressEvt;
 
// when QEVT_PAR_INIT is defined, the init() member function must be provided
static inline KeypressEvt * KeypressEvt_init(KeypressEvt * const me,
                                             uint8_t keyId)
{
    if (me != (KeypressEvt *)0) { // might be NULL if allocation failed
        me->keyId = keyId;
    }
    return me;
}
 
// event with parameters (keyId passed to KeypressEvt_init())
KeypressEvt const *ke = Q_NEW(KeypressEvt, KEYPRESS_SIG, keyId); // <===
// . . .

Backward Traceability

Forward Traceability

DVP_QP_MC5_R11_3B: MISRA-C:2025 Rule 11.3(Required): A cast shall not be performed between a pointer to object type and a pointer to a different object type (object-oriented downcast)
DVP_QP_PCLP_826: PCLP-826: suspicious pointer-to-pointer conversion (area too small)
DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)
DVR_QP_B18_R6_3B: BARR-C:2018 Rule 6.3b: unparenthesized macro parameter in definition of macro

Definition at line 740 of file qp.h.

◆ Q_NEW_X

#define Q_NEW_X	(	evtT_,
		margin_,
		sig_,
		... )

Value:

(evtT_##_init((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \

(margin_), (sig_)), __VA_ARGS__))

Non-asserting allocate a mutable (dynamic) event.

Details
This macro allocates a mutable (dynamic) event, but only if the corresponding event pool has at least a margin of free events left. If the event pool has an insufficient number of events left, the macro returns NULL. The caller of this macro is responsible for checking the returned event pointer for NULL.

Parameters

[in]	evtT_	event type (class name) of the event to allocate
[in]	margin_	number of events that must remain available in the given pool after this allocation. The special value QF_NO_MARGIN causes asserting failure in case event allocation fails.
[in]	sig_	signal to assign to the newly allocated event

Returns: An event pointer cast to the type evtT_ or NULL if the event cannot be allocated with the specified margin of events still left in the event pool.

Attention: When the configuration macro QEVT_PAR_INIT is defined, the macro Q_NEW() becomes variadic and takes additional parameters, which are passed to the event initialization. In that case, all your custom event classes (subclasses of QEvt) must provide the init() member functions. This init() function needs to take at least one parameter and must return the event pointer (me).

Usage
The following example illustrates non-variadic version of Q_NEW_X() (when QEVT_PAR_INIT is NOT defined):

// event without parameters
QEvt *myEvt = Q_NEW_X(QEvt, 5U, MY_SIG); // <== (margin == 5U)
if (myEvt) { // check the event pointer!
    // post or publish the event...
}
 
// event with parameter(s) (event parameter(s) initialized separately)
KeypressEvt *kevt = Q_NEW(KeypressEvt, 10U, KEYPRESS_SIG); // <===
if (kevt) { // check the event pointer!
    kevt->keyId = keyId;
    // post or publish the event...
}

The following example illustrates variadic version of Q_NEW_X() and the RAII principle (Resource Acquisition Is Initialization) (when QEVT_PAR_INIT IS defined) :

// event without parameters (QEVT_DYNAMIC passed to QEvt_init())
QEvt *myEvt = Q_NEW_X(QEvt, MY_SIG, 5U, QEVT_DYNAMIC); // <== (margin == 5U)
if (myEvt) { // check the event pointer!
    // post or publish the event...
}
 
// event with parameters
typedef struct {
    QEvt super; // <=== inherit QEvt
    // event parameters follow...
    uint8_t keyId; // ID of the key pressed
} KeypressEvt;
 
// when QEVT_PAR_INIT is defined, the init() member function must be provided
static inline KeypressEvt * KeypressEvt_init(KeypressEvt * const me,
                                             uint8_t keyId)
{
    if (me != (KeypressEvt *)0) {
        me->keyId = keyId;
    }
    return me;
}
 
// event with parameters (keyId passed to KeypressEvt_init())
KeypressEvt const *kevt = Q_NEW_X(KeypressEvt, 10U, KEYPRESS_SIG, keyId); // <==
if (kevt) { // check the event pointer!
    // post or publish the event...
}

Backward Traceability

Forward Traceability

DVP_QP_MC5_R11_3B: MISRA-C:2025 Rule 11.3(Required): A cast shall not be performed between a pointer to object type and a pointer to a different object type (object-oriented downcast)
DVP_QP_PCLP_826: PCLP-826: suspicious pointer-to-pointer conversion (area too small)
DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)
DVR_QP_B18_R6_3B: BARR-C:2018 Rule 6.3b: unparenthesized macro parameter in definition of macro

Definition at line 743 of file qp.h.

◆ Q_NEW_REF

#define Q_NEW_REF	(		evtRef_,
			evtT_ )

Value:

((evtRef_) = (evtT_ const *)QF_newRef_(e, (evtRef_)))

Create a new reference of the current event e.

Details
The current event processed by an active object is available only for the duration of the run-to-completion (RTC) step. After that step, the current event is no longer available and the framework might recycle (garbage-collect) the event. The macro Q_NEW_REF() explicitly creates a new reference to the current event that can be stored and used beyond the current RTC step, until the reference is explicitly recycled utilizing the macro Q_DELETE_REF().

Parameters

[in,out]	evtRef_	event reference to create
[in]	evtT_	event type (class name) of the event reference

Usage
The example defer in the directory examples/win32/defer illustrates the use of Q_NEW_REF()

Backward Traceability

Forward Traceability

DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)
DVR_QP_B18_R6_3B: BARR-C:2018 Rule 6.3b: unparenthesized macro parameter in definition of macro

Definition at line 755 of file qp.h.

◆ Q_DELETE_REF

#define Q_DELETE_REF ( evtRef_ )

Value:

    do { \
    QF_deleteRef_((evtRef_)); \
    (evtRef_) = (void *)0; \
} while (false)

Delete the event reference.

Details
Every event reference created with the macro Q_NEW_REF() needs to be eventually deleted utilizing the macro Q_DELETE_REF() to avoid leaking the event.

Parameters

[in,out] evtRef_ event reference to delete

Usage
The example defer in the directory examples/win32/defer illustrates the use of Q_DELETE_REF()

Backward Traceability

Forward Traceability

DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 757 of file qp.h.

◆ QACTIVE_POST

#define QACTIVE_POST	(	me_,
		e_,
		sender_ )

Value:

((void)QActive_post_((me_), (e_), QF_NO_MARGIN, (sender_)))

Invoke the direct event posting facility QActive_post_().

Details
This macro asserts if the queue overflows and cannot accept the event.

Parameters

[in,out]	me_	current instance pointer (see SAS_QP_OOA)
[in]	e_	pointer to the event to post
[in]	sender_	pointer to the sender object.

Note: The sender_ parameter is only used when QS software tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, this macro does not use the sender_ parameter, so it does not need to be defined.; The sender_ parameter is only used when QS software tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, this macro does not use the sender_ parameter, so it does not need to be defined.

See also

QActive_post_()

Forward Traceability

DVP_QP_PCLP_826: PCLP-826: suspicious pointer-to-pointer conversion (area too small)
DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 763 of file qp.h.

◆ QACTIVE_POST_X

#define QACTIVE_POST_X	(	me_,
		e_,
		margin_,
		sender_ )

Value:

(QActive_post_((me_), (e_), (margin_), (sender_)))

Invoke the direct event posting facility QActive_post_() without delivery guarantee.

Details
This macro does not assert if the queue overflows and cannot accept the event with the specified margin of free slots remaining.

Parameters

[in,out]	me_	current instance pointer (see SAS_QP_OOA)
[in]	e_	pointer to the event to post
[in]	margin_	the minimum free slots in the queue, which must still be available after posting the event. The special value QF_NO_MARGIN causes asserting failure in case event posting fails.
[in]	sender_	pointer to the sender object.

Returns: 'true' if the posting succeeded, and 'false' if the posting failed due to insufficient margin of free entries available in the queue.

Note: The sender_ parameter is only used when QS software tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, this macro does not use the sender_ parameter, so it does not need to be defined.; The pointer to the sender object is not necessarily a pointer to an active object. If QACTIVE_POST_X() is called from an interrupt or other context, you can create a unique object just to identify the sender of the event unambiguously.

Usage

extern QActive * const AO_Table;
    . . .
    /* typically inside a state machine action
    TableEvt *pe;
    Q_NEW_X(pe, TableEvt, 5U, HUNGRY_SIG); // dynamic alloc, margin==5
    if (pe != (TableEvt *)0) {
        pe->philNum = me->num;
        QACTIVE_POST_X(AO_Table, &pe->super, 3U, me); // <===
    }
    . . .

Forward Traceability

DVP_QP_PCLP_826: PCLP-826: suspicious pointer-to-pointer conversion (area too small)
DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 765 of file qp.h.

◆ QACTIVE_PUBLISH

#define QACTIVE_PUBLISH	(		e_,
			sender_ )

Value:

(QActive_publish_((e_), (void const *)(sender_), (sender_)->prio))

Publish an event to all subscriber Active Objects.

Details
If Q_SPY is defined, this macro calls QActive_publish_() with the sender_ parameter to identify the publisher of the event. Otherwise, sender_ is not used.

Parameters

[in]	e_	pointer to the posted event
[in]	sender_	pointer to the sender object (actually used only when Q_SPY is defined)

Note: The sender_ parameter is only used when QS software tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, the QACTIVE_PUBLISH() macro does not use the sender_ parameter, so it does not need to be defined.

Forward Traceability

DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 767 of file qp.h.

◆ QTIMEEVT_TICK_X

#define QTIMEEVT_TICK_X	(		tickRate_,
			sender_ )

Value:

(QTimeEvt_tick_((tickRate_), (sender_)))

Invoke the system clock tick processing QTimeEvt_tick_().

Details
This macro is the recommended way of invoking clock tick processing, because it provides the vital information for software tracing and avoids any overhead when the tracing is disabled.

Parameters

[in]	tickRate_	clock tick rate to be serviced through this call
[in]	sender_	pointer to the sender object. This parameter is only used when QS software tracing is enabled (macro Q_SPY is defined)

Note: The sender_ parameter is only used when QS software tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, the sender_ parameter is unused and does not even need to be specified in the program.

Forward Traceability

DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 769 of file qp.h.

◆ QTICKER_TRIG

#define QTICKER_TRIG	(		ticker_,
			sender_ )

Value:

(QTicker_trig_((ticker_), (sender_)))

Asynchronously trigger the QTicker AO to perform tick processing.

Details
This macro is the recommended way to trigger clock tick processing, because it provides the vital information for software tracing and avoids any overhead when the tracing is disabled.

Parameters

[in]	ticker_	pointer to the QTicker active object
[in]	sender_	pointer to the sender object. This parameter is only used when QS software tracing is enabled (macro Q_SPY is defined)

Note: When QS software tracing is disabled, the macro does not use the sender_ parameter, so it does not need to be defined.; The pointer to the sender_ object is not necessarily a pointer to an active object. When QTICKER_TRIG() is called from an interrupt, you would create a unique object just to unambiguously identify the ISR as the sender of the time events.

Forward Traceability

DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 770 of file qp.h.

◆ QACTIVE_POST_LIFO

#define QACTIVE_POST_LIFO	(		me_,
			e_ )

Value:

(QActive_postLIFO_((me_), (e_)))

Post an event to an active object using the Last-In-First-Out (LIFO) policy.

Parameters

[in,out]	me_	current instance pointer (see SAS_QP_OOA)
[in]	e_	pointer to the event to post

Definition at line 781 of file qp.h.

◆ QTIMEEVT_TICK

#define QTIMEEVT_TICK ( sender_ )

Value:

QTIMEEVT_TICK_X(0U, (sender_))

QTIMEEVT_TICK_X

#define QTIMEEVT_TICK_X(tickRate_, sender_)

Invoke the system clock tick processing QTimeEvt_tick_().

Definition qp.h:769

Invoke the system clock tick processing for tick rate 0.

See also

QTimeEvt::QTimeEvt_tick_()

Forward Traceability

DVR_QP_MC5_D4_9A: MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)

Definition at line 782 of file qp.h.

Typedef Documentation

◆ int_t

typedef int int_t

Alias for assertion-ID numbers in QP assertions and return from QF_run().

Definition at line 87 of file qp.h.

◆ enum_t

typedef int enum_t

Definition at line 88 of file qp.h.

◆ QSignal

typedef uint16_t QSignal

The signal of event QEvt.

Details
The event signal in UML is the specification of an asynchronous stimulus that triggers reactions, and as such is an essential part of an event. The event signal conveys the type of the occurrence (what happened?) However, an event can also contain additional quantitative information about the occurrence in the form of event parameters. The event signal has to unambiguously identify the event-type, which includes the precise types of all event parameters (see also Relationship between event signals and events).

Backward Traceability

QEvt: Event class

Definition at line 97 of file qp.h.

◆ QEvtPtr

typedef struct QEvt const * QEvtPtr

Pointer to const event instances passed around in QP/C Framework.

Forward Traceability

Definition at line 135 of file qp.h.

◆ QState

typedef uint_fast8_t QState

Type returned from state-handler functions.

Forward Traceability

Definition at line 144 of file qp.h.

◆ QStateHandler

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

Pointer to a state-handler function.

Forward Traceability

Definition at line 145 of file qp.h.

◆ QActionHandler

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

Pointer to an action-handler function.

Forward Traceability

Definition at line 146 of file qp.h.

◆ QXThreadHandler

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

Pointer to an extended-thread handler function.

Forward Traceability

Definition at line 149 of file qp.h.

◆ QPrioSpec

typedef uint16_t QPrioSpec

Priority specification for Active Objects in QP.

Details
Active Object priorities in QP are integer numbers in the range [1..QF_MAX_ACTIVE], whereas the special priority number 0 is reserved for the lowest-priority idle thread. The QP/C Framework uses the direct priority numbering, in which higher numerical values denote higher urgency. For example, an AO with priority 32 has higher urgency than an AO with priority 23.

QPrioSpec allows an application developer to assign two priorities to a given AO (see also Q_PRIO()):

The "QF-priority", which resides in the least-significant byte of the QPrioSpec data type. The "QF-priority" must be unique for each thread in the system and higher numerical values represent higher urgency (direct priority numbering).
The "preemption-threshold" priority, which resides in the most-significant byte of the QPrioSpec data type. The second priority cannot be lower than the "QF-priority", but does NOT need to be unique.

In the QP native preemptive kernels, like QK, the "preemption-threshold" priority is used to implement the "preemption-threshold scheduling" (PTS). It determines the conditions under which a given thread can be preempted by other threads. Specifically, a given thread can be preempted only by another thread with a higher priority than the "preemption-threshold" of the original thread.

QF-priority and preemption-threshold relations

Note: For backwards compatibility, QPrioSpec data type might contain only the "QF-priority" component (and the "preemption-threshold" component left at zero). In that case, the "preemption-threshold" will be assumed to be the same as the "QF-priority". This corresponds precisely to the previous semantics of AO priority.

Remarks: When QP runs on top of 3rd-party kernels/RTOSes or general-purpose operating systems, the second priority can have a different meaning, depending on the specific RTOS/GPOS used. Priority threshold is supported in QP ports to ThreadX.

Forward Traceability

Definition at line 386 of file qp.h.

◆ QTimeEvtCtr

typedef uint32_t QTimeEvtCtr

Data type to store the block-size defined based on the macro QF_TIMEEVT_CTR_SIZE.

Details
The dynamic range of this data type determines the maximum block size that the pool can manage.

Forward Traceability

Definition at line 393 of file qp.h.

◆ QPSetBits

typedef uint32_t QPSetBits

Bitmask for the internal representation of QPSet elements.

Definition at line 401 of file qp.h.

Function Documentation

◆ QF_LOG2()

uint_fast8_t QF_LOG2 ( QPSetBits const bitmask )

Log-base-2 calculation when hardware acceleration is NOT provided (QF_LOG2 not defined).

Definition at line 141 of file qf_qact.c.

◆ Q_PRIO()

QPrioSpec Q_PRIO	(	uint8_t const	prio,
		uint8_t const	pthre )

inlinestatic

Definition at line 691 of file qp.h.

Variable Documentation

◆ QP_versionStr

char const QP_versionStr[24]

extern

Definition at line 43 of file qf_act.c.

Classes

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ QP_VERSION_STR

◆ QP_VERSION

◆ QP_RELEASE

◆ Q_UNUSED_PAR

◆ Q_DIM

◆ Q_UINT2PTR_CAST

◆ QEVT_INITIALIZER

◆ QEVT_DYNAMIC

◆ Q_EVT_CAST

◆ Q_USER_SIG

◆ Q_STATE_CAST

◆ Q_ACTION_CAST

◆ Q_ACTION_NULL

◆ Q_RET_SUPER

◆ Q_RET_UNHANDLED

◆ Q_RET_HANDLED

◆ Q_RET_TRAN

◆ Q_RET_TRAN_HIST

◆ Q_RET_IGNORED

◆ Q_RET_ENTRY

◆ Q_RET_EXIT

◆ Q_RET_TRAN_INIT

◆ Q_EMPTY_SIG

◆ Q_ENTRY_SIG

◆ Q_EXIT_SIG

◆ Q_INIT_SIG

◆ QASM_INIT

◆ QASM_DISPATCH

◆ QASM_IS_IN

◆ QASM_GET_STATE_HANDLER

◆ Q_ASM_UPCAST

◆ Q_HSM_UPCAST

◆ Q_TRAN

◆ Q_TRAN_HIST

◆ Q_SUPER

◆ Q_HANDLED

◆ Q_UNHANDLED

◆ Q_MSM_UPCAST

◆ QM_ENTRY

◆ QM_EXIT

◆ QM_TRAN

◆ QM_TRAN_INIT

◆ QM_TRAN_HIST

◆ QM_HANDLED

◆ QM_UNHANDLED

◆ QM_SUPER

◆ QM_STATE_NULL

◆ Q_ACTIVE_UPCAST

◆ QF_NO_MARGIN

◆ Q_NEW

◆ Q_NEW_X

◆ Q_NEW_REF

◆ Q_DELETE_REF

◆ QACTIVE_POST

◆ QACTIVE_POST_X

◆ QACTIVE_PUBLISH

◆ QTIMEEVT_TICK_X

◆ QTICKER_TRIG

◆ QACTIVE_POST_LIFO

◆ QTIMEEVT_TICK

Typedef Documentation

◆ int_t

◆ enum_t

◆ QSignal

◆ QEvtPtr

◆ QState

◆ QStateHandler

◆ QActionHandler

◆ QXThreadHandler

◆ QPrioSpec

◆ QTimeEvtCtr

◆ QPSetBits

Function Documentation