qepn.h File Reference

Public QEP-nano interface. More...

#include "qassert.h"

Data Structures
struct	QEvent
	Event structure. More...
struct	QFsm
	Finite State Machine. More...
Defines
#define	QP_VERSION 0x4103
	The current QP-nano version number.
#define	Q_DIM(array_) (sizeof(array_) / sizeof(array_[0]))
#define	Q_SIG(me_) (((QFsm *)(me_))->evt.sig)
	macro to access the signal of the current event of a state machine
#define	Q_PAR(me_) (((QFsm *)(me_))->evt.par)
	macro to access the parameter of the current event of a state machine
#define	QFsm_ctor(me_, initial_) ((me_)->state = (initial_))
	State machine constructor.
#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_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_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_) (((QFsm *)me)->state = (QStateHandler)(super_), Q_RET_SUPER)
	Designates the superstate of a given state in an HSM.
#define	QHsm_ctor(me_, initial_) ((me_)->state = (initial_))
	State machine constructor.
Typedefs
typedef uint8_t	QSignal
	Scalar type describing the signal of an event.
typedef uint8_t	QParam
	type of the event parameter.
typedef uint8_t	QState
	Type returned from a state-handler function.
typedef QState(*	QStateHandler )(void *me)
	the signature of a state handler function
typedef struct QFsmTag	QHsm
	a Hierarchical State Machine.
Enumerations
enum	QReservedSignals { Q_ENTRY_SIG = 1, Q_EXIT_SIG, Q_INIT_SIG, Q_TIMEOUT_SIG, Q_USER_SIG }
	QP reserved signals. More...
Functions
char const Q_ROM *Q_ROM_VAR	QP_getVersion (void)
	get the current QP version number string
void	QFsm_init (QFsm *me)
	Initializes a FSM.
void	QHsm_init (QHsm *me)
	Initializes a HSM.
QState	QHsm_top (QHsm *me)
	The top-state.

Detailed Description

Public QEP-nano interface.

This header file must be included in all modules that use QP-nano. Typically, this header file is included indirectly through the header file qpn_port.h.

Definition in file qepn.h.

Define Documentation

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

helper macro to calculate static dimension of a 1-dim array array_

Definition at line 105 of file qepn.h.

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

typedef struct QBombTag {
    QFsm super;                                        /* derives from QFsm */
    uint8_t timeout;                    /* number of seconds till explosion */
    uint8_t defuse;                               /* the secret defuse code */
    uint8_t code;                          /* the current defuse code entry */
} QBomb;

Definition at line 265 of file qepn.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();)

typedef struct QBombTag {
    QFsm super;                                        /* derives from QFsm */
    uint8_t timeout;                    /* number of seconds till explosion */
    uint8_t defuse;                               /* the secret defuse code */
    uint8_t code;                          /* the current defuse code entry */
} QBomb;

Definition at line 279 of file qepn.h.

Referenced by QHsm_top().

#define Q_PAR ( me_ ) (((QFsm *)(me_))->evt.par)

macro to access the parameter of the current event of a state machine

See also:: QFsm QHsm Q_PARAM_SIZE

Definition at line 212 of file qepn.h.

Referenced by QK_schedule_().

#define Q_SIG ( me_ ) (((QFsm *)(me_))->evt.sig)

macro to access the signal of the current event of a state machine

See also:: QFsm QHsm

Definition at line 204 of file qepn.h.

Referenced by QFsm_init(), QHsm_init(), and QK_schedule_().

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

Designates the superstate of a given state in an HSM.

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

Definition at line 305 of file qepn.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.

/* HSM definition ----------------------------------------------------------*/
QState Pelican_carsGreenNoPed(Pelican *me) {
    switch (Q_SIG(me)) {
        case Q_ENTRY_SIG: {
            BSP_showState(me->super.prio, "carsGreenNoPed");
            return Q_HANDLED();
        }
        case PEDS_WAITING_SIG: {
            return Q_TRAN(&Pelican_carsGreenPedWait);
        }
        case Q_TIMEOUT_SIG: {
            return Q_TRAN(&Pelican_carsGreenInt);
        }
    }
    return Q_SUPER(&Pelican_carsGreen);
}
/*..........................................................................*/
QState Pelican_carsGreenPedWait(Pelican *me) {
    switch (Q_SIG(me)) {
        case Q_ENTRY_SIG: {
            BSP_showState(me->super.prio, "carsGreenPedWait");
            return Q_HANDLED();
        }
        case Q_TIMEOUT_SIG: {
            return Q_TRAN(&Pelican_carsYellow);
        }
    }
    return Q_SUPER(&Pelican_carsGreen);
}

Definition at line 292 of file qepn.h.

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

State machine constructor.

Parameters:

	me_	pointer the state machine structure derived from QHsm.
	initial_	is the pointer to the initial state of the state machine.

Note:: Must be called only ONCE before taking the initial transition with QFsm_init() and dispatching any events via QFsm_dispatch().

Definition at line 224 of file qepn.h.

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

State machine constructor.

Parameters:

	me_	pointer the state machine structure derived from QHsm.
	initial_	is the pointer to the initial state of the state machine.

Note:: Must be called only ONCE before taking the initial transition with QHsm_init() and dispatching any events via QHsm_dispatch().

Definition at line 338 of file qepn.h.

#define QP_VERSION 0x4103

The current QP-nano version number.

Returns:: version of the QP as a hex constant constant 0xXYZZ, 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 48 of file qepn.h.

Referenced by QP_getVersion().

Typedef Documentation

typedef struct QFsmTag QHsm

a Hierarchical State Machine.

QHsm represents a Hierarchical Finite State Machine (HSM). QHsm extends the capabilities of a basic FSM with state hierarchy.

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 328 of file qepn.h.

typedef uint8_t QParam

type of the event parameter.

This typedef is configurable via the preprocessor switch Q_PARAM_SIZE. The other possible values of this type are as follows:
none when (Q_PARAM_SIZE == 0);
uint8_t when (Q_PARAM_SIZE == 1);
uint16_t when (Q_PARAM_SIZE == 2); and
uint32_t when (Q_PARAM_SIZE == 4).

Definition at line 139 of file qepn.h.

Enumeration Type Documentation

enum QReservedSignals

QP 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 nested initial transitions
Q_TIMEOUT_SIG	signal used by time events
Q_USER_SIG	first signal that can be used in user applications

Definition at line 163 of file qepn.h.

Function Documentation

void QFsm_init ( QFsm * me )

Initializes a FSM.

Takes the top-most initial transition in a FSM.

Parameters:

me

is the pointer the state machine structure derived from FHsm.

Note:: Must be called only ONCE after QFsm_ctor() and before any calls to QFsm_dispatch().

Definition at line 63 of file qepn.c.

References Q_ENTRY_SIG, Q_SIG, and QFsm::state.

Referenced by QF_run().

void QHsm_init ( QHsm * me )

Initializes a HSM.

Takes the top-most initial transition in a HSM.

Parameters:

me

is the pointer the state machine structure derived from QHsm.

Note:: Must be called only ONCE after QHsm_ctor() and before any calls to QHsm_dispatch().

Definition at line 94 of file qepn.c.

References Q_ALLEGE, Q_ASSERT, Q_ENTRY_SIG, Q_INIT_SIG, Q_RET_TRAN, Q_SIG, QEP_EMPTY_SIG_, QEP_MAX_NEST_DEPTH_, and QHsm_top().

Referenced by QF_run().

QState QHsm_top ( QHsm * me )

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 89 of file qepn.c.

References Q_IGNORED.

Referenced by QHsm_init().

char const Q_ROM* Q_ROM_VAR QP_getVersion ( void )

get the current QP version number string

Returns:: version of the QP-nano 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 48 of file qepn.c.

References Q_ROM, Q_ROM_VAR, and QP_VERSION.

qepn.h File Reference

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation