QP-nano
Data Structures | Defines | Typedefs | Enumerations | Functions
qepn.h File Reference

Public QEP-nano interface. More...

#include "qassert.h"

Go to the source code of this file.

Data Structures

struct  QEvent
 Event structure. More...
struct  QFsm
 Finite State Machine. More...

Defines

#define QP_VERSION   0x4300U
 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_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

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

Definition at line 66 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 84 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 204 of file qepn.h.

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

#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   0x4300U

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

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

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

Referenced by QK_sched_().

void QFsm_init ( QFsm me)

Initializes a FSM.

Takes the top-most initial transition in a FSM.

Parameters:
meis 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.

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 131 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_sched_().

void QHsm_init ( QHsm me)

Initializes a HSM.

Takes the top-most initial transition in a HSM.

Parameters:
meis 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().

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.