QP/C  7.3.3
Real-Time Embedded Framework
Loading...
Searching...
No Matches
qp.h File Reference

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

Go to the source code of this file.

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   733U
 
#define QP_VERSION_STR   "7.3.3"
 
#define QP_RELEASE   0x70C4F752U
 Encrypted current QP release (7.3.3) and date (2024-03-01)
 
#define QEVT_MARKER   0xE0U
 
#define QEVT_DYNAMIC   0U
 
#define QEVT_INITIALIZER(sig_)   { (QSignal)(sig_), 0U, QEVT_MARKER }
 
#define QASM_INIT(me_, par_, qsId_)
 
#define QASM_DISPATCH(me_, e_, qsId_)    (*((QAsm *)(me_))->vptr->dispatch)((QAsm *)(me_), (e_), (qsId_))
 
#define QASM_IS_IN(me_, state_)    (*((QAsm *)(me_))->vptr->isIn)((QAsm *)(me_), (state_))
 
#define Q_ASM_UPCAST(ptr_)   ((QAsm *)(ptr_))
 
#define Q_HSM_UPCAST(ptr_)   ((QHsm *)(ptr_))
 
#define Q_MSM_UPCAST(ptr_)   ((QMsm *)(ptr_))
 
#define Q_TRAN(target_)
 
#define Q_TRAN_HIST(hist_)
 
#define Q_SUPER(super_)
 
#define Q_HANDLED()   ((QState)Q_RET_HANDLED)
 
#define Q_UNHANDLED()   ((QState)Q_RET_UNHANDLED)
 
#define Q_ACTION_NULL   ((QActionHandler)0)
 
#define Q_EVT_CAST(class_)   ((class_ const *)(e))
 
#define Q_STATE_CAST(handler_)   ((QStateHandler)(handler_))
 
#define Q_ACTION_CAST(action_)   ((QActionHandler)(action_))
 
#define Q_UNUSED_PAR(par_)   ((void)(par_))
 
#define Q_DIM(array_)   (sizeof(array_) / sizeof((array_)[0U]))
 
#define Q_UINT2PTR_CAST(type_, uint_)   ((type_ *)(uint_))
 
#define QM_ENTRY(state_)
 
#define QM_EXIT(state_)
 
#define QM_SM_EXIT(state_)
 
#define QM_TRAN(tatbl_)
 
#define QM_TRAN_INIT(tatbl_)
 
#define QM_TRAN_HIST(history_, tatbl_)
 
#define QM_TRAN_EP(tatbl_)
 
#define QM_TRAN_XP(xp_, tatbl_)
 
#define QM_HANDLED()   ((QState)Q_RET_HANDLED)
 
#define QM_UNHANDLED()   ((QState)Q_RET_UNHANDLED)
 
#define QM_SUPER()   ((QState)Q_RET_SUPER)
 
#define QM_SUPER_SUB(host_)
 
#define QM_STATE_NULL   ((QMState *)0)
 
#define QF_NO_MARGIN   ((uint_fast16_t)0xFFFFU)
 
#define Q_PRIO(prio_, pthre_)   ((QPrioSpec)((prio_) | ((pthre_) << 8U)))
 
#define Q_NEW(evtT_, sig_, ...)
 
#define Q_NEW_X(evtT_, margin_, sig_, ...)
 
#define Q_NEW_REF(evtRef_, evtT_)    ((evtRef_) = (evtT_ const *)QF_newRef_(e, (evtRef_)))
 
#define Q_DELETE_REF(evtRef_)
 
#define QACTIVE_START(me_, prioSpec_, qSto_, qLen_, stkSto_, stkSize_, par_)
 
#define QACTIVE_POST(me_, e_, sender_)    ((void)QActive_post_((me_), (e_), QF_NO_MARGIN, (sender_)))
 
#define QACTIVE_POST_X(me_, e_, margin_, sender_)    (QActive_post_((me_), (e_), (margin_), (sender_)))
 
#define QACTIVE_POST_LIFO(me_, e_)    (QActive_postLIFO_((me_), (e_)))
 
#define QACTIVE_PUBLISH(e_, sender_)    (QActive_publish_((e_), (void const *)(sender_), (sender_)->prio))
 
#define QTIMEEVT_TICK_X(tickRate_, sender_)   (QTimeEvt_tick_((tickRate_), (sender_)))
 
#define QTIMEEVT_TICK(sender_)   QTIMEEVT_TICK_X(0U, (sender_))
 
#define QTICKER_TRIG(ticker_, sender_)   (QTicker_trig_((ticker_), (sender_)))
 
#define QF_CRIT_EXIT_NOP()   ((void)0)
 
#define QF_TICK_X(tickRate_, sender_)   QTIMEEVT_TICK_X((tickRate_), (sender_))
 
#define QF_TICK(sender_)   QTIMEEVT_TICK(sender_)
 
#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
 
typedef int enum_t
 
typedef float float32_t
 
typedef double float64_t
 
typedef uint16_t QSignal
 
typedef enum QStateRet QState
 
typedef QState(* QStateHandler) (void *const me, QEvt const *const e)
 
typedef QState(* QActionHandler) (void *const me)
 
typedef void(* QXThreadHandler) (struct QXThread *const me)
 
typedef uint16_t QPrioSpec
 
typedef uint32_t QTimeEvtCtr
 
typedef uint32_t QPSetBits
 

Enumerations

enum  QStateRet {
  Q_RET_SUPER , Q_RET_SUPER_SUB , Q_RET_UNHANDLED , Q_RET_HANDLED ,
  Q_RET_IGNORED , Q_RET_ENTRY , Q_RET_EXIT , Q_RET_NULL ,
  Q_RET_TRAN , Q_RET_TRAN_INIT , Q_RET_TRAN_EP , Q_RET_TRAN_HIST ,
  Q_RET_TRAN_XP
}
 
enum  QReservedSig {
  Q_EMPTY_SIG , Q_ENTRY_SIG , Q_EXIT_SIG , Q_INIT_SIG ,
  Q_USER_SIG
}
 Reserved signals by the QHsm-style state machine implementation. More...
 

Functions

bool QMsm_isInState (QMsm const *const me, QMState const *const stateObj)
 
uint_fast8_t QF_LOG2 (QPSetBits const bitmask)
 

Variables

char const QP_versionStr [8]
 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.

Traceability

Definition in file qp.h.

Macro Definition Documentation

◆ QP_VERSION

#define QP_VERSION   733U

The current QP version as an unsigned number

Description
QP_VERSION is a decimal constant, where XX is a 1-digit or 2-digit major version number, Y is a 1-digit minor version number, and Z is a 1-digit release number.

Definition at line 47 of file qp.h.

◆ QP_VERSION_STR

#define QP_VERSION_STR   "7.3.3"

The current QP version as a zero terminated string literal.

Description
QP_VERSION_STR is of the form "XX.Y.Z", where XX is a 1-or 2-digit major version number, Y is a 1-digit minor version number, and Z is a 1-digit release number.

Definition at line 48 of file qp.h.

◆ QP_RELEASE

#define QP_RELEASE   0x70C4F752U

Encrypted current QP release (7.3.3) and date (2024-03-01)

Encrypted current QP release (7.3.0) and date (2023-06-30)

Definition at line 51 of file qp.h.

◆ QEVT_MARKER

#define QEVT_MARKER   0xE0U

QEvt memory marker (for internal integrity checks)

Description
The marker is implanted in bits 4:7 of QEvt:: evtTag_.

Definition at line 140 of file qp.h.

◆ QEVT_DYNAMIC

#define QEVT_DYNAMIC   0U

dummy parameter for dynamic event constructor (see QEvt_ctor())

Definition at line 143 of file qp.h.

◆ QEVT_INITIALIZER

#define QEVT_INITIALIZER (   sig_)    { (QSignal)(sig_), 0U, QEVT_MARKER }

Initializer for immutable (constant) QEvt instances

Description
This macro encapsulates the ugly casting of enumerated signals and the generation of the memory marker 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);
#define QEVT_INITIALIZER(sig_)
Definition qp.h:455
Event class.
Definition qp.h:147

Definition at line 455 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)
Abstract State Machine class (state machine interface)
Definition qp.h:277

Virtual 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".
Traceability
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;
}
#define QASM_INIT(me_, par_, qsId_)
Definition qp.h:459
#define QASM_DISPATCH(me_, e_, qsId_)
Definition qp.h:475
QP/C interface including the backwards-compatibility layer.

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

Description
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().
Traceability
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 475 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.

Description
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.
Traceability
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));
#define Q_STATE_CAST(handler_)
Definition qp.h:526
#define QASM_IS_IN(me_, state_)
Definition qp.h:486

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

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.
Parameters
[in,out]ptr_pointer to subclass of QAsm
Returns
The upcasted pointer to the QAsm base class
Traceability

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

See also
Q_ASM_UPCAST()
Parameters
[in,out]ptr_pointer to subclass of QHsm
Returns
The upcasted pointer to the QHsm base class
Traceability

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

See also
Q_ASM_UPCAST()
Parameters
[in,out]ptr_pointer to subclass of QMsm
Returns
The upcasted pointer to the QMsm base class
Traceability

Definition at line 496 of file qp.h.

◆ Q_TRAN

#define Q_TRAN (   target_)
Value:
((Q_ASM_UPCAST(me))->temp.fun = Q_STATE_CAST(target_), \
@ Q_RET_TRAN
regular transition
Definition qp.h:213
#define Q_ASM_UPCAST(ptr_)
Definition qp.h:490
enum QStateRet QState
Definition qp.h:223

Take transition to the specified target_ state

Traceability

Definition at line 499 of file qp.h.

◆ Q_TRAN_HIST

#define Q_TRAN_HIST (   hist_)
Value:
((Q_ASM_UPCAST(me))->temp.fun = (hist_), \
@ Q_RET_TRAN_HIST
transition to history of a given state
Definition qp.h:218

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

Traceability
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;
}
QState(* QStateHandler)(void *const me, QEvt const *const e)
Definition qp.h:226
#define Q_HANDLED()
Definition qp.h:514
@ Q_EXIT_SIG
signal for coding exit actions
Definition qp.h:258
#define Q_TRAN_HIST(hist_)
Definition qp.h:504
#define Q_SUPER(super_)
Definition qp.h:509
QSignal sig
Definition qp.h:151
Hierarchical State Machine class (QHsm-style state machine implementation strategy)
Definition qp.h:313

Definition at line 504 of file qp.h.

◆ Q_SUPER

#define Q_SUPER (   super_)
Value:
((Q_ASM_UPCAST(me))->temp.fun = Q_STATE_CAST(super_), \
@ Q_RET_SUPER
event passed to superstate to handle
Definition qp.h:197

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

Traceability
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;
}
#define Q_TRAN(target_)
Definition qp.h:499
@ Q_ENTRY_SIG
signal for coding entry actions
Definition qp.h:257

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

Traceability

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

Description
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 517 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 520 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_

Description
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
Traceability

Definition at line 523 of file qp.h.

◆ Q_STATE_CAST

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

Perform cast to QStateHandler.

Description
This macro encapsulates the cast of a specific state handler function pointer to QStateHandler, which violates MISRA:C-2023 Rule 11.1(R). This macro helps to localize this deviation.
Traceability
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);
}
int enum_t
Definition qp.h:109

Definition at line 526 of file qp.h.

◆ Q_ACTION_CAST

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

Perform cast to QActionHandler.

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

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

◆ Q_DIM

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

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

Description
This macro encapsulates the cast to (type_ *), which QP ports or application might use to access embedded hardware registers. Such uses can trigger PC-Lint "Note 923: cast from int to pointer" and this macro helps to encapsulate this deviation.

Definition at line 538 of file qp.h.

◆ QM_ENTRY

#define QM_ENTRY (   state_)
Value:
((Q_ASM_UPCAST(me))->temp.obj = (state_), \
@ Q_RET_ENTRY
state entry action executed
Definition qp.h:206

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

Traceability

Definition at line 542 of file qp.h.

◆ QM_EXIT

#define QM_EXIT (   state_)
Value:
((Q_ASM_UPCAST(me))->temp.obj = (state_), \
@ Q_RET_EXIT
state exit action executed
Definition qp.h:207

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

Traceability

Definition at line 554 of file qp.h.

◆ QM_SM_EXIT

#define QM_SM_EXIT (   state_)
Value:
((Q_ASM_UPCAST(me))->temp.obj = (state_), \

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

Traceability

Definition at line 565 of file qp.h.

◆ QM_TRAN

#define QM_TRAN (   tatbl_)
Value:
((Q_ASM_UPCAST(me))->temp.tatbl \
= (struct QMTranActTable const *)(tatbl_), \
Transition-Action Table for the QMsm State Machine.
Definition qp.h:248

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

Traceability

Definition at line 570 of file qp.h.

◆ QM_TRAN_INIT

#define QM_TRAN_INIT (   tatbl_)
Value:
((Q_ASM_UPCAST(me))->temp.tatbl \
= (struct QMTranActTable const *)(tatbl_), \
@ Q_RET_TRAN_INIT
initial transition in a state or submachine
Definition qp.h:214

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

Traceability

Definition at line 575 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_))), \

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

Traceability

Definition at line 580 of file qp.h.

◆ QM_TRAN_EP

#define QM_TRAN_EP (   tatbl_)
Value:
((Q_ASM_UPCAST(me))->temp.tatbl \
= (struct QMTranActTable const *)(tatbl_), \
@ Q_RET_TRAN_EP
entry-point transition into a submachine
Definition qp.h:215

Macro to call in a QM state-handler when it executes a transition to the submachine via an entry point.

Traceability

Definition at line 587 of file qp.h.

◆ QM_TRAN_XP

#define QM_TRAN_XP (   xp_,
  tatbl_ 
)
Value:
((((Q_ASM_UPCAST(me))->state.act = (xp_)), \
((Q_ASM_UPCAST(me))->temp.tatbl = \
(struct QMTranActTable const *)(tatbl_))), \
@ Q_RET_TRAN_XP
exit-point transition out of a submachine
Definition qp.h:219

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

Traceability

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

Description
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 602 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 605 of file qp.h.

◆ QM_SUPER_SUB

#define QM_SUPER_SUB (   host_)
Value:
((Q_ASM_UPCAST(me))->temp.obj = (host_), \
@ Q_RET_SUPER_SUB
event passed to submachine superstate
Definition qp.h:198

Macro to call in a QM submachine-handler when it designates the host state to handle an event. Applicable only to subclasses of QMsm.

Traceability

Definition at line 608 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 613 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 1154 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 1157 of file qp.h.

◆ Q_NEW

#define Q_NEW (   evtT_,
  sig_,
  ... 
)
Value:
(evtT_##_ctor((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
QF_NO_MARGIN, (sig_)), __VA_ARGS__))
#define QF_NO_MARGIN
Definition qp.h:1154

Allocate a mutable (dynamic) event.

Description
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
Note
When the configuration macro QEVT_DYN_CTOR is defined, the macro Q_NEW() becomes variadic and takes additional parameters, which are passed to the event constructor. In that case, you need to provide the constructor for each of your event classes derived from QEvt. This constructor needs to take at least one parameter and must return the event pointer (me).
Returns
A valid event pointer cast to the type evtT_.
Traceability
Usage
The following example illustrates non-variadic version of Q_NEW() (when QEVT_DYN_CTOR 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...
#define Q_NEW(evtT_, sig_,...)
Definition qp.h:1167

The following example illustrates variadic version of Q_NEW() (when QEVT_DYN_CTOR IS defined):

// event without parameters (QEVT_DYNAMIC passed to QEvt_ctor())
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_DYN_CTOR is defined, the ctor must be provided
static inline KeypressEvt * KeypressEvt_ctor(KeypressEvt * const me,
uint8_t keyId)
{
if (me != (KeypressEvt *)0) {
me->keyId = keyId;
}
return me;
}
// event with parameters (keyId passed to KeypressEvt_ctor())
KeypressEvt const *ke = Q_NEW(KeypressEvt, KEYPRESS_SIG, keyId); // <===
// . . .
#define QEVT_DYNAMIC
Definition qp.h:143

Definition at line 1167 of file qp.h.

◆ Q_NEW_X

#define Q_NEW_X (   evtT_,
  margin_,
  sig_,
  ... 
)
Value:
(evtT_##_ctor((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
(margin_), (sig_)), __VA_ARGS__))

Non-asserting allocate a mutable (dynamic) event.

Description
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.
Remarks
If QEVT_DYN_CTOR is defined, the Q_NEW_X() macro becomes variadic and takes all the arguments needed by the constructor of the event class being allocated.
Traceability
Usage
The following example illustrates non-variadic version of Q_NEW_X() (when QEVT_DYN_CTOR 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...
}
#define Q_NEW_X(evtT_, margin_, sig_,...)
Definition qp.h:1181
The following example illustrates variadic version of Q_NEW() (when QEVT_DYN_CTOR IS defined):
// event without parameters (QEVT_DYNAMIC passed to QEvt_ctor())
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_DYN_CTOR is defined, the ctor must be provided
static inline KeypressEvt * KeypressEvt_ctor(KeypressEvt * const me,
uint8_t keyId)
{
if (me != (KeypressEvt *)0) {
me->keyId = keyId;
}
return me;
}
// event with parameters (keyId passed to KeypressEvt_ctor())
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 1181 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

Description
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
Usage
The example defer in the directory examples/win32/defer illustrates the use of Q_NEW_REF()

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

Description
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
Usage
The example defer in the directory examples/win32/defer illustrates the use of Q_DELETE_REF()

Definition at line 1191 of file qp.h.

◆ QACTIVE_START

#define QACTIVE_START (   me_,
  prioSpec_,
  qSto_,
  qLen_,
  stkSto_,
  stkSize_,
  par_ 
)
Value:
(QActive_start_((QActive *)(me_), (prioSpec_), \
(qSto_), (qLen_), (stkSto_), (stkSize_), (par_)))
Active object class (based on the QHsm implementation strategy)
Definition qp.h:800

Start an Active Object.

Description
Starts execution of the AO and registers the AO with the framework.
Parameters
[in,out]me_current instance pointer (see Object Orientation)
[in]prioSpec_priority specification for the Active Object
[in]qSto_pointer to the storage for the ring buffer of the event queue (used only with the built-in QEQueue)
[in]qLen_length of the event queue (in events)
[in]stkSto_pointer to the stack storage (used only when per-AO stack is needed)
[in]stkSize_stack size (in bytes)
[in]par_pointer to the additional port-specific parameter(s) (might be NULL).
Usage
#include "qpc.h"
Q_DEFINE_THIS_FILE
int main() {
QF_init(); // initialize the framework and the underlying RT kernel
BSP_init(); // initialize the Board Support Package
. . .
// instantiate and start the active objects...
Blinky_ctor();
static QEvt const *l_blinkyQSto[10]; // Event queue storage for Blinky
QACTIVE_START(AO_Blinky, // AO pointer to start
1U, // unique QP priority of the AO
l_blinkyQSto, // storage for the AO's queue
Q_DIM(l_blinkyQSto), // length of the queue [entries]
(void *)0, // stack storage (not used in QK)
0U, // stack size [bytes] (not used in QK)
(void *)0); // initialization parameter (or 0)
. . .
return QF_run(); // run the QF application
}
#define QACTIVE_START(me_, prioSpec_, qSto_, qLen_, stkSto_, stkSize_, par_)
Definition qp.h:1197
#define Q_DIM(array_)
Definition qp.h:535
int_t QF_run(void)
Definition qutest.c:191
void QF_init(void)
Definition qutest.c:172

Definition at line 1197 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_()

Description
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 sendedr_ parameter is actually only used when QS tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, the QACTIVE_POST() macro does not pass the sender_ parameter, so the overhead of passing this extra parameter is entirely avoided.
The pointer to the sender object is not necessarily a pointer to an active object. In fact, if QACTIVE_POST() is called from an interrupt or other context, you can create a unique object just to unambiguously identify the sender of the event.
See also
QActive_post_()
Traceability

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

Description
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 tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, the POST_X() macro does not pass the sender_ parameter, so the overhead of passing this extra parameter is entirely avoided.
The pointer to the sender object is not necessarily a pointer to an active object. In fact, if 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.
Traceability
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); // <===
}
. . .

Definition at line 1215 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
Traceability

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

Description
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 pointer to the sender_ object is not necessarily a pointer to an active object. In fact, if QACTIVE_PUBLISH() is called from an interrupt or other context, you can create a unique object just to unambiguously identify the sender of the event.

Definition at line 1231 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_()

Description
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
When QS software tracing is disabled, the macro calls QTimeEvt_tick_() without the sender parameter, so the overhead of passing this extra parameter is entirely avoided.
The pointer to the sender object is not necessarily a pointer to an active object. In fact, when QTIMEEVT_TICK_X() is called from an interrupt, you would create a unique object just to unambiguously identify the ISR as the sender of the time events.

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

Definition at line 1251 of file qp.h.

◆ QTICKER_TRIG

#define QTICKER_TRIG (   ticker_,
  sender_ 
)    (QTicker_trig_((ticker_), (sender_)))

Asynchronously trigger the QTicker AO to perform tick processing.

Description
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 calls QTicker_trig_() without the sender parameter, so the overhead of passing this extra parameter is entirely avoided.
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.

Definition at line 1255 of file qp.h.

◆ QF_CRIT_EXIT_NOP

#define QF_CRIT_EXIT_NOP ( )    ((void)0)

No-operation for exiting a critical section

Description
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 1265 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 1269 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 1272 of file qp.h.

◆ QF_PUBLISH

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

Definition at line 1275 of file qp.h.

◆ QF_MEM_SYS

#define QF_MEM_SYS ( )    ((void)0)

Definition at line 1279 of file qp.h.

◆ QF_MEM_APP

#define QF_MEM_APP ( )    ((void)0)

Definition at line 1284 of file qp.h.

Typedef Documentation

◆ int_t

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

Definition at line 106 of file qp.h.

◆ enum_t

typedef int enum_t

Definition at line 109 of file qp.h.

◆ float32_t

Alias for IEEE 754 32-bit floating point number

Note
QP 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 112 of file qp.h.

◆ float64_t

Alias for IEEE 754 64-bit floating point number

Note
QP 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 115 of file qp.h.

◆ QSignal

The signal of event QEvt

Description
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 131 of file qp.h.

◆ QState

Type returned from state-handler functions.

Definition at line 223 of file qp.h.

◆ QStateHandler

QStateHandler

Pointer to a state-handler function.

Definition at line 226 of file qp.h.

◆ QActionHandler

QActionHandler

Pointer to an action-handler function.

Definition at line 229 of file qp.h.

◆ QXThreadHandler

QXThreadHandler

Pointer to an extended-thread handler function

Definition at line 236 of file qp.h.

◆ QPrioSpec

Priority specification for Active Objects in QP.

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

  1. 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).
  2. 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 619 of file qp.h.

◆ QTimeEvtCtr

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

Description
The dynamic range of this data type determines the maximum block size that can be managed by the pool.

Definition at line 633 of file qp.h.

◆ QPSetBits

Bitmask for the internal representation of QPSet elements

Definition at line 648 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_SUPER_SUB 

event passed to submachine superstate

Q_RET_UNHANDLED 

event unhandled due to a guard

Q_RET_HANDLED 

event handled (internal transition)

Q_RET_IGNORED 

event silently ignored (bubbled up to top)

Q_RET_ENTRY 

state entry action executed

Q_RET_EXIT 

state exit action executed

Q_RET_NULL 

return value without any effect

Q_RET_TRAN 

regular transition

Q_RET_TRAN_INIT 

initial transition in a state or submachine

Q_RET_TRAN_EP 

entry-point transition into a submachine

Q_RET_TRAN_HIST 

transition to history of a given state

Q_RET_TRAN_XP 

exit-point transition out of a submachine

Definition at line 195 of file qp.h.

◆ QReservedSig

Reserved signals by the QHsm-style state machine implementation.

Enumerator
Q_EMPTY_SIG 

signal to execute the default case

Q_ENTRY_SIG 

signal for coding entry actions

Q_EXIT_SIG 

signal for coding exit actions

Q_INIT_SIG 

signal for coding initial transitions

Q_USER_SIG 

offset for the user signals (QP Application)

Definition at line 255 of file qp.h.

Function Documentation

◆ QMsm_isInState()

bool QMsm_isInState ( QMsm const *const  me,
QMState const *const  stateObj 
)
Deprecated:
instead use: QASM_IS_IN()

Definition at line 412 of file qep_msm.c.

◆ QF_LOG2()

QF_LOG2 ( QPSetBits const  bitmask)

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

Definition at line 90 of file qf_act.c.

Variable Documentation

◆ QP_versionStr

char const QP_versionStr[8]
extern

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

◆ QEvt_reserved_

QEvt const QEvt_reserved_[4]
extern