Public QEP-nano interface. More...

#include "qassert.h"

Data Structures
struct	QEvt
	Event structure. More...
struct	QFsm
	Finite State Machine. More...
Defines
#define	QP_VERSION 0x4504U
	The current QP-nano version number.
#define	Q_ROM
	Macro to specify compiler-specific directive for placing a constant object in ROM.
#define	Q_ROM_VAR
	Macro to specify compiler-specific directive for accessing a constant object in ROM.
#define	Q_REENTRANT
	Macro to specify compiler-specific directive for generating reentrant function.
#define	Q_DIM(array_) (sizeof(array_) / sizeof(array_[0]))
#define	Q_UINT2PTR_CAST(type_, uint_) ((type_ *)(uint_))
	Perform cast from unsigned integer uint_ to pointer of type type_.
#define	Q_STATE_CAST(handler_) ((QStateHandler)(handler_))
	Perform cast to QStateHandler.
#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_)
	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)
	Macro to specify the return of 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)
	Macro to specify the return of a state-handler function when it ignores (does not handle in any way) 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.
#define	QHsm_ctor(me_, initial_)
	State machine constructor.
#define	QHsm_state(me_) (Q_STATE_CAST((me_)->state))
	Obtain the current active state from a HSM (read only).
Typedefs
typedef char	char_t
	typedef for character strings.
typedef float	float32_t
typedef double	float64_t
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.
typedef QEvt	QEvent
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_t const Q_ROM *Q_ROM_VAR	QP_getVersion (void)
	get the current QP version number string
void	QFsm_init (QFsm *const me)
	Initializes a FSM.
void	QFsm_dispatch (QFsm *const me)
	Dispatches an event to a FSM.
void	QHsm_init (QHsm *const me)
	Initializes a HSM.
void	QHsm_dispatch (QHsm *const me)
	Dispatches an event to a HSM.
QState	QHsm_top (void const *const 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 112 of file qepn.h.

#define Q_HANDLED ( ) (Q_RET_HANDLED)

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

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

#define Q_IGNORED ( ) (Q_RET_IGNORED)

Macro to specify the return of a state-handler function when it ignores (does not handle in any way) the event.

Note:: Can be used in non-hierarchical state machines.

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

Referenced by QK_sched_().

#define Q_REENTRANT

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.

Definition at line 107 of file qepn.h.

#define Q_ROM

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

Many compilers for 8-bit Harvard-architecture MCUs provide non-standard 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).

Definition at line 73 of file qepn.h.

#define Q_ROM_VAR

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

Definition at line 91 of file qepn.h.

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

Referenced by QFsm_dispatch(), QFsm_init(), QHsm_dispatch(), QHsm_init(), and QK_sched_().

#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 218 of file qepn.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.

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

/* 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 333 of file qepn.h.

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

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

This macro encapsulates the cast to (type_ *), which QP ports or application might use to access embedded hardware registers. Such uses can trigger PC-Lint "Note 923: cast from int to pointer" and this macro helps to encapsulate this deviation.

Definition at line 138 of file qepn.h.

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

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

#define QFsm_ctor	(	me_,
		initial_
	)

Value:

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

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

#define QHsm_ctor	(	me_,
		initial_
	)

Value:

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

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

#define QP_VERSION 0x4504U

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

Referenced by QP_getVersion().

Typedef Documentation

typedef char char_t

typedef for character strings.

This typedef specifies character type for exclusive use in character strings. Use of this type, rather than plain 'char', is in compliance with the MISRA-C 2004 Rules 6.1(req), 6.3(adv).

Definition at line 122 of file qepn.h.

typedef float float32_t

typedef for 32-bit IEEE 754 floating point numbers

Definition at line 125 of file qepn.h.

typedef double float64_t

typedef for 64-bit IEEE 754 floating point numbers

Definition at line 128 of file qepn.h.

typedef QEvt QEvent

typedef for backwards compatibity

Definition at line 441 of file qepn.h.

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 381 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 172 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 196 of file qepn.h.

Function Documentation

void QFsm_dispatch ( QFsm *const 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 82 of file qepn.c.

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

Referenced by QK_sched_().

void QFsm_init ( QFsm *const 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 67 of file qepn.c.

References Q_ALLEGE, Q_ENTRY_SIG, Q_REQUIRE, Q_RET_TRAN, Q_SIG, Q_STATE_CAST, QFsm::state, and QFsm::temp.

void QHsm_dispatch ( QHsm *const 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 144 of file qepn.c.

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

Referenced by QK_sched_().

void QHsm_init ( QHsm *const 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 103 of file qepn.c.

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

QState QHsm_top ( void const *const 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 98 of file qepn.c.

References Q_IGNORED.

Referenced by QHsm_init().

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

References Q_ROM, Q_ROM_VAR, and QP_VERSION.

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation