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

Classes
class	QEvt
	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.0.0"
	Version string complying with Semantic Versioning

#define	QP_VERSION 800U
	Version number for internal use (must correspond to QP_VERSION_STR)

#define	QP_RELEASE 0x7055936FU
	Encrypted current QP release for internal use (7.3.5 on 2024-05-31)

#define	QEVT_INITIALIZER(sig_) { (QSignal)(sig_), 0x01U, 0x0EU }
	Initializer for immutable (constant) QEvt instances.

#define	QEVT_DYNAMIC ((uint8_t)0)
	dummy parameter for dynamic event initialization (see QEvt::QEvt_init())

#define	QASM_INIT(me_, par_, qsId_)
	QVirtual call to the top-most initial transition in a HSM.

#define	QASM_DISPATCH(me_, e_, qsId_) (((QAsm )(me_))->vptr->dispatch)((QAsm *)(me_), (e_), (qsId_))
	Virtual call to dispatch an event to a HSM.

#define	QASM_IS_IN(me_, state_) (((QAsm )(me_))->vptr->isIn)((QAsm *)(me_), (state_))
	Virtual call to check whether a SM is in a given state.

#define	Q_ASM_UPCAST(ptr_) ((QAsm *)(ptr_))
	Perform upcasting from a subclass of QAsm to the base class QAsm.

#define	Q_HSM_UPCAST(ptr_) ((QHsm *)(ptr_))
	Perform upcasting from a subclass of QHsm to the base class QHsm.

#define	Q_MSM_UPCAST(ptr_) ((QMsm *)(ptr_))
	Perform upcasting from a subclass of QMsm to the base class QMsm.

#define	Q_EMPTY_SIG ((QSignal)0)
	reserved signal sent to state handler to execute the default case)

#define	Q_ENTRY_SIG ((QSignal)1)
	reserved signal sent to state handler to execute the entry case)

#define	Q_EXIT_SIG ((QSignal)2)
	reserved signal sent to state handler to execute the exit case)

#define	Q_INIT_SIG ((QSignal)3)
	reserved signal sent to state handler to execute the initial transition)

#define	Q_USER_SIG ((enum_t)4)
	offset for the user signals (QP Application))

#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() ((QState)Q_RET_HANDLED)
	Indicate that an action has been "handled". Applies to entry/exit actions and to internal transitions.

#define	Q_UNHANDLED() ((QState)Q_RET_UNHANDLED)
	Indicate that an internal transition has been "unhandled" due to a guard condition.

#define	Q_ACTION_NULL ((QActionHandler)0)
	Macro to provide strictly-typed zero-action to terminate action lists in the transition-action-tables.

#define	Q_EVT_CAST(class_) ((class_ const *)(e))
	Perform downcast of an event onto a subclass of QEvt `class_`

#define	Q_STATE_CAST(handler_) ((QStateHandler)(handler_))
	Perform cast to QStateHandler.

#define	Q_ACTION_CAST(action_) ((QActionHandler)(action_))
	Perform cast to QActionHandler.

#define	Q_UNUSED_PAR(par_) ((void)(par_))
	Helper macro to clearly mark unused parameters of functions.

#define	Q_DIM(array_) (sizeof(array_) / sizeof((array_)[0U]))

#define	Q_UINT2PTR_CAST(type_, uint_) ((type_ *)(uint_))
	Perform cast from unsigned integer `uint_` to pointer of type `type_`

#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_SM_EXIT(state_)
	Macro to call in a QM submachine exit-handler. Applicable only to subclasses of QMsm.

#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() ((QState)Q_RET_HANDLED)
	Macro to call in a QM state-handler when it handled an event. Applicable only to QMsm subclasses.

#define	QM_UNHANDLED() ((QState)Q_RET_UNHANDLED)
	Indicate that an internal transition has been "unhandled" due to a guard condition. Applicable only to QMsm subclasses.

#define	QM_SUPER() ((QState)Q_RET_SUPER)
	Macro to call in a QM state-handler when it designates the superstate to handle an event. Applicable only to QMSMs.

#define	QM_STATE_NULL ((QMState *)0)
	Macro to provide strictly-typed zero-state to use for submachines. Applicable to subclasses of QMsm.

#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_PRIO(prio_, pthre_) ((QPrioSpec)((prio_) \| ((pthre_) << 8U)))
	Create a QPrioSpec object to specify priority of an AO or a thread.

#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_) ((evtRef_) = (evtT_ const *)QF_newRef_(e, (evtRef_)))
	Create a new reference of the current event `e`

#define	Q_DELETE_REF(evtRef_)
	Delete the event reference.

#define	QACTIVE_POST(me_, e_, sender_) ((void)QActive_post_((me_), (e_), QF_NO_MARGIN, (sender_)))
	Invoke the direct event posting facility QActive_post_().

#define	QACTIVE_POST_X(me_, e_, margin_, sender_) (QActive_post_((me_), (e_), (margin_), (sender_)))
	Invoke the direct event posting facility QActive_post_() without delivery guarantee.

#define	QACTIVE_POST_LIFO(me_, e_) (QActive_postLIFO_((me_), (e_)))
	Post an event to an active object using the Last-In-First-Out (LIFO) policy.

#define	QACTIVE_PUBLISH(e_, sender_) (QActive_publish_((e_), (void const *)(sender_), (sender_)->prio))
	Publish an event to all subscriber Active Objects.

#define	QTIMEEVT_TICK_X(tickRate_, sender_) (QTimeEvt_tick_((tickRate_), (sender_)))
	Invoke the system clock tick processing QTimeEvt_tick_()

#define	QTIMEEVT_TICK(sender_) QTIMEEVT_TICK_X(0U, (sender_))
	Invoke the system clock tick processing for tick rate 0.

#define	QTICKER_TRIG(ticker_, sender_) (QTicker_trig_((ticker_), (sender_)))
	Asynchronously trigger the QTicker AO to perform tick processing.

#define	QF_CRIT_EXIT_NOP() ((void)0)
	No-operation for exiting a critical section.

#define	QF_TICK_X(tickRate_, sender_) QTIMEEVT_TICK_X((tickRate_), (sender_))
	Invoke the system clock tick processing.

#define	QF_TICK(sender_) QTIMEEVT_TICK(sender_)
	Invoke the system clock tick processing.

#define	QF_PUBLISH(e_, sender_) QACTIVE_PUBLISH((e_), (sender_))

#define	QF_MEM_SYS() ((void)0)

#define	QF_MEM_APP() ((void)0)

Typedefs
typedef int	int_t
	Alias for assertion-ID numbers in QP assertions and return from QF_run()

typedef int	enum_t

typedef float	float32_t
	Alias for IEEE 754 32-bit floating point number.

typedef double	float64_t
	Alias for IEEE 754 64-bit floating point number.

typedef uint16_t	QSignal
	The signal of event QEvt.

typedef enum QStateRet	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.

typedef QEvt const *	QEvtPtr
	Pointer to const event instances passed around in QP Framework.

Enumerations
enum	QStateRet { Q_RET_SUPER , 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 }

Functions
uint_fast8_t	QF_LOG2 (QPSetBits const bitmask)
	Log-base-2 calculation when hardware acceleration is NOT provided (QF_LOG2 not defined)

Variables
char const	QP_versionStr [16]
	the current QP version number string in ROM, based on QP_VERSION_STR

QEvt const	QEvt_reserved_ [4]

Detailed Description

QP/C platform-independent public interface.

Backward Traceability

DVP_QP_MC4_D04_08 : 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

Definition in file qp.h.

Macro Definition Documentation

◆ QP_VERSION_STR

#define QP_VERSION_STR "8.0.0"

Version string complying with Semantic Versioning

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

Examples:

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

Definition at line 39 of file qp.h.

◆ QP_VERSION

#define QP_VERSION 800U

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.

Definition at line 40 of file qp.h.

◆ QP_RELEASE

#define QP_RELEASE 0x7055936FU

Encrypted current QP release for internal use (7.3.5 on 2024-05-31)

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

Definition at line 41 of file qp.h.

◆ QEVT_INITIALIZER

#define QEVT_INITIALIZER ( sig_ ) { (QSignal)(sig_), 0x01U, 0x0EU }

Initializer for immutable (constant) QEvt instances.

Details: This macro encapsulates the casting of enumerated signals and the generation of the Duplicate Inverse Storage for integrity check in the QEvt. evtTag_ attribute.

Usage: static QEvt const testEvt = QEVT_INITIALIZER(TEST_SIG);

. . .

QACTIVE_POST(AO_Xyz, &testEvt, 0U);

. . .

. . .

typedef struct {

QEvt super; // inherit QEvt

uint8_t id; // id of the pressed button

} ButtonPressEvt;

. . .

// immutable button-press event

static ButtonWorkEvt const pressEvt = {

QEVT_INITIALIZER(BUTTON_PRESSED_SIG),

.id = 123U

};

. . .

QACTIVE_POST(AO_Button, &pressEvt.super, &l_SysTick_Handler);

QEVT_INITIALIZER
#define QEVT_INITIALIZER(sig_)
Initializer for immutable (constant) QEvt instances.
Definition qp.h:430

QEvt
Event class.
Definition qp.h:131

Definition at line 430 of file qp.h.

◆ QEVT_DYNAMIC

#define QEVT_DYNAMIC ((uint8_t)0)

dummy parameter for dynamic event initialization (see QEvt::QEvt_init())

Definition at line 433 of file qp.h.

◆ QASM_INIT

#define QASM_INIT	(	me_,
		par_,
		qsId_ )

Value:

    do { \
    Q_ASSERT(((QAsm *)(me_))->vptr); \
    (*((QAsm *)(me_))->vptr->init)((QAsm *)(me_), (par_), (qsId_)); \
} while (false)

QVirtual call to the top-most initial transition in a HSM.

Parameters

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

Note: Must be called only ONCE after the SM "constructor".

Backward Traceability

SRS_QP_SM_38 : All State Machine Implementation Strategies provided by QP/C Framework shall support top-most initial transition that shall be explicitly triggered independently from instantiation of the state machine object

Usage: The following example illustrates how to initialize a SM, and dispatch events to it:
#include "qpc.h" // QP/C public interface

#include "calc.h" // Calc derived from QHsm

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;

}

QASM_INIT
#define QASM_INIT(me_, par_, qsId_)
QVirtual call to the top-most initial transition in a HSM.
Definition qp.h:437

QASM_DISPATCH
#define QASM_DISPATCH(me_, e_, qsId_)
Virtual call to dispatch an event to a HSM.
Definition qp.h:453

qpc.h
QP/C interface including the backwards-compatibility layer.

Definition at line 437 of file qp.h.

◆ QASM_DISPATCH

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

Virtual call to dispatch an event to a HSM.

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

Parameters

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

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

Backward Traceability

SRS_QP_SM_10 : QP/C Framework shall support multiple and interchangeable State Machine Implementation Strategies

Usage: The following example illustrates how to initialize a SM, and dispatch events to it:
#include "qpc.h" // QP/C public interface

#include "calc.h" // Calc derived from QHsm

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;

}

Definition at line 453 of file qp.h.

◆ QASM_IS_IN

#define QASM_IS_IN	(		me_,
			state_ ) (((QAsm )(me_))->vptr->isIn)((QAsm *)(me_), (state_))

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

Details: This macro applies to all QP state machines, that is subclasses of QHsm and QMsm.

Parameters

[in,out]	me_	current instance pointer (see Object Orientation)
[in]	state_	state handler (QStateHandler type)

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

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

Attention: This macro must be called only on a SM that is in the "stable state configuration". Among others, this means that the state machine cannot call it in the middle of its own transition.

Backward Traceability

SRS_QP_SM_25 : All State Machine Implementation Strategies provided by QP/C Framework might supply a method for checking if a state machine is in a given state

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

Q_STATE_CAST
#define Q_STATE_CAST(handler_)
Perform cast to QStateHandler.
Definition qp.h:519

QASM_IS_IN
#define QASM_IS_IN(me_, state_)
Virtual call to check whether a SM is in a given state.
Definition qp.h:464

Definition at line 464 of file qp.h.

◆ Q_ASM_UPCAST

#define Q_ASM_UPCAST ( ptr_ ) ((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 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:2023 Rule 11.3(R). This macro encapsulates this deviation and provides a descriptive name for the reason of this cast.

Backward Traceability

DVP_QP_MC4_R11_03A : 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) (upcast)

Definition at line 468 of file qp.h.

◆ Q_HSM_UPCAST

#define Q_HSM_UPCAST ( ptr_ ) ((QHsm *)(ptr_))

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

Backward Traceability

DVP_QP_MC4_R11_03A : 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) (upcast)

Definition at line 471 of file qp.h.

◆ Q_MSM_UPCAST

#define Q_MSM_UPCAST ( ptr_ ) ((QMsm *)(ptr_))

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

See also

Q_ASM_UPCAST()

Backward Traceability

DVP_QP_MC4_R11_03A : 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) (upcast)

Definition at line 474 of file qp.h.

◆ Q_EMPTY_SIG

#define Q_EMPTY_SIG ((QSignal)0)

reserved signal sent to state handler to execute the default case)

Definition at line 477 of file qp.h.

◆ Q_ENTRY_SIG

#define Q_ENTRY_SIG ((QSignal)1)

reserved signal sent to state handler to execute the entry case)

Definition at line 480 of file qp.h.

◆ Q_EXIT_SIG

#define Q_EXIT_SIG ((QSignal)2)

reserved signal sent to state handler to execute the exit case)

Definition at line 483 of file qp.h.

◆ Q_INIT_SIG

#define Q_INIT_SIG ((QSignal)3)

reserved signal sent to state handler to execute the initial transition)

Definition at line 486 of file qp.h.

◆ Q_USER_SIG

#define Q_USER_SIG ((enum_t)4)

offset for the user signals (QP 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,

. . .

};

Q_USER_SIG
#define Q_USER_SIG
offset for the user signals (QP Application))
Definition qp.h:489

Definition at line 489 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_RET_TRAN

@ Q_RET_TRAN

regular transition

Definition qp.h:204

Q_ASM_UPCAST

#define Q_ASM_UPCAST(ptr_)

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

Definition qp.h:468

QState

enum QStateRet QState

Type returned from state-handler functions.

Definition qp.h:212

Take transition to the specified target_ state.

Backward Traceability

DVP_QP_MC4_R11_01 : Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type
DVP_QP_MC4_R12_03 : Rule 12.3(Advisory): The comma operator should not be used
DVP_QP_MC4_R13_04 : Rule 13.4(Advisory): The result of an assignment operator shall not be used

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

@ Q_RET_TRAN_HIST

transition to history of a given state

Definition qp.h:208

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

Backward Traceability

SRS_QP_SM_39 : All State Machine Implementation Strategies provided by QP/C Framework should support transitions to history. Both shallow and deep histories shall be supported
DVP_QP_MC4_R11_01 : Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type
DVP_QP_MC4_R12_03 : Rule 12.3(Advisory): The comma operator should not be used

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;

}

Q_HANDLED
#define Q_HANDLED()
Indicate that an action has been "handled". Applies to entry/exit actions and to internal transitions...
Definition qp.h:507

Q_EXIT_SIG
#define Q_EXIT_SIG
reserved signal sent to state handler to execute the exit case)
Definition qp.h:483

QStateHandler
QState(* QStateHandler)(void *const me, QEvt const *const e)
Pointer to a state-handler function.
Definition qp.h:215

Q_TRAN_HIST
#define Q_TRAN_HIST(hist_)
Take transition to the specified history of a given state. Applicable only to HSMs.
Definition qp.h:497

Q_SUPER
#define Q_SUPER(super_)
Designates the superstate of a given state. Applicable only to QHsm subclasses.
Definition qp.h:502

QEvt::sig
QSignal sig
Signal of the event (see Event Signal)
Definition qp.h:135

QHsm
Hierarchical State Machine class (QHsm-style state machine implementation strategy)
Definition qp.h:292

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

@ Q_RET_SUPER

event passed to superstate to handle

Definition qp.h:189

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

Backward Traceability

SRS_QP_SM_31 : All State Machine Implementation Strategies provided by QP/C Framework shall support states capable of holding hierarchically nested substates
DVP_QP_MC4_R11_01 : Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type
DVP_QP_MC4_R12_03 : Rule 12.3(Advisory): The comma operator should not be used
DVP_QP_MC4_R13_04 : Rule 13.4(Advisory): The result of an assignment operator shall not be used

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;

}

Q_TRAN
#define Q_TRAN(target_)
Take transition to the specified target_ state.
Definition qp.h:492

Q_ENTRY_SIG
#define Q_ENTRY_SIG
reserved signal sent to state handler to execute the entry case)
Definition qp.h:480

Definition at line 502 of file qp.h.

◆ Q_HANDLED

#define Q_HANDLED ( ) ((QState)Q_RET_HANDLED)

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

Backward Traceability

SRS_QP_SM_32 : All State Machine Implementation Strategies provided by QP/C Framework shall support entry actions to states
SRS_QP_SM_33 : All State Machine Implementation Strategies provided by QP/C Framework shall support exit actions from states
SRS_QP_SM_36 : All State Machine Implementation Strategies provided by QP/C Framework shall support internal transitions in states

Definition at line 507 of file qp.h.

◆ Q_UNHANDLED

#define Q_UNHANDLED ( ) ((QState)Q_RET_UNHANDLED)

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.

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

◆ Q_EVT_CAST

#define Q_EVT_CAST ( class_ ) ((class_ const *)(e))

Perform downcast of an event onto a subclass of QEvt class_

Details: This macro encapsulates the downcast of QEvt pointers, which violates MISRA-C:2023 Rule 11.3(R). This macro helps to localize this deviation.

Parameters

class_ a subclass of QEvt

Backward Traceability

SRS_QP_EVT_30 : QP/C Framework shall allow Application to create event instances with Parameters defined by the Application
DVP_QP_MC4_D04_09A : Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnosis)
DVP_QP_MC4_R11_03B : 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 : Suspicious pointer-to-pointer conversion (area too small)

Definition at line 516 of file qp.h.

◆ Q_STATE_CAST

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

Perform cast to QStateHandler.

Details: This macro encapsulates the cast of a specific state handler function pointer to QStateHandler, which violates MISRA:C-2023 Rule 11.1(R). This macro helps to localize this deviation.

Backward Traceability

DVP_QP_MC4_D04_09A : Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnosis)
DVP_QP_MC4_R11_01 : Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type

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

}

enum_t
int enum_t
Definition qp.h:99

Definition at line 519 of file qp.h.

◆ Q_ACTION_CAST

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

Perform cast to QActionHandler.

Details: This macro encapsulates the cast of a specific action handler function pointer to QActionHandler, which violates MISRA:C-2023 Rule 11.1(R). This macro helps to localize this deviation.

Backward Traceability

DVP_QP_MC4_D04_09A : Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnosis)
DVP_QP_MC4_R11_01 : Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type

Definition at line 522 of file qp.h.

◆ Q_UNUSED_PAR

#define Q_UNUSED_PAR ( par_ ) ((void)(par_))

Helper macro to clearly mark unused parameters of functions.

Definition at line 525 of file qp.h.

◆ Q_DIM

#define Q_DIM ( array_ ) (sizeof(array_) / sizeof((array_)[0U]))

Definition at line 528 of file qp.h.

◆ Q_UINT2PTR_CAST

#define Q_UINT2PTR_CAST	(		type_,
			uint_ ) ((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 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 531 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

@ Q_RET_ENTRY

state entry action executed

Definition qp.h:197

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

Backward Traceability

DVP_QP_MC4_R11_01 : Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type
DVP_QP_MC4_R12_03 : Rule 12.3(Advisory): The comma operator should not be used
DVP_QP_MC4_R13_04 : Rule 13.4(Advisory): The result of an assignment operator shall not be used

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

@ Q_RET_EXIT

state exit action executed

Definition qp.h:198

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

Backward Traceability

DVP_QP_MC4_R11_01 : Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type
DVP_QP_MC4_R12_03 : Rule 12.3(Advisory): The comma operator should not be used
DVP_QP_MC4_R13_04 : Rule 13.4(Advisory): The result of an assignment operator shall not be used

Definition at line 547 of file qp.h.

◆ QM_SM_EXIT

#define QM_SM_EXIT ( state_ )

Value:

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

(QState)Q_RET_EXIT)

Macro to call in a QM submachine exit-handler. Applicable only to subclasses of QMsm.

Backward Traceability

DVP_QP_MC4_R11_01 : Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type
DVP_QP_MC4_R12_03 : Rule 12.3(Advisory): The comma operator should not be used
DVP_QP_MC4_R13_04 : Rule 13.4(Advisory): The result of an assignment operator shall not be used

Definition at line 558 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)

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

Backward Traceability

DVP_QP_MC4_R11_01 : Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type
DVP_QP_MC4_R11_03A : 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) (upcast)
DVP_QP_MC4_R12_03 : Rule 12.3(Advisory): The comma operator should not be used
DVP_QP_MC4_R13_04 : Rule 13.4(Advisory): The result of an assignment operator shall not be used

Definition at line 563 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)

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

Backward Traceability

DVP_QP_MC4_R11_01 : Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type
DVP_QP_MC4_R11_03A : 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) (upcast)
DVP_QP_MC4_R12_03 : Rule 12.3(Advisory): The comma operator should not be used
DVP_QP_MC4_R13_04 : Rule 13.4(Advisory): The result of an assignment operator shall not be used

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

Backward Traceability

DVP_QP_MC4_R11_01 : Rule 11.1(Required): Conversions shall not be performed between a pointer to a function and any other type
DVP_QP_MC4_R12_03 : Rule 12.3(Advisory): The comma operator should not be used
DVP_QP_MC4_R13_04 : Rule 13.4(Advisory): The result of an assignment operator shall not be used

Definition at line 573 of file qp.h.

◆ QM_HANDLED

#define QM_HANDLED ( ) ((QState)Q_RET_HANDLED)

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

Definition at line 580 of file qp.h.

◆ QM_UNHANDLED

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

Definition at line 583 of file qp.h.

◆ QM_SUPER

#define QM_SUPER ( ) ((QState)Q_RET_SUPER)

Macro to call in a QM state-handler when it designates the superstate to handle an event. Applicable only to QMSMs.

Definition at line 586 of file qp.h.

◆ QM_STATE_NULL

#define QM_STATE_NULL ((QMState *)0)

Macro to provide strictly-typed zero-state to use for submachines. Applicable to subclasses of QMsm.

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

◆ Q_PRIO

#define Q_PRIO	(		prio_,
			pthre_ ) ((QPrioSpec)((prio_) \| ((pthre_) << 8U)))

Create a QPrioSpec object to specify priority of an AO or a thread.

Parameters

[in]	prio_	QF priority [1..QF_MAX_ACTIVE]
[in]	pthre_	Preemption threshold [1..QF_MAX_ACTIVE]

Returns: The combined 16-bit priority specification (prio_ in bits [0..7] and pthre_ in bits [8..15].

Definition at line 1158 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:1155

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

Backward Traceability

SDS_QP_QF : QF Active Object Framework
DVP_QP_MC4_R10_03 : Rule 10.3(Required): The value of an expression shall not be assigned to an object with a narrower essential type or a different essential type category
DVP_QP_MC4_R11_03B : 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 : Suspicious pointer-to-pointer conversion (area too small)

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

Q_NEW
#define Q_NEW(evtT_, sig_,...)
Allocate a mutable (dynamic) event.
Definition qp.h:1168

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); // <===
// . . .

Definition at line 1168 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 of margin of free events left. If the event pool has 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 to provide the init() member functions. This init() function needs to take at least one parameter and must return the event pointer (me).

Backward Traceability

SDS_QP_QF : QF Active Object Framework
DVP_QP_MC4_R10_03 : Rule 10.3(Required): The value of an expression shall not be assigned to an object with a narrower essential type or a different essential type category
DVP_QP_MC4_R11_03B : 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 : Suspicious pointer-to-pointer conversion (area too small)

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

}

Q_NEW_X
#define Q_NEW_X(evtT_, margin_, sig_,...)
Non-asserting allocate a mutable (dynamic) event.
Definition qp.h:1182

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

}

Definition at line 1182 of file qp.h.

◆ Q_NEW_REF

#define Q_NEW_REF	(		evtRef_,
			evtT_ ) ((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 by means of the macro Q_DELETE_REF().

Parameters

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

Backward Traceability

SDS_QP_QF : QF Active Object Framework

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

Definition at line 1188 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 by means of the macro Q_DELETE_REF() to avoid leaking the event.

Parameters

[in,out] evtRef_ event reference to delete

Backward Traceability

SDS_QP_QF : QF Active Object Framework

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

Definition at line 1192 of file qp.h.

◆ QACTIVE_POST

#define QACTIVE_POST	(	me_,
		e_,
		sender_ ) ((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 Object Orientation)
[in]	e_	pointer to the event to post
[in]	sender_	pointer to the sender object.

Note: The sender_ parameter is actually 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 actually 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_()

Backward Traceability

QActive : Active object class (based on the QHsm implementation strategy)
DVP_QP_MC4_R11_03A : 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-PCLP-826 : Suspicious pointer-to-pointer conversion (area too small)

Definition at line 1199 of file qp.h.

◆ QACTIVE_POST_X

#define QACTIVE_POST_X	(	me_,
		e_,
		margin_,
		sender_ ) (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 Object Orientation)
[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 actually 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. In fact, if QACTIVE_POST_X() is called from an interrupt or other context, you can create a unique object just to unambiguously identify the sender of the event.

Backward Traceability

QActive : Active object class (based on the QHsm implementation strategy)
DVP_QP_MC4_R11_03A : 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-PCLP-826 : Suspicious pointer-to-pointer conversion (area too small)

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); // <===

}

. . .

QActive
Active object class (based on the QHsm implementation strategy)
Definition qp.h:779

Definition at line 1211 of file qp.h.

◆ QACTIVE_POST_LIFO

#define QACTIVE_POST_LIFO	(		me_,
			e_ ) (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 Object Orientation)
[in]	e_	pointer to the event to post

Backward Traceability

QActive : Active object class (based on the QHsm implementation strategy)
DVP_QP_MC4_R11_03A : 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-PCLP-826 : Suspicious pointer-to-pointer conversion (area too small)

Definition at line 1222 of file qp.h.

◆ QACTIVE_PUBLISH

#define QACTIVE_PUBLISH	(		e_,
			sender_ ) (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 actually 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.

Backward Traceability

QActive : Active object class (based on the QHsm implementation strategy)

Definition at line 1227 of file qp.h.

◆ QTIMEEVT_TICK_X

#define QTIMEEVT_TICK_X	(		tickRate_,
			sender_ ) (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 actually only used when QS software tracing is enabled (macro Q_SPY is defined)

Note: The sender_ parameter is actually 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 actually only used when QS software tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, the QTIMEEVT_TICK_X() macro does not use the sender_ parameter, so it does not need to be defined.

Backward Traceability

QTimeEvt : Time Event class

Definition at line 1238 of file qp.h.

◆ QTIMEEVT_TICK

#define QTIMEEVT_TICK ( sender_ ) QTIMEEVT_TICK_X(0U, (sender_))

Invoke the system clock tick processing for tick rate 0.

See also

QTimeEvt::QTimeEvt_tick_()

Definition at line 1247 of file qp.h.

◆ QTICKER_TRIG

#define QTICKER_TRIG	(		ticker_,
			sender_ ) (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 actually only used when QS software tracing is enabled (macro Q_SPY is defined)

Note: When QS software tracing is disabled, the macro not 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. In fact, 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.

Backward Traceability

QTicker : "Ticker" Active Object class

Definition at line 1251 of file qp.h.

◆ QF_CRIT_EXIT_NOP

#define QF_CRIT_EXIT_NOP ( ) ((void)0)

No-operation for exiting a critical section.

Details: In some QF ports the critical section exit takes effect only on the next machine instruction. If this next instruction is another entry to a critical section, the critical section won't be really exited, but rather the two adjacent critical sections would be merged. The QF_CRIT_EXIT_NOP() macro contains minimal code required to prevent such merging of critical sections in such merging of critical sections in QF ports, in which it can occur.

Definition at line 1261 of file qp.h.

◆ QF_TICK_X

#define QF_TICK_X	(		tickRate_,
			sender_ ) QTIMEEVT_TICK_X((tickRate_), (sender_))

Invoke the system clock tick processing.

Deprecated: superseded by QTIMEEVT_TICK_X()

Definition at line 1265 of file qp.h.

◆ QF_TICK

#define QF_TICK ( sender_ ) QTIMEEVT_TICK(sender_)

Invoke the system clock tick processing.

Deprecated: superseded by QTIMEEVT_TICK()

Definition at line 1268 of file qp.h.

◆ QF_PUBLISH

#define QF_PUBLISH	(		e_,
			sender_ ) QACTIVE_PUBLISH((e_), (sender_))

Definition at line 1271 of file qp.h.

◆ QF_MEM_SYS

#define QF_MEM_SYS ( ) ((void)0)

Definition at line 1275 of file qp.h.

◆ QF_MEM_APP

#define QF_MEM_APP ( ) ((void)0)

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

◆ enum_t

typedef int enum_t

Definition at line 99 of file qp.h.

◆ float32_t

typedef float float32_t

Alias for IEEE 754 32-bit floating point number.

Note: QP/C does not use floating-point types anywhere in the internal implementation, except in QS software tracing, where utilities for output of floating-point numbers are provided for application-specific trace records.

Definition at line 102 of file qp.h.

◆ float64_t

typedef double float64_t

Alias for IEEE 754 64-bit floating point number.

Note: QP/C does not use floating-point types anywhere in the internal implementation, except in QS software tracing, where utilities for output of floating-point numbers are provided for application-specific trace records.

Definition at line 105 of file qp.h.

◆ QSignal

typedef uint16_t QSignal

The signal of event QEvt.

Details: The relationship between an event and a signal is as follows. A signal in UML is the specification of an asynchronous stimulus that triggers reactions, and as such is an essential part of an event. (The signal conveys the type of the occurrence–what happened?) However, an event can also contain additional quantitative information about the occurrence in form of event parameters.

Definition at line 121 of file qp.h.

◆ QState

typedef enum QStateRet QState

Type returned from state-handler functions.

Definition at line 212 of file qp.h.

◆ QStateHandler

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

Pointer to a state-handler function.

Definition at line 215 of file qp.h.

◆ QActionHandler

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

Pointer to an action-handler function.

Definition at line 218 of file qp.h.

◆ QXThreadHandler

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

Pointer to an extended-thread handler function.

Definition at line 225 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 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 as 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 exactly 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 different meaning, depending on the specific RTOS/GPOS used. Priority threshold is supported in QP ports to ThreadX.

Definition at line 595 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 can be managed by the pool.

Definition at line 609 of file qp.h.

◆ QPSetBits

typedef uint32_t QPSetBits

Bitmask for the internal representation of QPSet elements.

Definition at line 624 of file qp.h.

◆ QEvtPtr

typedef QEvt const* QEvtPtr

Pointer to const event instances passed around in QP Framework.

Definition at line 768 of file qp.h.

Enumeration Type Documentation

◆ QStateRet

enum QStateRet

All possible values returned from state/action handlers

Note: The order of enumeration matters for algorithmic correctness.

Enumerator
Q_RET_SUPER	event passed to superstate to handle
Q_RET_UNHANDLED	event unhandled due to guard
Q_RET_HANDLED	event handled (internal transition)
Q_RET_IGNORED	event silently ignored (bubbled up to top)
Q_RET_ENTRY	state entry action executed
Q_RET_EXIT	state exit action executed
Q_RET_NULL	return value without any effect
Q_RET_TRAN	regular transition
Q_RET_TRAN_INIT	initial transition in a state
Q_RET_TRAN_HIST	transition to history of a given state

Definition at line 187 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 82 of file qf_act.c.

Variable Documentation

◆ QP_versionStr

char const QP_versionStr[16]

extern

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

◆ QEvt_reserved_

QEvt const QEvt_reserved_[4]

extern

Classes

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ QP_VERSION_STR

◆ QP_VERSION

◆ QP_RELEASE

◆ QEVT_INITIALIZER

◆ QEVT_DYNAMIC

◆ QASM_INIT

◆ QASM_DISPATCH

◆ QASM_IS_IN

◆ Q_ASM_UPCAST

◆ Q_HSM_UPCAST

◆ Q_MSM_UPCAST

◆ Q_EMPTY_SIG

◆ Q_ENTRY_SIG

◆ Q_EXIT_SIG

◆ Q_INIT_SIG

◆ Q_USER_SIG

◆ Q_TRAN

◆ Q_TRAN_HIST

◆ Q_SUPER

◆ Q_HANDLED

◆ Q_UNHANDLED

◆ Q_ACTION_NULL

◆ Q_EVT_CAST

◆ Q_STATE_CAST

◆ Q_ACTION_CAST

◆ Q_UNUSED_PAR

◆ Q_DIM

◆ Q_UINT2PTR_CAST

◆ QM_ENTRY

◆ QM_EXIT

◆ QM_SM_EXIT

◆ QM_TRAN

◆ QM_TRAN_INIT

◆ QM_TRAN_HIST

◆ QM_HANDLED

◆ QM_UNHANDLED

◆ QM_SUPER

◆ QM_STATE_NULL

◆ QF_NO_MARGIN

◆ Q_PRIO

◆ Q_NEW

◆ Q_NEW_X

◆ Q_NEW_REF

◆ Q_DELETE_REF

◆ QACTIVE_POST

◆ QACTIVE_POST_X

◆ QACTIVE_POST_LIFO

◆ QACTIVE_PUBLISH

◆ QTIMEEVT_TICK_X

◆ QTIMEEVT_TICK

◆ QTICKER_TRIG

◆ QF_CRIT_EXIT_NOP

◆ QF_TICK_X

◆ QF_TICK

◆ QF_PUBLISH

◆ QF_MEM_SYS

◆ QF_MEM_APP

Typedef Documentation

◆ int_t

◆ enum_t

◆ float32_t

◆ float64_t

◆ QSignal

◆ QState

◆ QStateHandler

◆ QActionHandler

◆ QXThreadHandler

◆ QPrioSpec

◆ QTimeEvtCtr

◆ QPSetBits

◆ QEvtPtr

Enumeration Type Documentation