OS
v7.3.3
Documentation
|
API interface of the Finite State Machines (FSM) extension. More...
Data Structures | |
struct | qSM_Signal_t |
The type to be used as a container variable for a signal. More... | |
struct | qSM_Handler_t |
The callback argument to handle the state-machine dynamics and provide execution information. Some members can be written to perform state-transitions. More... | |
struct | qSM_TimeoutStateDefinition_t |
This structure should be used to define an item for a timeout-specification table. More... | |
struct | qSM_State_t |
A state object. More... | |
struct | qSM_TimeoutSpec_t |
A FSM Timeout-specification object. More... | |
struct | qSM_t |
A FSM(Finite State Machine) object. More... | |
struct | qSM_Transition_t |
This structure should be used to define an item for a state transition table. More... | |
Macros | |
#define | QSM_STATE_TOP |
This macro can be used to reference the top state when using the qStateMachine_StateSubscribe() API. | |
#define | QSM_SIGNAL_START |
Built-in signal that can be used to set a nested initial-transition (aka default transition) by writing the qSM_Handler_t::StartState member. | |
#define | QSM_SIGNAL_EXIT |
Built-in signal to indicate if the current state has just exit to another state. | |
#define | QSM_SIGNAL_ENTRY |
Built-in signal to indicate if the current state has just entered from another state. | |
#define | QSM_SIGNAL_NONE |
Built-in signal to indicate that there is not signal available. | |
#define | QSM_SIGNAL_TIMEOUT(index) |
Built-in signal to indicate that a timeout expiration event occurs. | |
#define | QSM_TSOPT_INDEX(index) |
Timeout-specification option. Should be used to specify the timeout index. | |
#define | QSM_TSOPT_SET_ENTRY |
This timeout-specification option its used to specify that the engine should set the timeout when the specified state its entering. | |
#define | QSM_TSOPT_RST_ENTRY |
This timeout-specification option its used to specify that the engine should reset the timeout when the specified state its entering. | |
#define | QSM_TSOPT_SET_EXIT |
This timeout-specification option its used to specify that the engine should set the timeout when the specified state its exiting*. | |
#define | QSM_TSOPT_RST_EXIT |
This timeout-specification option its used to specify that the engine should reset the timeout when the specified state its exiting*. | |
#define | QSM_TSOPT_KEEP_IF_SET |
This timeout-specification option its used to specify that the engine should set the timeout only if it is in reset state. | |
#define | QSM_TSOPT_PERIODIC |
This timeout-specification option its used setup the timeout in periodic mode. | |
#define | QSM_SIGNAL_RANGE_MIN |
Minimum value that can be used for an user-defined signal. | |
#define | QSM_SIGNAL_RANGE_MAX |
Maximum value that can be used for an user-defined signal. | |
#define | QSM_SIGNAL_TM_MAX |
#define | QSM_SIGNAL_TM_MIN |
#define | QSM_SIGNAL_USER |
The start value for an user-defined signal. | |
Typedefs | |
typedef qUINT32_t | qSM_SigId_t |
The type for signal ID. | |
typedef qSM_Status_t(* | qSM_StateCallback_t) (qSM_Handler_t h) |
Pointer to a function that represents a state callback. | |
typedef void(* | qSM_SurroundingCallback_t) (qSM_Handler_t h) |
Pointer to a function that represents a surrounding callback. | |
typedef qBool_t(* | qSM_SignalAction_t) (qSM_Handler_t h) |
Pointer to a function that represents a signal guard/action. | |
typedef qUINT32_t | qSM_TimeoutSpecOptions_t |
A typedef to hold the timeout specification options. | |
Enumerations | |
enum | qSM_Status_t { qSM_STATUS_BEFORE_ANY , qSM_STATUS_NULL , qSM_STATUS_EXIT_FAILURE , qSM_STATUS_EXIT_SUCCESS , qSM_STATUS_SIGNAL_HANDLED } |
This enumeration defines the built-in state-execution status values that can be used as return value in a state callback. More... | |
enum | qSM_TransitionHistoryMode_t { qSM_TRANSITION_NO_HISTORY , qSM_TRANSITION_SHALLOW_HISTORY , qSM_TRANSITION_DEEP_HISTORY } |
This enumeration defines the possible modes to perform a transition to history. More... | |
enum | qSM_Attribute_t { qSM_ATTRIB_STATE_TOP , qSM_ATTRIB_STATE_CURRENT , qSM_ATTRIB_SIGNAL_QUEUE , qSM_ATTRIB_TIMESPEC , qSM_ATTRIB_TRANSITION_TABLE , qSM_ATTRIB_DATA , qSM_ATTRIB_COMPOSITE_INITSTATE , qSM_ATTRIB_COMPOSITE_LASTSTATE , qSM_ATTRIB_COMPOSITE_PARENT } |
This enumeration defines the attributes that can be acquired for a FSM or a state. More... | |
Functions | |
qBool_t | qStateMachine_Run (qSM_t *const m, qSM_Signal_t sig) |
Execute the Finite State Machine (FSM). | |
qBool_t | qStateMachine_Setup (qSM_t *const m, qSM_StateCallback_t topFcn, qSM_State_t *const init, qSM_SurroundingCallback_t sFcn, void *pData) |
Initializes a Finite State Machine (FSM). | |
qBool_t | qStateMachine_StateSubscribe (qSM_t *const m, qSM_State_t *const s, qSM_State_t *const parent, qSM_StateCallback_t sFcn, qSM_State_t *const init, void *pData) |
This function subscribes the FSM instance to a specific state with an associated callback function. | |
qBool_t | qStateMachine_Set_StateTransitions (qSM_State_t *const s, qSM_Transition_t *const table, const size_t n) |
Installs a table with the outgoing transitions for the supplied state. | |
qBool_t | qStateMachine_InstallSignalQueue (qSM_t *const m, qQueue_t *q) |
Install a signal queue to the provided Finite State Machine (FSM). | |
qBool_t | qStateMachine_SendSignal (qSM_t *const m, qSM_SigId_t sig, void *sData, const qBool_t isUrgent) |
Sends a signal to a specific state machine or to all its subscribers (if available). | |
qBool_t | qStateMachine_InstallTimeoutSpec (qSM_t *const m, qSM_TimeoutSpec_t *const ts) |
Install the Timeout-specification object to target FSM to allow timed signals within states ( See the QSM_SIGNAL_TIMEOUT signal ). | |
qBool_t | qStateMachine_Set_StateTimeouts (qSM_State_t *const s, qSM_TimeoutStateDefinition_t *tdef, const size_t n) |
Setup fixed timeouts for the specified state using a lookup-table. | |
qBool_t | qStateMachine_TimeoutSet (qSM_t *const m, const qIndex_t xTimeout, const qTime_t t) |
Set the time for the selected built-in timeout inside the target FSM. | |
qBool_t | qStateMachine_TimeoutStop (qSM_t *const m, const qIndex_t xTimeout) |
Stop the time count for the selected built-in timeout. | |
void * | qStateMachine_Get_Machine (qSM_t *const m, const qSM_Attribute_t a) |
Get attributes from the provided Finite State Machine object. | |
void * | qStateMachine_Get_State (const qSM_State_t *const s, const qSM_Attribute_t a) |
Get attributes from the provided state object. | |
qBool_t | qStateMachine_Set_StateCallback (qSM_State_t *const state, qSM_StateCallback_t sFcn) |
Set/Change the state callback in run-time. | |
qBool_t | qStateMachine_Set_MachineSurrounding (qSM_t *const m, qSM_SurroundingCallback_t sFcn) |
Set/Change the FSM surrounding callback in run-time. | |
qBool_t | qStateMachine_SubscribeToSignal (qSM_t *const m, qSM_SigId_t s) |
Subscribe state machine to a particular signal. | |
qBool_t | qStateMachine_UnsubscribeFromSignal (const qSM_t *const m, qSM_SigId_t s) |
Unsubscribe state machine from a particular signal. | |
API interface of the Finite State Machines (FSM) extension.
#define QSM_SIGNAL_ENTRY |
Built-in signal to indicate if the current state has just entered from another state.
#define QSM_SIGNAL_EXIT |
Built-in signal to indicate if the current state has just exit to another state.
#define QSM_SIGNAL_START |
Built-in signal that can be used to set a nested initial-transition (aka default transition) by writing the qSM_Handler_t::StartState member.
#define QSM_SIGNAL_TIMEOUT | ( | index | ) |
Built-in signal to indicate that a timeout expiration event occurs.
index | The index of the timeout (0, 1, 2... ( Q_FSM_MAX_TIMEOUTS-1 ) ) |
#define QSM_TSOPT_INDEX | ( | index | ) |
Timeout-specification option. Should be used to specify the timeout index.
#define QSM_TSOPT_KEEP_IF_SET |
This timeout-specification option its used to specify that the engine should set the timeout only if it is in reset state.
#define QSM_TSOPT_PERIODIC |
This timeout-specification option its used setup the timeout in periodic mode.
#define QSM_TSOPT_RST_ENTRY |
This timeout-specification option its used to specify that the engine should reset the timeout when the specified state its entering.
#define QSM_TSOPT_RST_EXIT |
This timeout-specification option its used to specify that the engine should reset the timeout when the specified state its exiting*.
#define QSM_TSOPT_SET_ENTRY |
This timeout-specification option its used to specify that the engine should set the timeout when the specified state its entering.
#define QSM_TSOPT_SET_EXIT |
This timeout-specification option its used to specify that the engine should set the timeout when the specified state its exiting*.
typedef qBool_t(* qSM_SignalAction_t) (qSM_Handler_t h) |
Pointer to a function that represents a signal guard/action.
h | The object that handles the state machine |
typedef qSM_Status_t(* qSM_StateCallback_t) (qSM_Handler_t h) |
Pointer to a function that represents a state callback.
h | The object that handles the state machine |
typedef void(* qSM_SurroundingCallback_t) (qSM_Handler_t h) |
Pointer to a function that represents a surrounding callback.
h | The object that handles the state machine |
enum qSM_Attribute_t |
This enumeration defines the attributes that can be acquired for a FSM or a state.
Enumerator | |
---|---|
qSM_ATTRIB_STATE_TOP | Only for qStateMachine_Get_Machine() : Get a pointer to the top state |
qSM_ATTRIB_STATE_CURRENT | Only for qStateMachine_Get_Machine() : Get a pointer to the current running state |
qSM_ATTRIB_SIGNAL_QUEUE | Only for qStateMachine_Get_Machine() : Get a pointer to the signal-queue object if installed |
qSM_ATTRIB_TIMESPEC | Only for qStateMachine_Get_Machine() : Get a pointer to the timeout specification object if installed |
qSM_ATTRIB_TRANSITION_TABLE | Only for qStateMachine_Get_State() : Get a pointer to the transition table if available |
qSM_ATTRIB_DATA | Get the user data ( storage-pointer ) |
qSM_ATTRIB_COMPOSITE_INITSTATE | Only for qStateMachine_Get_State() : Get the initial default or initial state, if input is composite |
qSM_ATTRIB_COMPOSITE_LASTSTATE | Only for qStateMachine_Get_State() : Get the last state, if input is composite |
qSM_ATTRIB_COMPOSITE_PARENT | Only for qStateMachine_Get_State() : Get the parent state, if input is a child |
enum qSM_Status_t |
This enumeration defines the built-in state-execution status values that can be used as return value in a state callback.
This enumeration defines the possible modes to perform a transition to history.
void * qStateMachine_Get_Machine | ( | qSM_t *const | m, |
const qSM_Attribute_t | a ) |
Get attributes from the provided Finite State Machine object.
[in] | m | A pointer to the FSM object. |
[in] | a | The requested attribute |
NULL
. void * qStateMachine_Get_State | ( | const qSM_State_t *const | s, |
const qSM_Attribute_t | a ) |
Get attributes from the provided state object.
[in] | s | A pointer to the state object. |
[in] | a | The requested attribute |
NULL
. Install a signal queue to the provided Finite State Machine (FSM).
[in] | m | A pointer to the FSM object. |
[in] | q | A pointer to the queue object. |
qBool_t qStateMachine_InstallTimeoutSpec | ( | qSM_t *const | m, |
qSM_TimeoutSpec_t *const | ts ) |
Install the Timeout-specification object to target FSM to allow timed signals within states ( See the QSM_SIGNAL_TIMEOUT signal ).
Q_FSM_MAX_TIMEOUTS
configuration macro inside qconfig.h
[in] | m | A pointer to the FSM object. |
[in] | ts | A pointer to the timeout specification object. |
qBool_t qStateMachine_Run | ( | qSM_t *const | m, |
qSM_Signal_t | sig ) |
Execute the Finite State Machine (FSM).
[in] | m | A pointer to the FSM object. |
[in] | sig | User-defined signal (this value will be ignored if the installed queue has items available) |
qBool_t qStateMachine_SendSignal | ( | qSM_t *const | m, |
qSM_SigId_t | sig, | ||
void * | sData, | ||
const qBool_t | isUrgent ) |
Sends a signal to a specific state machine or to all its subscribers (if available).
qconfig.h
[in] | m | A pointer to the FSM object to send the signal to a specific recipient. Pass NULL to send the signal to all subscribed state-machines. |
[in] | sig | The user-defined signal. |
[in] | sData | The data associated to the signal. |
[in] | isUrgent | If qTrue, the signal will be sent to the front of the queue. (only if the there is a signal-queue available) |
qBool_t qStateMachine_Set_MachineSurrounding | ( | qSM_t *const | m, |
qSM_SurroundingCallback_t | sFcn ) |
qBool_t qStateMachine_Set_StateCallback | ( | qSM_State_t *const | state, |
qSM_StateCallback_t | sFcn ) |
qBool_t qStateMachine_Set_StateTimeouts | ( | qSM_State_t *const | s, |
qSM_TimeoutStateDefinition_t * | tdef, | ||
const size_t | n ) |
Setup fixed timeouts for the specified state using a lookup-table.
[in] | s | A pointer to the state object. |
[in] | tdef | The lookup table matching the requested timeout values with their respective options. { [Timeout value], [Options(Combined with a bitwise OR)] } |
[in] | n | The number of elements inside tdef. |
qBool_t qStateMachine_Set_StateTransitions | ( | qSM_State_t *const | s, |
qSM_Transition_t *const | table, | ||
const size_t | n ) |
Installs a table with the outgoing transitions for the supplied state.
[in] | s | A pointer to the state object. |
[in] | table | An array of entries of type qSM_Transition_t with the outgoing transitions. Each entry relates signals, actions and the target state using the following layout: { [Signal], [Action/Guard], [Target state], [History Mode] } |
[in] | n | The number of elements inside table. |
qBool_t qStateMachine_Setup | ( | qSM_t *const | m, |
qSM_StateCallback_t | topFcn, | ||
qSM_State_t *const | init, | ||
qSM_SurroundingCallback_t | sFcn, | ||
void * | pData ) |
Initializes a Finite State Machine (FSM).
[in] | m | A pointer to the FSM object. |
[in] | topFcn | The callback for the "Top" state. |
[in] | init | The first state to be executed (init-state or default transition). |
[in] | sFcn | The surrounding callback. To ignore pass NULL . |
[in] | pData | Represents the FSM arguments. User storage pointer. To ignore pass NULL . |
qBool_t qStateMachine_StateSubscribe | ( | qSM_t *const | m, |
qSM_State_t *const | s, | ||
qSM_State_t *const | parent, | ||
qSM_StateCallback_t | sFcn, | ||
qSM_State_t *const | init, | ||
void * | pData ) |
This function subscribes the FSM instance to a specific state with an associated callback function.
[in] | m | A pointer to the FSM object. |
[in] | s | A pointer to the state object. |
[in] | parent | A pointer to the parent state (Use QSM_STATE_TOP) if the parent is the top state. |
[in] | sFcn | The handler function associated to the state. |
Prototype:
[in] | init | The first child-state to be executed if the subscribed state its a parent in an hierarchical pattern. (default transition). To ignore pass NULL as argument. |
[in] | pData | State data. Storage pointer. To ignore pass NULL . |
qBool_t qStateMachine_SubscribeToSignal | ( | qSM_t *const | m, |
qSM_SigId_t | s ) |
Subscribe state machine to a particular signal.
[in] | m | A pointer to the subscriber FSM. |
[in] | s | Signal ID to which the subscriber FSM wants to subscribe. |
Set the time for the selected built-in timeout inside the target FSM.
[in] | m | A pointer to the FSM object. |
[in] | xTimeout | The index of the requested timeout (0, 1, 2 ... (Q_FSM_MAX_TIMEOUTS-1 ) ) |
[in] | t | The specified time usually given in seconds. |
Stop the time count for the selected built-in timeout.
[in] | m | A pointer to the FSM object. |
[in] | xTimeout | The index of the timeout (0, 1, 2 ... (Q_FSM_MAX_TIMEOUTS-1 ) ) |
qBool_t qStateMachine_UnsubscribeFromSignal | ( | const qSM_t *const | m, |
qSM_SigId_t | s ) |
Unsubscribe state machine from a particular signal.
[in] | m | A pointer to the subscriber FSM. |
[in] | s | Signal ID to which the subscriber FSM wants to unsubscribe. |