![]() |
OS
v7.3.4
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. |