sys_fsm.h 9.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286
  1. /**
  2. * Copyright (c) 2016 - 2020 Nordic Semiconductor ASA and Luxoft Global Operations Gmbh.
  3. *
  4. * All Rights Reserved.
  5. *
  6. * Redistribution and use in source and binary forms, with or without modification,
  7. * are permitted provided that the following conditions are met:
  8. *
  9. *
  10. * 1. Redistributions of source code must retain the above copyright notice, this
  11. * list of conditions and the following disclaimer.
  12. *
  13. * 2. Redistributions in binary form, except as embedded into a Nordic
  14. * Semiconductor ASA integrated circuit in a product or a software update for
  15. * such product, must reproduce the above copyright notice, this list of
  16. * conditions and the following disclaimer in the documentation and/or other
  17. * materials provided with the distribution.
  18. *
  19. * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
  20. * contributors may be used to endorse or promote products derived from this
  21. * software without specific prior written permission.
  22. *
  23. * 4. This software, with or without modification, must only be used with a
  24. * Nordic Semiconductor ASA integrated circuit.
  25. *
  26. * 5. Any software provided in binary form under this license must not be reverse
  27. * engineered, decompiled, modified and/or disassembled.
  28. *
  29. *
  30. * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
  31. * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  32. * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
  33. * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
  34. * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  35. * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  36. * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  37. * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  38. * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  39. * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  40. *
  41. */
  42. #ifndef SYS_FSM_H_INCLUDED
  43. #define SYS_FSM_H_INCLUDED
  44. #include <stdint.h>
  45. #include <stdbool.h>
  46. /** @file
  47. * This file contains declarations of the Finite State Machine (FSM) primitives and necessary types.
  48. *
  49. * @defgroup sys_fsm Finite State Machine API
  50. * @ingroup sys_15_4
  51. * @{
  52. * @brief Module to declare Finite State Machine API
  53. * @details The FSM module implements the Finite State Machine abstraction. The user is intended to implement a transition
  54. * table of states with guards and actions in order to represent some event-driven subject. When a table is
  55. * implemented, call sys_fsm_init() to initialize the FSM. After that, the only routine to
  56. * work with FSM is sys_fsm_event_post().
  57. */
  58. /**@brief Fixed-size type for FSM state ID.
  59. */
  60. typedef uint8_t sys_fsm_state_id_t;
  61. /**@brief Fixed-size type for FSM event ID.
  62. */
  63. typedef uint8_t sys_fsm_event_id_t;
  64. /**@brief Fixed-size type for FSM guard condition ID.
  65. */
  66. typedef uint8_t sys_fsm_guard_id_t;
  67. /**@brief Fixed-size type for FSM action ID.
  68. */
  69. typedef uint8_t sys_fsm_action_id_t;
  70. /**@brief FSM transition description (item of FSM transition table).
  71. *
  72. * @details When an event with given event_id occurs, the guard condition with guard_id
  73. * is checked, and if it returns true, the action with action_id is performed,
  74. * and state machine is switched to the state with new_state_id.
  75. */
  76. typedef struct
  77. {
  78. sys_fsm_event_id_t event_id; /**< FSM event ID. */
  79. sys_fsm_guard_id_t guard_id; /**< FSM guard ID. */
  80. sys_fsm_action_id_t action_id; /**< FSM action ID. */
  81. sys_fsm_state_id_t new_state_id; /**< New state ID. */
  82. #if defined(CONFIG_FSM_DEBUG)
  83. const char * debug_string;
  84. #endif
  85. } sys_fsm_transition_t;
  86. /**@brief FSM transition declaration (item of FSM transition table).
  87. */
  88. #if defined(CONFIG_FSM_DEBUG)
  89. # define SYS_FSM_TRANSITION(event_id, guard_id, action_id, new_state_id) \
  90. {(event_id), (guard_id), (action_id), (new_state_id), \
  91. "(" #event_id ", " #guard_id ", " #action_id " -> " #new_state_id ")"}
  92. #else
  93. # define SYS_FSM_TRANSITION(event_id, guard_id, action_id, new_state_id) \
  94. {(event_id), (guard_id), (action_id), (new_state_id)}
  95. #endif
  96. /**@brief FSM state declaration.
  97. *
  98. * @details The state is an aggregator item of the FSM transition table, aggregating
  99. * the transitions, declared immediately after this state declaration.
  100. * All transition declaration items, following the state declaration item,
  101. * will be aggregated in this state, until the next state declaration item,
  102. * or the "end of table" item.
  103. */
  104. #define SYS_FSM_STATE(state_id) \
  105. {(state_id) | SYS_FSM_STATE_FLAG, 0, 0, 0}
  106. /**@brief Empty guard condition ID.
  107. *
  108. * @details Special value of the guard_id field. If it is used in transition declaration,
  109. * guard check will be omitted.
  110. */
  111. #define SYS_FSM_NO_GUARD 0xFF
  112. /**@brief Empty guard condition ID (useful synonym).
  113. *
  114. * @details Special value of the guard_id field. If it is used in transition declaration,
  115. * guard check will be omitted.
  116. */
  117. #define SYS_FSM_OTHERWISE 0xFF
  118. /**@brief Empty guard condition ID (useful synonym).
  119. *
  120. * @details Special value of the guard_id field. If it is used in transition declaration,
  121. * guard check will be omitted.
  122. */
  123. #define SYS_FSM_ALWAYS 0xFF
  124. /**@brief Empty action ID.
  125. *
  126. * @details Special value of the action_id field. If it is used in transition declaration,
  127. * no action will be performed during the transition.
  128. */
  129. #define SYS_FSM_NO_ACTION 0xFF
  130. /**@brief Same state ID.
  131. *
  132. * @details Special value of the next_state_id field. If it is used in transition
  133. * declaration, the current state will not be changed.
  134. */
  135. #define SYS_FSM_SAME_STATE 0xFF
  136. /**@brief Any state ID.
  137. *
  138. * @details Special value of the event_id field. If it is used in transition
  139. * declaration table, then the transitions listed in this state will be applied
  140. * in case they have not been listed in the transition table for the
  141. * current FSM state.
  142. * Only one SYS_FSM_STATE(SYS_FSM_ANY_STATE) can be present in the transition table.
  143. */
  144. #define SYS_FSM_ANY_STATE 0xFF
  145. /**@brief State declaration flag.
  146. *
  147. * @details Special flag of the event_id field. This flag is used to distinguish
  148. * between state declaration and transition declaration.
  149. */
  150. #define SYS_FSM_STATE_FLAG 0x80
  151. /**@brief Prototype of a user-defined FSM guard condition function.
  152. *
  153. * @details You must implement a single FSM guard condition function which will
  154. * use an ID of the needed guard check as a parameter.
  155. *
  156. * @param[in] guard_id Guard condition ID to be checked.
  157. * @param[in] p_data Additional FSM specific data.
  158. *
  159. * @retval true Transition is allowed, false otherwise.
  160. */
  161. typedef bool (* sys_fsm_guard_t)(sys_fsm_guard_id_t guard_id, void * p_data);
  162. /**@brief Prototype of a user-defined FSM action function.
  163. *
  164. * @details You must implement a single FSM action function which will
  165. * use an ID of the needed action as a parameter.
  166. *
  167. * @param[in] action_id Action ID to be performed.
  168. * @param[in] p_data Additional FSM specific data.
  169. */
  170. typedef void (* sys_fsm_action_t)(sys_fsm_action_id_t action_id, void * p_data);
  171. /**@brief Constant FSM descriptor which can reside in read-only memory.
  172. */
  173. typedef struct
  174. {
  175. #if defined(CONFIG_FSM_DEBUG)
  176. const char * debug_fsm_name;
  177. #endif
  178. /** Pointer to the transition table.
  179. */
  180. const sys_fsm_transition_t * transition_table;
  181. /** Number of transitions in the transition table.
  182. */
  183. uint8_t transitions_amount;
  184. /** Initial state ID.
  185. */
  186. sys_fsm_state_id_t initial_state;
  187. /** Pointer to the guard condition function.
  188. */
  189. sys_fsm_guard_t guard;
  190. /** Pointer to the action function.
  191. */
  192. sys_fsm_action_t action;
  193. } sys_fsm_const_descriptor_t;
  194. /**@brief FSM dynamic descriptor, holding the current state of the FSM.
  195. */
  196. typedef struct
  197. {
  198. /** Pointer to the constant FSM descriptor which can reside in read-only memory.
  199. */
  200. const sys_fsm_const_descriptor_t * fsm_const_desc;
  201. /** Index of the "any state transitions" block.
  202. */
  203. uint8_t any_state_transitions_index;
  204. /** Current state ID.
  205. */
  206. volatile sys_fsm_state_id_t current_state;
  207. /** Recursion protection.
  208. */
  209. volatile uint8_t recursion_protection;
  210. } sys_fsm_t;
  211. #if defined(CONFIG_FSM_DEBUG)
  212. #define FSM_DEBUG_NAME(name_string) .debug_fsm_name = name_string,
  213. #else
  214. #define FSM_DEBUG_NAME(name_string)
  215. #endif
  216. /**@brief Function for initializing a specific FSM.
  217. *
  218. * @param[in] p_fsm Pointer to FSM descriptor to initialize.
  219. * @param[in] p_fsm_const Pointer to constant FSM descriptor with transition table, etc.
  220. */
  221. void sys_fsm_init(sys_fsm_t * p_fsm, const sys_fsm_const_descriptor_t * p_fsm_const);
  222. /**@brief Function for posting an event to FSM.
  223. *
  224. * @details This function causes FSM transition from the current state to the new state,
  225. * according to the transition table of this FSM.
  226. * The corresponding guard check and action is performed.
  227. *
  228. * @param[in] p_fsm Pointer to FSM descriptor.
  229. * @param[in] event_id Event ID to post.
  230. * @param[in] p_data Pointer to the FSM-specific data.
  231. */
  232. void sys_fsm_event_post(sys_fsm_t * p_fsm, sys_fsm_event_id_t event_id, void * p_data);
  233. /** @} */
  234. #endif // SYS_FSM_H_INCLUDED