Public QEP/C interface. More...

#include "qevt.h"

Data Structures
struct	QFsm
	Finite State Machine. More...
Defines
#define	Q_STATE_CAST(handler_) ((QStateHandler)(handler_))
	Perform cast to QStateHandler.
#define	QFsm_ctor(me_, initial_)
	Protected "constructor" of a FSM.
#define	QHsm_ctor(me_, initial_)
	protected "constructor" of a HSM. Performs the first step of HSM initialization by assigning the initial pseudostate to the currently active state of the state machine.
#define	QHsm_state(me_) (Q_STATE_CAST((me_)->state))
	Obtain the current active state from a HSM (read only).
#define	Q_RET_HANDLED ((QState)0)
	Value returned by a state-handler function when it handles the event.
#define	Q_HANDLED() (Q_RET_HANDLED)
	Macro to specify the return of a state-handler function when it handles the event.
#define	Q_RET_IGNORED ((QState)1)
	Macro to specify the return of a state-handler function when it ignores (does not handle in any way) the event.
#define	Q_IGNORED() (Q_RET_IGNORED)
	The macro returned from a non-hierarchical state-handler function when it ignores (does not handle) the event.
#define	Q_RET_TRAN ((QState)2)
	Value returned by a state-handler function when it takes a regular state transition.
#define	Q_TRAN(target_) (((QFsm *)me)->temp = Q_STATE_CAST(target_), Q_RET_TRAN)
	Designates a target for an initial or regular transition. Q_TRAN() can be used both in the FSMs and HSMs.
#define	Q_RET_SUPER ((QState)3)
	Value returned by a state-handler function when it forwards the event to the superstate to handle.
#define	Q_SUPER(super_) (((QHsm *)me)->temp = Q_STATE_CAST(super_), Q_RET_SUPER)
	Designates the superstate of a given state in an HSM.
#define	Q_RET_UNHANDLED ((QState)4)
	Value returned by a state-handler function when a guard condition prevents it from handling the event.
#define	Q_UNHANDLED() (Q_RET_UNHANDLED)
	Macro to specify the return of a state-handler function when it attempts to handle the event but a guard condition evaluates to false and there is no other explicit way of handling the event.
Typedefs
typedef uint8_t	QState
	Type returned from a state-handler function.
typedef QState(*	QStateHandler )(void const me, QEvt const const e)
	pointer to state-handler function
typedef struct QFsmTag	QHsm
	Hierarchical State Machine.
Enumerations
enum	QReservedSignals { Q_ENTRY_SIG = 1, Q_EXIT_SIG, Q_INIT_SIG, Q_USER_SIG }
	QEP reserved signals. More...
Functions
char_t const Q_ROM *Q_ROM_VAR	QEP_getVersion (void)
	obtain the current QEP version number string
void	QFsm_init (QFsm const me, QEvt const const e)
	Performs the second step of FSM initialization by triggering the top-most initial transition.
void	QFsm_dispatch (QFsm const me, QEvt const const e)
	Dispatches an event to a FSM.
void	QHsm_init (QHsm const me, QEvt const const e)
	Performs the second step of HSM initialization by triggering the top-most initial transition.
void	QHsm_dispatch (QHsm const me, QEvt const const e)
	Dispatches an event to a HSM.
uint8_t	QHsm_isIn (QHsm *const me, QStateHandler const state)
	Tests if a given state is part of the current active state configuration.
QState	QHsm_top (void const const me, QEvt const const e)
	the top-state.

Detailed Description

Public QEP/C interface.

This header file must be included, perhaps indirectly, in all modules (*.c files) that use QEP/C

Definition in file qep.h.

Define Documentation

#define Q_HANDLED ( ) (Q_RET_HANDLED)

Macro to specify the return of a state-handler function when it handles the event.

You call that macro after the return statement (return Q_HANDLED();) Q_HANDLED() can be used both in the FSMs and HSMs.

Definition at line 245 of file qep.h.

#define Q_IGNORED ( ) (Q_RET_IGNORED)

The macro returned from a non-hierarchical state-handler function when it ignores (does not handle) the event.

You call that macro after the return statement (return Q_IGNORED();)

Definition at line 259 of file qep.h.

Referenced by QHsm_top().

#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 2004 rule 11.4(advisory). This macro helps to localize this deviation.

Definition at line 73 of file qep.h.

Referenced by QFsm_init(), and QHsm_init().

#define Q_SUPER ( super_ ) (((QHsm *)me)->temp = Q_STATE_CAST(super_), Q_RET_SUPER)

Designates the superstate of a given state in an HSM.

Definition at line 283 of file qep.h.

#define Q_TRAN ( target_ ) (((QFsm *)me)->temp = Q_STATE_CAST(target_), Q_RET_TRAN)

Designates a target for an initial or regular transition. Q_TRAN() can be used both in the FSMs and HSMs.

Definition at line 271 of file qep.h.

#define QFsm_ctor	(	me_,
		initial_
	)

Value:

do { \
    (me_)->state = Q_STATE_CAST(0); \
    (me_)->temp  = (initial_); \
} while (0)

Protected "constructor" of a FSM.

Performs the first step of FSM initialization by assigning the initial pseudostate to the currently active state of the state machine.

Note:: Must be called only by the "constructors" of the derived state machines.; Must be called only ONCE before QFsm_init().

The following example illustrates how to invoke QFsm_ctor() in the "constructor" of a derived state machine:

void QBomb_ctor(QBomb *me) {
    QFsm_ctor(&me->super, (QStateHandler)&QBomb_initial);/* superclass ctor */
}

Definition at line 109 of file qep.h.

#define QHsm_ctor	(	me_,
		initial_
	)

Value:

do { \
    (me_)->state = Q_STATE_CAST(&QHsm_top); \
    (me_)->temp  = (initial_); \
} while (0)

protected "constructor" of a HSM. Performs the first step of HSM initialization by assigning the initial pseudostate to the currently active state of the state machine.

Note:: Must be called only by the "constructors" of the derived state machines.; Must be called before QHsm_init().

The following example illustrates how to invoke QHsm_ctor() in the "constructor" of a derived state machine:

void QCalc_ctor(QCalc *me) {
    QHsm_ctor(&me->super, (QStateHandler)&QCalc_initial);
}

Definition at line 177 of file qep.h.

Typedef Documentation

typedef struct QFsmTag QHsm

Hierarchical State Machine.

QHsm represents a Hierarchical Finite State Machine (HSM) with full support for hierarchical nesting of states, entry/exit actions, and initial transitions in any composite state.

Note:: QHsm is not intended to be instantiated directly, but rather serves as the base structure for derivation of state machines in the application code.

The following example illustrates how to derive a state machine structure from QHsm. Please note that the QHsm member super is defined as the FIRST member of the derived struct.

typedef struct QCalcTag {
    QHsm super;                                        /* derives from QHsm */
    double operand1;
    double operand2;
    char display[DISP_WIDTH + 1];
    uint8_t len;
    uint8_t opKey;
} QCalc;

See also:: Encapsulation and Single Inheritance in C

Definition at line 160 of file qep.h.

Enumeration Type Documentation

enum QReservedSignals

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 in user applications

Definition at line 299 of file qep.h.

Function Documentation

char_t const Q_ROM* Q_ROM_VAR QEP_getVersion ( void )

obtain the current QEP version number string

Returns:: version of the QEP as a constant 6-character string of the form x.y.zz, where x is a 1-digit major version number, y is a 1-digit minor version number, and zz is a 2-digit release number.

Definition at line 52 of file qep.c.

References QP_VERSION.

void QFsm_dispatch	(	QFsm *const	me,
		QEvt const *const	e
	)

Dispatches an event to a FSM.

Processes one event at a time in Run-to-Completion fashion. The argument me is the pointer the state machine structure derived from QFsm. The argument e is a constant pointer the QEvt or a structure derived from QEvt.

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

See also:: example for QFsm_init()
Encapsulation and Single Inheritance in C

Definition at line 47 of file qfsm_dis.c.

References Q_REQUIRE, Q_RET_HANDLED, Q_RET_TRAN, Q_RET_UNHANDLED, QEP_ENTER_, QEP_EXIT_, QS_BEGIN_, QS_CRIT_STAT_, QS_END_, QS_FUN_, QS_OBJ_, QS_QEP_DISPATCH, QS_QEP_IGNORED, QS_QEP_INTERN_TRAN, QS_QEP_TRAN, QS_QEP_UNHANDLED, QS_smObj_, and QS_TIME_.

void QFsm_init	(	QFsm *const	me,
		QEvt const *const	e
	)

Performs the second step of FSM initialization by triggering the top-most initial transition.

Parameters:

me	pointer the state machine structure derived from QFsm
e	constant pointer the QEvt or a structure derived from QEvt

Note:: Must be called only ONCE after the "constructor" QFsm_ctor().

The following example illustrates how to initialize a FSM, and dispatch events to it:

#include "qep.h"                                  /* QEP/C public interface */
#include "qbomb.h"                           /* QBomb FSM derived from QFsm */

static QBomb l_qbomb;                           /* an instance of QBomb FSM */

int main() {
    QBombInitEvt ie;                  /* initialization event for QBomb FSM */

    QBomb_ctor(&l_qbomb);   /* QBomb FSM "constructor" invokes QFsm_ctor_() */

    /* set the initialization event ie */

    QFsm_init((QFsm *)&l_qbomb, &ie);         /* trigger initial transition */

    for (;;) {                                                /* event loop */
        QEvent e;
        . . .
        /* wait for the next event and assign it to the event object e */
        . . .
        QFsm_dispatch((QFsm *)&l_qbomb, &e);       /* dispatch e to l_qbomb */
    }
    return 0;
}

Definition at line 47 of file qfsm_ini.c.

References Q_ALLEGE, Q_ENTRY_SIG, Q_REQUIRE, Q_RET_TRAN, Q_STATE_CAST, QEP_TRIG_, QS_BEGIN_, QS_CRIT_STAT_, QS_END_, QS_FUN_, QS_OBJ_, QS_QEP_INIT_TRAN, QS_QEP_STATE_INIT, QS_smObj_, and QS_TIME_.

void QHsm_dispatch	(	QHsm *const	me,
		QEvt const *const	e
	)

Dispatches an event to a HSM.

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

Parameters:

me	is the pointer the state machine structure derived from QHsm.
e	is a constant pointer the QEvt or a structure derived from QEvt.

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

See also:: example for QHsm_init()
Encapsulation and Single Inheritance in C

Definition at line 47 of file qhsm_dis.c.

References Q_ASSERT, Q_EXIT_SIG, Q_INIT_SIG, Q_REQUIRE, Q_RET_HANDLED, Q_RET_IGNORED, Q_RET_SUPER, Q_RET_TRAN, Q_RET_UNHANDLED, QEP_EMPTY_SIG_, QEP_ENTER_, QEP_EXIT_, QEP_MAX_NEST_DEPTH_, QEP_TRIG_, QS_BEGIN_, QS_CRIT_STAT_, QS_END_, QS_FUN_, QS_OBJ_, QS_QEP_DISPATCH, QS_QEP_IGNORED, QS_QEP_INTERN_TRAN, QS_QEP_STATE_EXIT, QS_QEP_STATE_INIT, QS_QEP_TRAN, QS_QEP_UNHANDLED, QS_smObj_, and QS_TIME_.

void QHsm_init	(	QHsm *const	me,
		QEvt const *const	e
	)

Performs the second step of HSM initialization by triggering the top-most initial transition.

Parameters:

me	pointer the state machine structure derived from QHsm
e	constant pointer the QEvt or a structure derived from QEvt

Note:: Must be called only ONCE after the "constructor" QHsm_ctor().

The following example illustrates how to initialize a HSM, and dispatch events to it:

#include "qep.h"                                  /* QEP/C public interface */
#include "qcalc.h"                           /* QCalc HSM derived from QHsm */

static QCalc l_qcalc;                           /* an instance of QCalc HSM */

int main() {
    QCalc_ctor(&l_qcalc);   /* QCalc HSM "constructor" invokes QHsm_ctor_() */

    QHsm_init((QHsm *)&l_qcalc, (QEvent *)0); /* trigger initial transition */

    for (;;) {                                                /* event loop */
        QEvent e;
        . . .
        /* wait for the next event and assign it to the event object e */
        . . .
        QHsm_dispatch((QHsm *)&l_qcalc, (QEvent *)&e);        /* dispatch e */
    }
    return 0;
}

Definition at line 47 of file qhsm_ini.c.

References Q_ALLEGE, Q_ASSERT, Q_INIT_SIG, Q_REQUIRE, Q_RET_TRAN, Q_STATE_CAST, QEP_EMPTY_SIG_, QEP_ENTER_, QEP_MAX_NEST_DEPTH_, QEP_TRIG_, QHsm_top(), QS_BEGIN_, QS_CRIT_STAT_, QS_END_, QS_FUN_, QS_OBJ_, QS_QEP_INIT_TRAN, QS_QEP_STATE_INIT, QS_smObj_, and QS_TIME_.

uint8_t QHsm_isIn	(	QHsm *const	me,
		QStateHandler const	state
	)

Tests if a given state is part of the current active state configuration.

Parameters:

me	is the pointer the state machine structure derived from QHsm.
state	is a pointer to the state handler function, e.g., &QCalc_on.

Definition at line 47 of file qhsm_in.c.

References Q_REQUIRE, Q_RET_IGNORED, QEP_EMPTY_SIG_, and QEP_TRIG_.

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

the top-state.

QHsm_top() is the ultimate root of state hierarchy in all HSMs derived from QHsm. This state handler always returns (QState)0, which means that it "handles" all events.

See also:: Example of the QCalc_on() state handler for Q_INIT().

Definition at line 44 of file qhsm_top.c.

References Q_IGNORED.

Referenced by QHsm_init().

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation