qep.h File Reference

Public QEP/C interface. More...

#include "qevent.h"
#include "qs_port.h"

Data Structures
struct	QFsm
	Finite State Machine. More...
Defines
#define	QFsm_ctor(me_, initial_) ((me_)->state = (initial_))
	Protected "constructor" of a FSM.
#define	QHsm_ctor(me_, initial_) ((me_)->state = (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	Q_RET_IGNORED ((QState)1)
	Value returned by a non-hierarchical state-handler function when it ignores (does not handle) 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_HANDLED ((QState)0)
	Value returned by a state-handler function when it handles the event.
#define	Q_HANDLED() (Q_RET_HANDLED)
	Value returned by a state-handler function when it handles 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)->state = (QStateHandler)(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 cannot handle the event.
#define	Q_SUPER(super_) (((QHsm *)me)->state = (QStateHandler)(super_), Q_RET_SUPER)
	Designates the superstate of a given state in an HSM.
#define	QS_SIG_(sig_) QS_u8_(sig_)
	Internal QS macro to output an unformatted event signal data element.
Typedefs
typedef uint8_t	QState
	Type returned from a state-handler function.
typedef QState(*	QStateHandler )(void me, QEvent 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 const Q_ROM *Q_ROM_VAR	QEP_getVersion (void)
	obtain the current QEP version number string
void	QFsm_init (QFsm me, QEvent const e)
	Performs the second step of FSM initialization by triggering the top-most initial transition.
void	QFsm_dispatch (QFsm me, QEvent const e)
	Dispatches an event to a FSM.
void	QHsm_init (QHsm me, QEvent const e)
	Performs the second step of HSM initialization by triggering the top-most initial transition.
void	QHsm_dispatch (QHsm me, QEvent const e)
	Dispatches an event to a HSM.
uint8_t	QHsm_isIn (QHsm *me, QStateHandler state)
	Tests if a given state is part of the current active state configuratioin.
QState	QHsm_top (QHsm me, QEvent 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)

Value returned by 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 234 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 219 of file qep.h.

Referenced by QHsm_top().

#define Q_SUPER ( super_ ) (((QHsm *)me)->state = (QStateHandler)(super_), Q_RET_SUPER)

Designates the superstate of a given state in an HSM.

Definition at line 260 of file qep.h.

#define Q_TRAN ( target_ ) (((QFsm *)me)->state = (QStateHandler)(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 247 of file qep.h.

#define QFsm_ctor	(	me_,
		initial_		)	((me_)->state = (initial_))

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

#define QHsm_ctor	(	me_,
		initial_		)	((me_)->state = (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.

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

See also:: QFsm_ctor

Definition at line 159 of file qep.h.

#define QS_SIG_ ( sig_ ) QS_u8_(sig_)

Internal QS macro to output an unformatted event signal data element.

Note:: the size of the pointer depends on the macro Q_SIGNAL_SIZE.

Definition at line 286 of file qep.h.

Referenced by QActive_get_(), QActive_postFIFO(), QActive_postLIFO(), QActive_subscribe(), QActive_unsubscribe(), QActive_unsubscribeAll(), QEQueue_get(), QEQueue_postFIFO(), QEQueue_postLIFO(), QF_gc(), QF_new_(), QF_publish(), QF_tick(), QFsm_dispatch(), and QHsm_dispatch().

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

Function Documentation

char 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 46 of file qep.c.

References Q_ROM, Q_ROM_VAR, and QP_VERSION.

void QFsm_dispatch	(	QFsm *	me,
		QEvent 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 QEvent or a structure derived from QEvent.

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 37 of file qfsm_dis.c.

References Q_ENTRY_SIG, Q_EXIT_SIG, Q_RET_HANDLED, Q_RET_TRAN, QEP_TRIG_, QS_BEGIN_, QS_END_, QS_FUN_, QS_INT_LOCK_KEY_, QS_OBJ_, QS_QEP_IGNORED, QS_QEP_INTERN_TRAN, QS_QEP_TRAN, QS_SIG_, QS_smObj_, QEvent::sig, and QFsm::state.

void QFsm_init	(	QFsm *	me,
		QEvent 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 QEvent or a structure derived from QEvent

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 40 of file qfsm_ini.c.

References Q_ALLEGE, Q_ENTRY_SIG, Q_RET_TRAN, QEP_TRIG_, QS_BEGIN_, QS_END_, QS_FUN_, QS_INT_LOCK_KEY_, QS_OBJ_, QS_QEP_INIT_TRAN, QS_QEP_STATE_INIT, and QS_smObj_.

void QHsm_dispatch	(	QHsm *	me,
		QEvent 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 QEvent or a structure derived from QEvent.

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 40 of file qhsm_dis.c.

References Q_ASSERT, Q_EXIT_SIG, Q_INIT_SIG, Q_RET_HANDLED, Q_RET_IGNORED, Q_RET_SUPER, Q_RET_TRAN, QEP_EMPTY_SIG_, QEP_ENTER_, QEP_EXIT_, QEP_MAX_NEST_DEPTH_, QEP_TRIG_, QS_BEGIN_, QS_END_, QS_FUN_, QS_INT_LOCK_KEY_, QS_OBJ_, QS_QEP_DISPATCH, QS_QEP_IGNORED, QS_QEP_INTERN_TRAN, QS_QEP_STATE_EXIT, QS_QEP_STATE_INIT, QS_QEP_TRAN, QS_SIG_, and QS_smObj_.

void QHsm_init	(	QHsm *	me,
		QEvent 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 QEvent or a structure derived from QEvent

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 40 of file qhsm_ini.c.

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

uint8_t QHsm_isIn	(	QHsm *	me,
		QStateHandler	state
	)

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

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 37 of file qhsm_in.c.

References Q_RET_IGNORED, QEP_EMPTY_SIG_, and QEP_TRIG_.

QState QHsm_top	(	QHsm *	me,
		QEvent 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 37 of file qhsm_top.c.

References Q_IGNORED.

Referenced by QHsm_init().

qep.h File Reference

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation