1 /* 2 * Arm SCP/MCP Software 3 * Copyright (c) 2015-2022, Arm Limited and Contributors. All rights reserved. 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 * 7 * Description: 8 * Framework core definitions. 9 */ 10 11 #ifndef FWK_CORE_H 12 #define FWK_CORE_H 13 14 #include <internal/fwk_core.h> 15 16 #include <fwk_event.h> 17 #include <fwk_id.h> 18 19 #include <stdbool.h> 20 #include <stdint.h> 21 22 /*! 23 * \addtogroup GroupLibFramework Framework 24 * \{ 25 */ 26 27 /*! 28 * \defgroup GroupFwkCore Core 29 * 30 * \{ 31 */ 32 33 /*! 34 * \brief Put an event in one of the event queues. 35 * 36 * \details The framework copies the event description into its internal data 37 * and so does not keep track of the pointer passed as a parameter. 38 * 39 * In the runtime phase, the source identifier of the event is populated 40 * with the identifier of the caller, and it is therefore unnecessary for 41 * the caller to do so manually. Note that this does not occur in the 42 * pre-runtime phase. 43 * 44 * If the function is called from an ISR, the event is put in the ISR 45 * event queue. 46 * 47 * In both cases, the event identifier and target identifier are checked 48 * to be valid and to refer to the same module. 49 * 50 * In the case of a delayed response event, the event's 'is_response' flag 51 * must be set. 52 * 53 * 54 * \param[in] event Pointer to the event to queue. Must not be \c NULL. 55 * 56 * \retval ::FWK_SUCCESS The event was queued. 57 * \retval ::FWK_E_INIT The core framework component is not initialized. 58 * \retval ::FWK_E_PARAM An invalid parameter was encountered: 59 * - The `event` parameter was a null pointer value. 60 * - One or more fields of the event were invalid. 61 * \retval ::FWK_E_OS Operating system error. 62 * 63 * \return Status code representing the result of the operation. 64 */ 65 #define fwk_put_event(event) \ 66 _Generic((event), struct fwk_event * \ 67 : __fwk_put_event, struct fwk_event_light * \ 68 : __fwk_put_event_light)(event) 69 70 /*! 71 * \brief Processing events already raised by modules and interrupt handlers. 72 */ 73 void fwk_process_event_queue(void); 74 75 /*! 76 * \brief Get a copy of a delayed response event. 77 * 78 * \details When a module or element delays a response as part of the processing 79 * of an event requiring a response, the framework automatically stores the 80 * delayed response as part of the module or element data internal to the 81 * framework. This function allows to get a copy of such delayed response 82 * event. The event is not removed from the module or element internal 83 * data. If called from an interrupt handler, the function returns in 84 * error. 85 * 86 * \param[in] id Identifier of the module or element that delayed the response. 87 * \param[in] cookie Cookie of the event which the response has been delayed 88 * for. The cookie identifies the response event among the response events 89 * the entity \p id may have delayed. 90 * \param[out] event The copy of the response event. 91 * 92 * \retval ::FWK_SUCCESS The event was returned. 93 * \retval ::FWK_E_PARAM One or more parameters were invalid. 94 * \retval ::FWK_E_ACCESS Access violation due to call from interrupt handler. 95 * 96 * \return Status code representing the result of the operation. 97 */ 98 int fwk_get_delayed_response( 99 fwk_id_t id, 100 uint32_t cookie, 101 struct fwk_event *event); 102 103 /*! 104 * \brief Check if the list of delayed response events of a given module or 105 * element is empty. 106 * 107 * \details When a module or element delays a response as part of the processing 108 * of an event requiring a response, the framework automatically queues the 109 * delayed response in a list that is part of the module or element data 110 * internal to the framework. This function checks if such a list is empty 111 * or not. If called from an interrupt handler, the function returns in 112 * error. 113 * 114 * \param[in] id Identifier of the module or element. 115 * \param[out] is_empty \c true if the list is empty, \c false otherwise. 116 * 117 * \retval ::FWK_SUCCESS The flag was returned. 118 * \retval ::FWK_E_PARAM One or more parameters were invalid. 119 * \retval ::FWK_E_ACCESS Access violation due to call from interrupt handler. 120 * 121 * \return Status code representing the result of the operation. 122 */ 123 int fwk_is_delayed_response_list_empty(fwk_id_t id, bool *is_empty); 124 125 /*! 126 * \brief Get a copy of the first delayed response event in the list of 127 * delayed response events of a given module or element. 128 * 129 * \details When a module or element delays a response as part of the processing 130 * of an event requiring a response, the framework automatically queues 131 * the delayed response in a list that is part of the module or element 132 * data internal to the framework. This function allows a copy of the first 133 * event of such a list to be retrieved. The event is not removed from the 134 * module or element internal data. This function may be use to process the 135 * delayed responses in the order they were queued. If called from an 136 * interrupt handler, the function returns in error. 137 * 138 * \param[in] id Identifier of the module or element that delayed the response. 139 * \param[out] event The copy of the response event. 140 * 141 * \retval ::FWK_SUCCESS The event was returned. 142 * \retval ::FWK_E_STATE The list of delayed response event for \p id is empty. 143 * \retval ::FWK_E_PARAM One or more parameters were invalid. 144 * \retval ::FWK_E_ACCESS Access violation due to call from interrupt handler. 145 * 146 * \return Status code representing the result of the operation. 147 */ 148 int fwk_get_first_delayed_response(fwk_id_t id, struct fwk_event *event); 149 150 /*! 151 * \} 152 */ 153 154 /*! 155 * \} 156 */ 157 #endif /* FWK_CORE_H */ 158