fsl_notifier.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237
  1. /*
  2. * Copyright (c) 2015, Freescale Semiconductor, Inc.
  3. * Copyright 2016-2017 NXP
  4. * All rights reserved.
  5. *
  6. * SPDX-License-Identifier: BSD-3-Clause
  7. */
  8. #ifndef _FSL_NOTIFIER_H_
  9. #define _FSL_NOTIFIER_H_
  10. #include "fsl_common.h"
  11. /*!
  12. * @addtogroup notifier
  13. * @{
  14. */
  15. /*******************************************************************************
  16. * Definitions
  17. ******************************************************************************/
  18. /*!
  19. * @brief Notifier error codes.
  20. *
  21. * Used as return value of Notifier functions.
  22. */
  23. enum _notifier_status
  24. {
  25. kStatus_NOTIFIER_ErrorNotificationBefore =
  26. MAKE_STATUS(kStatusGroup_NOTIFIER, 0), /*!< An error occurs during send "BEFORE" notification. */
  27. kStatus_NOTIFIER_ErrorNotificationAfter =
  28. MAKE_STATUS(kStatusGroup_NOTIFIER, 1), /*!< An error occurs during send "AFTER" notification. */
  29. };
  30. /*!
  31. * @brief Notifier policies.
  32. *
  33. * Defines whether the user function execution is forced or not.
  34. * For kNOTIFIER_PolicyForcible, the user function is executed regardless of the callback results,
  35. * while kNOTIFIER_PolicyAgreement policy is used to exit NOTIFIER_SwitchConfig()
  36. * when any of the callbacks returns error code.
  37. * See also NOTIFIER_SwitchConfig() description.
  38. */
  39. typedef enum _notifier_policy
  40. {
  41. kNOTIFIER_PolicyAgreement, /*!< NOTIFIER_SwitchConfig() method is exited when any of the callbacks returns error
  42. code. */
  43. kNOTIFIER_PolicyForcible, /*!< The user function is executed regardless of the results. */
  44. } notifier_policy_t;
  45. /*! @brief Notification type. Used to notify registered callbacks */
  46. typedef enum _notifier_notification_type
  47. {
  48. kNOTIFIER_NotifyRecover = 0x00U, /*!< Notify IP to recover to previous work state. */
  49. kNOTIFIER_NotifyBefore = 0x01U, /*!< Notify IP that configuration setting is going to change. */
  50. kNOTIFIER_NotifyAfter = 0x02U, /*!< Notify IP that configuration setting has been changed. */
  51. } notifier_notification_type_t;
  52. /*!
  53. * @brief The callback type, which indicates kinds of notification the callback handles.
  54. *
  55. * Used in the callback configuration structure (notifier_callback_config_t)
  56. * to specify when the registered callback is called during configuration switch initiated by the
  57. * NOTIFIER_SwitchConfig().
  58. * Callback can be invoked in following situations.
  59. * - Before the configuration switch (Callback return value can affect NOTIFIER_SwitchConfig()
  60. * execution. See the NOTIFIER_SwitchConfig() and notifier_policy_t documentation).
  61. * - After an unsuccessful attempt to switch configuration
  62. * - After a successful configuration switch
  63. */
  64. typedef enum _notifier_callback_type
  65. {
  66. kNOTIFIER_CallbackBefore = 0x01U, /*!< Callback handles BEFORE notification. */
  67. kNOTIFIER_CallbackAfter = 0x02U, /*!< Callback handles AFTER notification. */
  68. kNOTIFIER_CallbackBeforeAfter = 0x03U, /*!< Callback handles BEFORE and AFTER notification. */
  69. } notifier_callback_type_t;
  70. /*! @brief Notifier user configuration type.
  71. *
  72. * Reference of the user defined configuration is stored in an array; the notifier switches between these configurations
  73. * based on this array.
  74. */
  75. typedef void notifier_user_config_t;
  76. /*! @brief Notifier user function prototype
  77. * Use this function to execute specific operations in configuration switch.
  78. * Before and after this function execution, different notification is sent to registered callbacks.
  79. * If this function returns any error code, NOTIFIER_SwitchConfig() exits.
  80. *
  81. * @param targetConfig target Configuration.
  82. * @param userData Refers to other specific data passed to user function.
  83. * @return An error code or kStatus_Success.
  84. */
  85. typedef status_t (*notifier_user_function_t)(notifier_user_config_t *targetConfig, void *userData);
  86. /*! @brief notification block passed to the registered callback function. */
  87. typedef struct _notifier_notification_block
  88. {
  89. notifier_user_config_t *targetConfig; /*!< Pointer to target configuration. */
  90. notifier_policy_t policy; /*!< Configure transition policy. */
  91. notifier_notification_type_t notifyType; /*!< Configure notification type. */
  92. } notifier_notification_block_t;
  93. /*!
  94. * @brief Callback prototype.
  95. *
  96. * Declaration of a callback. It is common for registered callbacks.
  97. * Reference to function of this type is part of the notifier_callback_config_t callback configuration structure.
  98. * Depending on callback type, function of this prototype is called (see NOTIFIER_SwitchConfig())
  99. * before configuration switch, after it or in both use cases to notify about
  100. * the switch progress (see notifier_callback_type_t). When called, the type of the notification
  101. * is passed as a parameter along with the reference to the target configuration structure (see
  102. * notifier_notification_block_t) and any data passed during the callback registration. When notified before the
  103. * configuration switch, depending on the configuration switch policy (see notifier_policy_t), the callback may deny the
  104. * execution of the user function by returning an error code different than kStatus_Success (see
  105. * NOTIFIER_SwitchConfig()).
  106. *
  107. * @param notify Notification block.
  108. * @param data Callback data. Refers to the data passed during callback registration. Intended to
  109. * pass any driver or application data such as internal state information.
  110. * @return An error code or kStatus_Success.
  111. */
  112. typedef status_t (*notifier_callback_t)(notifier_notification_block_t *notify, void *data);
  113. /*!
  114. * @brief Callback configuration structure.
  115. *
  116. * This structure holds the configuration of callbacks.
  117. * Callbacks of this type are expected to be statically allocated.
  118. * This structure contains the following application-defined data.
  119. * callback - pointer to the callback function
  120. * callbackType - specifies when the callback is called
  121. * callbackData - pointer to the data passed to the callback.
  122. */
  123. typedef struct _notifier_callback_config
  124. {
  125. notifier_callback_t callback; /*!< Pointer to the callback function. */
  126. notifier_callback_type_t callbackType; /*!< Callback type. */
  127. void *callbackData; /*!< Pointer to the data passed to the callback. */
  128. } notifier_callback_config_t;
  129. /*!
  130. * @brief Notifier handle structure.
  131. *
  132. * Notifier handle structure. Contains data necessary for the Notifier proper function.
  133. * Stores references to registered configurations, callbacks, information about their numbers,
  134. * user function, user data, and other internal data.
  135. * NOTIFIER_CreateHandle() must be called to initialize this handle.
  136. */
  137. typedef struct _notifier_handle
  138. {
  139. notifier_user_config_t **configsTable; /*!< Pointer to configure table. */
  140. uint8_t configsNumber; /*!< Number of configurations. */
  141. notifier_callback_config_t *callbacksTable; /*!< Pointer to callback table. */
  142. uint8_t callbacksNumber; /*!< Maximum number of callback configurations. */
  143. uint8_t errorCallbackIndex; /*!< Index of callback returns error. */
  144. uint8_t currentConfigIndex; /*!< Index of current configuration. */
  145. notifier_user_function_t userFunction; /*!< User function. */
  146. void *userData; /*!< User data passed to user function. */
  147. } notifier_handle_t;
  148. /*******************************************************************************
  149. * API
  150. ******************************************************************************/
  151. #if defined(__cplusplus)
  152. extern "C" {
  153. #endif
  154. /*!
  155. * @brief Creates a Notifier handle.
  156. *
  157. * @param notifierHandle A pointer to the notifier handle.
  158. * @param configs A pointer to an array with references to all configurations which is handled by the Notifier.
  159. * @param configsNumber Number of configurations. Size of the configuration array.
  160. * @param callbacks A pointer to an array of callback configurations.
  161. * If there are no callbacks to register during Notifier initialization, use NULL value.
  162. * @param callbacksNumber Number of registered callbacks. Size of the callbacks array.
  163. * @param userFunction User function.
  164. * @param userData User data passed to user function.
  165. * @return An error Code or kStatus_Success.
  166. */
  167. status_t NOTIFIER_CreateHandle(notifier_handle_t *notifierHandle,
  168. notifier_user_config_t **configs,
  169. uint8_t configsNumber,
  170. notifier_callback_config_t *callbacks,
  171. uint8_t callbacksNumber,
  172. notifier_user_function_t userFunction,
  173. void *userData);
  174. /*!
  175. * @brief Switches the configuration according to a pre-defined structure.
  176. *
  177. * This function sets the system to the target configuration. Before transition,
  178. * the Notifier sends notifications to all callbacks registered to the callback table.
  179. * Callbacks are invoked in the following order: All registered callbacks are notified
  180. * ordered by index in the callbacks array. The same order is used for before and after switch notifications.
  181. * The notifications before the configuration switch can be used to obtain confirmation about
  182. * the change from registered callbacks. If any registered callback denies the
  183. * configuration change, further execution of this function depends on the notifier policy: the
  184. * configuration change is either forced (kNOTIFIER_PolicyForcible) or exited (kNOTIFIER_PolicyAgreement).
  185. * When configuration change is forced, the result of the before switch notifications are ignored. If an
  186. * agreement is required, if any callback returns an error code, further notifications
  187. * before switch notifications are cancelled and all already notified callbacks are re-invoked.
  188. * The index of the callback which returned error code during pre-switch notifications is stored
  189. * (any error codes during callbacks re-invocation are ignored) and NOTIFIER_GetErrorCallback() can be used to get it.
  190. * Regardless of the policies, if any callback returns an error code, an error code indicating in which phase
  191. * the error occurred is returned when NOTIFIER_SwitchConfig() exits.
  192. * @param notifierHandle pointer to notifier handle
  193. * @param configIndex Index of the target configuration.
  194. * @param policy Transaction policy, kNOTIFIER_PolicyAgreement or kNOTIFIER_PolicyForcible.
  195. *
  196. * @return An error code or kStatus_Success.
  197. *
  198. */
  199. status_t NOTIFIER_SwitchConfig(notifier_handle_t *notifierHandle, uint8_t configIndex, notifier_policy_t policy);
  200. /*!
  201. * @brief This function returns the last failed notification callback.
  202. *
  203. * This function returns an index of the last callback that failed during the configuration switch while
  204. * the last NOTIFIER_SwitchConfig() was called. If the last NOTIFIER_SwitchConfig() call ended successfully
  205. * value equal to callbacks number is returned. The returned value represents an index in the array of
  206. * static call-backs.
  207. *
  208. * @param notifierHandle Pointer to the notifier handle
  209. * @return Callback Index of the last failed callback or value equal to callbacks count.
  210. */
  211. uint8_t NOTIFIER_GetErrorCallbackIndex(notifier_handle_t *notifierHandle);
  212. #if defined(__cplusplus)
  213. }
  214. #endif /* __cplusplus */
  215. /*! @}*/
  216. #endif /* _FSL_NOTIFIER_H_ */