Public QEP/C interface. More...

Data Structures
struct	QEvt

union	QHsmAttr

struct	QHsm

struct	QHsmVtable

struct	QMsm

struct	QMState

struct	QMTranActTable

Macros
#define	QP_VERSION 700U

#define	QP_VERSION_STR "7.0.0"

#define	QP_RELEASE 0x7CCAAA13U

#define	Q_SIGNAL_SIZE 2U

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

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

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

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

#define	QHSM_INIT(me_, par_, qs_id_)

#define	QHSM_DISPATCH(me_, e_, qs_id_) ((*(me_)->vptr->dispatch)((me_), (e_), (qs_id_)))

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

#define	Q_TRAN(target_) ((Q_HSM_UPCAST(me))->temp.fun = Q_STATE_CAST(target_), (QState)Q_RET_TRAN)

#define	Q_TRAN_HIST(hist_) ((Q_HSM_UPCAST(me))->temp.fun = (hist_), (QState)Q_RET_TRAN_HIST)

#define	Q_SUPER(super_) ((Q_HSM_UPCAST(me))->temp.fun = Q_STATE_CAST(super_), (QState)Q_RET_SUPER)

#define	Q_HANDLED() ((QState)Q_RET_HANDLED)

#define	Q_UNHANDLED() ((QState)Q_RET_UNHANDLED)

#define	Q_ACTION_NULL ((QActionHandler)0)

#define	QM_ENTRY(state_) ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_ENTRY)

#define	QM_EXIT(state_) ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)

#define	QM_SM_EXIT(state_) ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)

#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_) ((Q_HSM_UPCAST(me))->temp.obj = (host_), (QState)Q_RET_SUPER_SUB)

#define	QM_STATE_NULL ((QMState *)0)

Typedefs
typedef signed int	int_t

typedef signed int	enum_t

typedef float	float32_t

typedef double	float64_t

typedef uint16_t	QSignal

typedef uint_fast8_t	QState

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

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

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

Enumerations
enum	{ Q_RET_SUPER , Q_RET_SUPER_SUB , Q_RET_UNHANDLED , Q_RET_HANDLED , Q_RET_IGNORED , Q_RET_ENTRY , Q_RET_EXIT , Q_RET_NULL , Q_RET_TRAN , Q_RET_TRAN_INIT , Q_RET_TRAN_EP , Q_RET_TRAN_HIST , Q_RET_TRAN_XP }

enum	{ Q_ENTRY_SIG = 1 , Q_EXIT_SIG , Q_INIT_SIG , Q_USER_SIG }

Variables
char const	QP_versionStr [7]

Detailed Description

Date: Last updated on: 2021-12-23

Version: Last updated for: Version 7.0.0, 2022-04-30

Traceability:

traces to: RQP001

traces to: RQP101

Definition in file qep.h.

Macro Definition Documentation

◆ QP_VERSION

#define QP_VERSION 700U

The current QP version as a decimal constant XXYZ, where XX is a 2-digit major version number, Y is a 1-digit minor version number, and Z is a 1-digit release number.

Definition at line 42 of file qep.h.

◆ QP_VERSION_STR

#define QP_VERSION_STR "7.0.0"

The current QP version number string of the form XX.Y.Z, where XX is a 2-digit major version number, Y is a 1-digit minor version number, and Z is a 1-digit release number.

Definition at line 48 of file qep.h.

◆ QP_RELEASE

#define QP_RELEASE 0x7CCAAA13U

Encrypted current QP release (7.0.0) and date (2022-01-31)

Definition at line 51 of file qep.h.

◆ Q_SIGNAL_SIZE

#define Q_SIGNAL_SIZE 2U

Definition at line 83 of file qep.h.

◆ Q_EVT_CAST

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

Perform downcast of an event onto a subclass of QEvt class_

QEvt represents events without parameters and serves as the base class This macro encapsulates the downcast of QEvt pointers, which violates MISRA-C 2012 Rule 11.3(R) "A cast shall not be performed between a pointer to object type and a pointer to a different object type". This macro helps to localize this deviation.

Traceability:

traces to: RQP003

traces to: PQA11_3

Definition at line 158 of file qep.h.

◆ Q_UINT2PTR_CAST

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

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

This macro encapsulates the cast to (type_ *), which QP ports or application might use to access embedded hardware registers.

Definition at line 166 of file qep.h.

◆ Q_STATE_CAST

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

Perform cast to QStateHandler.

This macro encapsulates the cast of a specific state handler function pointer to QStateHandler, which violates MISRA:C-2012 Rule 11.1(req) "Conversions shall not be performed between a pointer to function and any other type". This macro helps to localize this deviation.

Traceability:

traces to: PQP11_1

traces to: PQA11_1

Usage: void Calc_ctor(Calc * const me) {

/* superclass' ctor */

QHsm_ctor(&me->super, Q_STATE_CAST(&Calc_initial));

me->operand1 = 0.0;

me->operand2 = 0.0;

me->len = 0U;

me->opKey = 0U;

}

Q_STATE_CAST
#define Q_STATE_CAST(handler_)
Definition: qep.h:196

QHsm::QHsm_ctor
void QHsm_ctor(QHsm *const me, QStateHandler initial)
Definition: qep_hsm.c:139

Definition at line 196 of file qep.h.

◆ Q_ACTION_CAST

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

Perform cast to QActionHandler.

This macro encapsulates the cast of a specific action handler function pointer to QActionHandler, which violates MISRA:C-2012 Rule 11.1(R) "Conversions shall not be performed between a pointer to function and any other type". This macro helps to localize this deviation.

Traceability:

traces to: PQP11_1

traces to: PQA11_1

Definition at line 207 of file qep.h.

◆ QHSM_INIT

#define QHSM_INIT	(	me_,
		par_,
		qs_id_
	)

Value:

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

Polymorphically executes the top-most initial transition in a HSM

Parameters

[in,out]	me_	pointer (see oop)
[in]	e_	constant pointer the QEvt or a class derived from QEvt (see oop)
[in]	qs_id_	QS local filter ID

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

Traceability:: traces to: RQP102

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

QMSM_INIT(&Calc_inst.super, (QEvt *)0); /* trigger initial transition */

for (;;) { /* event loop */

QEvt e;

. . .

/* wait for the next event and assign it to the event object e */

. . .

QMSM_DISPATCH(&Calc_inst.super, &e); /* dispatch e */

}

return 0;

}

Q_DEFINE_THIS_FILE
#define Q_DEFINE_THIS_FILE
Definition: qassert.h:87

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

QMSM_INIT
#define QMSM_INIT(me_, e_)
Definition: qpc.h:144

QMSM_DISPATCH
#define QMSM_DISPATCH(me_, e_)
Definition: qpc.h:148

QEvt
Definition: qep.h:119

Definition at line 296 of file qep.h.

◆ QHSM_DISPATCH

#define QHSM_DISPATCH	(	me_,
		e_,
		qs_id_
	)	((*(me_)->vptr->dispatch)((me_), (e_), (qs_id_)))

Polymorphically dispatches an event to a HSM

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

Parameters

[in,out]	me_	pointer (see oop)
[in]	e_	constant pointer the QEvt or a class derived from QEvt (see oop)

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

Traceability:: traces to: RQP102

Definition at line 330 of file qep.h.

◆ Q_HSM_UPCAST

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

Perform upcast from a subclass of QHsm to the base class QHsm

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 oop), 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 2012 Rule 11.3(req) "A cast shall not be performed between a pointer to object type and a pointer to a different object type". This macro encapsulates this deviation and provides a descriptive name for the reason of this cast.

Definition at line 365 of file qep.h.

◆ Q_TRAN

#define Q_TRAN ( target_ ) ((Q_HSM_UPCAST(me))->temp.fun = Q_STATE_CAST(target_), (QState)Q_RET_TRAN)

Macro to call in a state-handler when it executes a regular or and initial transition. Applicable only to QHsm subclasses.

Traceability:

traces to: RQP103

traces to: RQP120E

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_HANDLED
#define Q_HANDLED()
Definition: qep.h:554

Q_TRAN
#define Q_TRAN(target_)
Definition: qep.h:526

QState
uint_fast8_t QState
Definition: qep.h:170

Q_SUPER
#define Q_SUPER(super_)
Definition: qep.h:548

Q_ENTRY_SIG
@ Q_ENTRY_SIG
Definition: qep.h:688

QEvt::sig
QSignal sig
Definition: qep.h:123

QHsm::QHsm_top
QState QHsm_top(void const *const me, QEvt const *const e)
Definition: qep_hsm.c:261

Definition at line 526 of file qep.h.

◆ Q_TRAN_HIST

#define Q_TRAN_HIST ( hist_ ) ((Q_HSM_UPCAST(me))->temp.fun = (hist_), (QState)Q_RET_TRAN_HIST)

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

Traceability:

traces to: RQP103

traces to: RQP120H

Usage: typedef struct {

QHsm super; /* inherit QHsm */

QStateHandler hist_doorClosed; /* history of doorClosed */

} ToastOven;

/*..........................................................*/

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

}

/*..........................................................*/

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

}

QStateHandler
QState(* QStateHandler)(void *const me, QEvt const *const e)
Definition: qep.h:176

Q_TRAN_HIST
#define Q_TRAN_HIST(hist_)
Definition: qep.h:537

Q_EXIT_SIG
@ Q_EXIT_SIG
Definition: qep.h:689

QHsm
Definition: qep.h:253

QHsm::QHsm_state
static QStateHandler QHsm_state(QHsm *const me)
Definition: qep.h:373

Definition at line 537 of file qep.h.

◆ Q_SUPER

#define Q_SUPER ( super_ ) ((Q_HSM_UPCAST(me))->temp.fun = Q_STATE_CAST(super_), (QState)Q_RET_SUPER)

Macro to call in a state-handler when it designates the superstate of a given state. Applicable only to QHsm subclasses.

Traceability:: traces to: RQP103

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;

}

Definition at line 548 of file qep.h.

◆ Q_HANDLED

#define Q_HANDLED ( ) ((QState)Q_RET_HANDLED)

Macro to call in a state-handler when it handles an event.

Traceability:

traces to: RQP103

traces to: RQP120B

traces to: RQP120C

Definition at line 554 of file qep.h.

◆ Q_UNHANDLED

#define Q_UNHANDLED ( ) ((QState)Q_RET_UNHANDLED)

Macro to call in a state-handler when it attempts to handle an event but a guard condition evaluates to 'false' and there is no other explicit way of handling the event. Applicable only to QHsm subclasses.

Definition at line 560 of file qep.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 565 of file qep.h.

◆ QM_ENTRY

#define QM_ENTRY ( state_ ) ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_ENTRY)

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

Definition at line 602 of file qep.h.

◆ QM_EXIT

#define QM_EXIT ( state_ ) ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)

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

Definition at line 608 of file qep.h.

◆ QM_SM_EXIT

#define QM_SM_EXIT ( state_ ) ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)

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

Definition at line 621 of file qep.h.

◆ QM_TRAN

#define QM_TRAN ( tatbl_ )

Value:

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

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

Q_RET_TRAN

@ Q_RET_TRAN

Definition: qep.h:589

Q_HSM_UPCAST

#define Q_HSM_UPCAST(ptr_)

Definition: qep.h:365

QMTranActTable

Definition: qep.h:452

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

Definition at line 627 of file qep.h.

◆ QM_TRAN_INIT

#define QM_TRAN_INIT ( tatbl_ )

Value:

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

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

Q_RET_TRAN_INIT

@ Q_RET_TRAN_INIT

Definition: qep.h:590

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

Definition at line 633 of file qep.h.

◆ QM_TRAN_HIST

#define QM_TRAN_HIST	(	history_,
		tatbl_
	)

Value:

    ((((Q_HSM_UPCAST(me))->state.obj  = (history_)),                        \
      ((Q_HSM_UPCAST(me))->temp.tatbl = (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.

Definition at line 639 of file qep.h.

◆ QM_TRAN_EP

#define QM_TRAN_EP ( tatbl_ )

Value:

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

= (QMTranActTable const *)(tatbl_), (QState)Q_RET_TRAN_EP)

Q_RET_TRAN_EP

@ Q_RET_TRAN_EP

Definition: qep.h:591

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

Definition at line 647 of file qep.h.

◆ QM_TRAN_XP

#define QM_TRAN_XP	(	xp_,
		tatbl_
	)

Value:

    ((((Q_HSM_UPCAST(me))->state.act  = (xp_)),                             \
      ((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_))), \
     (QState)Q_RET_TRAN_XP)

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

Definition at line 653 of file qep.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 661 of file qep.h.

◆ QM_UNHANDLED

#define QM_UNHANDLED ( ) ((QState)Q_RET_UNHANDLED)

Macro to call in a QM state-handler when when it attempts to handle an event but a guard condition evaluates to 'false' and there is no other explicit way of handling the event. Applicable only to QMsm subclasses.

Definition at line 668 of file qep.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 673 of file qep.h.

◆ QM_SUPER_SUB

#define QM_SUPER_SUB ( host_ ) ((Q_HSM_UPCAST(me))->temp.obj = (host_), (QState)Q_RET_SUPER_SUB)

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

Definition at line 678 of file qep.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 QP::QMsm.

Definition at line 684 of file qep.h.

Typedef Documentation

◆ int_t

typedef signed int int_t

typedef for line numbers in assertions and return from QF_run()

Definition at line 57 of file qep.h.

◆ enum_t

typedef signed int enum_t

typedef for enumerations used for event signals

Definition at line 60 of file qep.h.

◆ float32_t

typedef float float32_t

IEEE 754 32-bit floating point number, MISRA-C 2012 Dir 4.6(A)

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 68 of file qep.h.

◆ float64_t

typedef double float64_t

IEEE 754 64-bit floating point number, MISRA-C 2012 Dir 4.6(A)

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 76 of file qep.h.

◆ QSignal

typedef uint16_t QSignal

The size (in bytes) of the signal of an event. Valid values: 1U, 2U, or 4U; default 2U

This macro can be defined in the QEP port file (qep_port.h) to configure the QSignal type. When the macro is not defined, the default of 2 bytes is applied.

Traceability:: traces to: RQP002A

Definition at line 97 of file qep.h.

◆ QState

typedef uint_fast8_t QState

typedef of the return type from a state/action-handler functions.

Definition at line 170 of file qep.h.

◆ QStateHandler

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

Pointer to a state-handler function.

Definition at line 176 of file qep.h.

◆ QActionHandler

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

Pointer to an action-handler function.

Definition at line 179 of file qep.h.

◆ QXThreadHandler

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

Pointer to a thread-handler function.

Definition at line 182 of file qep.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

All possible values returned from state/action handlers

Note: The order 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 571 of file qep.h.

◆ anonymous enum

anonymous enum

QEP reserved signals

Enumerator
Q_ENTRY_SIG	signal for coding entry actions
Q_EXIT_SIG	signal for coding exit actions
Q_INIT_SIG	signal for coding initial transitions
Q_USER_SIG	first signal that can be used for user signals

Definition at line 687 of file qep.h.

Variable Documentation

◆ QP_versionStr

char const QP_versionStr[7]

extern

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

Definition at line 47 of file qep_hsm.c.

Data Structures

Macros

Typedefs

Enumerations

Variables

Detailed Description

Macro Definition Documentation

◆ QP_VERSION

◆ QP_VERSION_STR

◆ QP_RELEASE

◆ Q_SIGNAL_SIZE

◆ Q_EVT_CAST

◆ Q_UINT2PTR_CAST

◆ Q_STATE_CAST

◆ Q_ACTION_CAST

◆ QHSM_INIT

◆ QHSM_DISPATCH

◆ Q_HSM_UPCAST

◆ Q_TRAN

◆ Q_TRAN_HIST

◆ Q_SUPER

◆ Q_HANDLED

◆ Q_UNHANDLED

◆ Q_ACTION_NULL

◆ QM_ENTRY

◆ QM_EXIT

◆ QM_SM_EXIT

◆ QM_TRAN

◆ QM_TRAN_INIT

◆ QM_TRAN_HIST

◆ QM_TRAN_EP

◆ QM_TRAN_XP

◆ QM_HANDLED

◆ QM_UNHANDLED

◆ QM_SUPER

◆ QM_SUPER_SUB

◆ QM_STATE_NULL

Typedef Documentation

◆ int_t

◆ enum_t

◆ float32_t

◆ float64_t

◆ QSignal

◆ QState

◆ QStateHandler

◆ QActionHandler

◆ QXThreadHandler

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

Variable Documentation

◆ QP_versionStr