QP-nano: qepn.h File Reference

Go to the source code of this file.


Data Structures
struct	QEvent
	Event structure. More...
struct	QFsm
	Finite State Machine. More...
Defines
#define	Q_DIM(array_) (sizeof(array_) / sizeof(array_[0]))
	Macro to specify compiler-specific directive for placing a constant object in ROM.
#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	QFsm_dispatch (QFsm *me)
	Dispatches an event to a FSM.
void	QHsm_init (QHsm *me)
	Initializes a HSM.
void	QHsm_dispatch (QHsm *me)
	Dispatches an event to a HSM.
QState	QHsm_top (QHsm *me)
	The top-state.

Detailed Description

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.

Define Documentation

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

Macro to specify compiler-specific directive for placing a constant object in ROM.

Many compilers for 8-bit Harvard-architecture MCUs provide non-stanard extensions to support placement of objects in different memories. In order to conserve the precious RAM, QP-nano uses the Q_ROM macro for all constant objects that can be allocated in ROM.

To override the following empty definition, you need to define the Q_ROM macro in the qpn_port.h header file. Some examples of valid Q_ROM macro definitions are: __code (IAR 8051 compiler), code (Keil 8051 compiler), PROGMEM (gcc for AVR), __flash (IAR for AVR). Macro to specify compiler-specific directive for accessing a constant object in ROM.

Many compilers for 8-bit MCUs provide different size pointers for accessing objects in various memories. Constant objects allocated in ROM (see Q_ROM macro) often mandate the use of specific-size pointers (e.g., far pointers) to get access to ROM objects. The macro Q_ROM_VAR specifies the kind of the pointer to be used to access the ROM objects.

To override the following empty definition, you need to define the Q_ROM_VAR macro in the qpn_port.h header file. An example of valid Q_ROM_VAR macro definition is: __far (Freescale HC(S)08 compiler). Macro to specify compiler-specific directive for generating reentrant function.

Some compilers for 8-bit MCUs provide, most notably the Keil C51 compiler for 8051, don't generate ANSI-C compliant reentrant functions by default, due to the limited CPU architecture. These compilers allow dedicating specific functions to be reentrant with a special extended keyword (such as "reentrant" for Keil C51). The macro Q_REENTRANT is defined to nothing by default, to work with ANSI-C compliant compilers, but can be defined to "reentrant" to work with Keil C51 and perhaps other embedded compilers. helper macro to calculate static dimension of a 1-dim array array_

Definition at line 96 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 253 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 267 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 201 of file qepn.h.

Referenced by QActive_post(), QActive_postISR(), and 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 193 of file qepn.h.

Referenced by QActive_post(), QActive_postISR(), QFsm_dispatch(), QFsm_init(), QHsm_dispatch(), 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 293 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 280 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 213 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 326 of file qepn.h.

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 316 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 130 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 152 of file qepn.h.

Function Documentation

void QFsm_dispatch ( QFsm * me )

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.

Note:: Must be called after QFsm_init().

Definition at line 65 of file qepn.c.

References Q_ENTRY_SIG, Q_EXIT_SIG, Q_RET_TRAN, Q_SIG, and QFsm::state.

Referenced by QK_schedule_().

void QFsm_init ( QFsm * me )

Initializes a FSM.

Takes the top-most initial transition in a FSM.

Parameters:

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

References Q_ENTRY_SIG, Q_SIG, and QFsm::state.

Referenced by QF_run().

void QHsm_dispatch ( QHsm * me )

Dispatches an event to a HSM.

Processes one event at a time in Run-to-Completion fashion. me is the pointer the state machine structure derived from QHsm.

Note:: Must be called repetitively for each event after QHsm_init().

Definition at line 121 of file qepn.c.

References Q_ASSERT, Q_ENTRY_SIG, Q_EXIT_SIG, Q_INIT_SIG, Q_RET_HANDLED, Q_RET_IGNORED, Q_RET_SUPER, Q_RET_TRAN, Q_SIG, QEP_EMPTY_SIG_, and QEP_MAX_NEST_DEPTH_.

Referenced by QK_schedule_().

void QHsm_init ( QHsm * me )

Initializes a HSM.

Takes the top-most initial transition in a HSM.

Parameters:

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 86 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 81 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 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, and Q_ROM_VAR.

qepn.h File Reference

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation