1 /*$Id: //dwh/bluetooth/DWC_ble154combo/firmware/rel/1.32a-lca02/firmware/public_inc/evnt_schdlr_gnrc_if.h#2 $*/ 2 /** 3 ******************************************************************************** 4 * @file evnt_schdlr_gnrc_if.h 5 * @brief This file contains all the functions prototypes for the evnt_schdlr.c 6 * that are used by other layers to interface with the scheduler. 7 ****************************************************************************** 8 * @copy 9 * This Synopsys DWC Bluetooth Low Energy Combo Link Layer/MAC software and 10 * associated documentation ( hereinafter the "Software") is an unsupported 11 * proprietary work of Synopsys, Inc. unless otherwise expressly agreed to in 12 * writing between Synopsys and you. The Software IS NOT an item of Licensed 13 * Software or a Licensed Product under any End User Software License Agreement 14 * or Agreement for Licensed Products with Synopsys or any supplement thereto. 15 * Synopsys is a registered trademark of Synopsys, Inc. Other names included in 16 * the SOFTWARE may be the trademarks of their respective owners. 17 * 18 * Synopsys MIT License: 19 * Copyright (c) 2020-Present Synopsys, Inc 20 * 21 * Permission is hereby granted, free of charge, to any person obtaining a copy of 22 * the Software), to deal in the Software without restriction, including without 23 * limitation the rights to use, copy, modify, merge, publish, distribute, 24 * sublicense, and/or sell copies of the Software, and to permit persons to whom 25 * the Software is furnished to do so, subject to the following conditions: 26 * 27 * The above copyright notice and this permission notice shall be included in all 28 * copies or substantial portions of the Software. 29 * 30 * THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 31 * IMPLIED, INCLUDING, BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 32 * FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE 33 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 34 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE ARISING FROM, 35 * OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 36 * 37 * */ 38 39 /** 40 * @ingroup gnrc_schdlr_intf 41 * @brief Provides APIs to register an external event in the system, all operations for utilizing the generic interface are part of the APIs in evnt_schdlr_gnrc_if.h header file. 42 * * @{ 43 */ 44 /* Define to prevent recursive inclusion -------------------------------------*/ 45 #ifndef INCLUDE_EVNT_GNRC_SCHDLR_IF_H_ 46 #define INCLUDE_EVNT_GNRC_SCHDLR_IF_H_ 47 48 49 /* Includes ------------------------------------------------------------------*/ 50 #include <stdint.h> 51 52 #include "bsp.h" 53 #include "os_wrapper.h" 54 #include "common_types.h" 55 56 typedef void* ext_evnt_hndl_t; 57 58 59 /** 60 * @brief Generic External Event node that holds the the external event information. 61 * @note All parameters that are related to time assumed to be in microseconds 62 */ 63 typedef struct _extrnl_evnt_st_t{ 64 /** Event must end before this point in time (us) it is an optional parameter and 65 * it should set with zero if not used by stack.*/ 66 uint64_t deadline; 67 68 /** Earliest time the event can start (us) , it is an optional parameter and 69 * it should set with zero if not used by stack.it is not logical to have periodic event with max start time. 70 * So, it will be neglected and never checked in case of periodic event.*/ 71 uint64_t strt_min; 72 /** Latest time the event can start (us), it is an optional parameter and 73 * it should set with zero if not used by stack.*/ 74 uint64_t strt_max; 75 /** Minimum amount of time that must be allocated to the event (us) , */ 76 uint32_t durn_min; 77 /** Maximum amount of time that the event is requesting (us), it is an optional parameter and 78 * it should set with zero if not used by stack.*/ 79 uint32_t durn_max; 80 /** Periodicity of the event (us), 0: Not Periodic 81 * if the value is not zero , it should be multiple of 1250 us to be aligned with BLE events.*/ 82 uint32_t prdc_intrvl; 83 /** Priority of the event from @ref _extrnl_evnt_priority_e*/ 84 extrnl_evnt_priority_e priority; 85 /** Event blocked or not, and reason if blocked from @ref _extrnl_evnt_state_e */ 86 extrnl_evnt_state_e blocked; 87 /** Pointer to private data that should passed with the call back function */ 88 void* ptr_priv; 89 /** Event Started Callback Function , this function will be called at the allocated time to do the job related to 90 * executing the event, it must not be NULL. 91 * At the end of given grant, @ref evnt_schdlr_gnrc_evnt_cmplt function should be called to inform scheduler 92 * that the event is finished, and PHY should not be accessed after that call until a new grant is given 93 * from event scheduler. @ref evnt_strtd_cbk should handle calling of @ref evnt_schdlr_gnrc_evnt_cmplt via timer or 94 * at the end of execution if the execution is blocking 95 * 96 * if @ref slot_durn is set to zero "0" , event scheduler has given the on idle event unlimited grant. 97 * It will be aborted later with a calling to evnt_abortd_cbk function.*/ 98 uint32_t (*evnt_strtd_cbk)(ext_evnt_hndl_t evnt_hndl, 99 uint32_t slot_durn, void* priv_data_ptr); 100 /** Event Blocked Callback Function , called if the event is blocked due deadline or other reasons as 101 * in @ref blocked_state .it could be NULL if not used by stack 102 * if it is not NULL ,it will be called when event exceeded the given maximum start time or the given deadline while scheduling the event*/ 103 uint32_t (*evnt_blckd_cbk)(extrnl_evnt_state_e blocked_state); 104 /** Event Aborted Callback Function. it could be NULL if not used by stack. it will be called when event execution is aborted. 105 * the event @ref EXTRNL_ON_IDLE is the only event type that can be aborted so it must not be NULL for this event type 106 * when it is called from event scheduler, the stack should stop all running operation that access phy, 107 * no need to call @ref evnt_schdlr_gnrc_evnt_cmpltafter calling this callback as it is called from scheduler itself. 108 * */ 109 uint32_t (*evnt_abortd_cbk)(void); 110 /** Event coexistence error Callback Function. it will be called when @ref EXTRNL_GNRC event execution returned error. 111 * when @ref evnt_strtd_cbk of @ref EXTRNL_GNRC failed at execution for any reason, this callback will be called from event scheduler, 112 * it'll send the returned error to ral_tx_done to check if there will retransmission of failed packet or send the error to upper layers, 113 * */ 114 void (*coex_error_cbk)(uint32_t error); 115 } extrnl_evnt_st_t; 116 #if(SUPPORT_COEXISTENCE || SUPPORT_GNRC_SCHDLR_IF) 117 /** 118 * @brief request duration extension of previous registered external generic event. 119 * 120 * @param evnt_hndl_t [in] : Event handle of registered event. 121 * @param updated_priority [in] : Updated priority of the event during new extend request. 122 * @param flxbl_req [in] : Flexible request flag, 123 * True: scheduler will try to extend duration with available duration up to requested deadline 124 * False: scheduler will try to extend duration with requested duration only (full requested duration or not) 125 * @param reqstd_deadline [in and out] : Pointer to new end time that the event request to extend the grant to it. 126 * It is also will be used as an output to report the given grant end time if the request is successfully accepted.. 127 * @retval Status (0: SUCCESS, 0xXX: ERROR_CODE from @ref ble_stat_t). 128 */ 129 uint32_t evnt_schdlr_extend_gnrc_evnt_durn(ext_evnt_hndl_t evnt_hndl, extrnl_evnt_priority_e updated_priority, 130 uint8_t flxbl_req, uint64_t *reqstd_deadline); 131 132 /** 133 * @brief register external generic event. 134 * This function is used to register external generic event in event scheduler.all required information to schedule this event are contained in @ref p_extrnl_evnt_st parameter 135 * @param p_extrnl_evnt_st [in] : Pointer to external event structure. 136 * @retval evnt_hndl_t : The event handle of registered event. 137 * @retval NULL : means that the event is not registered. 138 */ 139 ext_evnt_hndl_t evnt_schdlr_rgstr_gnrc_evnt(extrnl_evnt_st_t* p_extrnl_evnt_st); 140 141 /** 142 * @brief un-register external generic/ onidle event. 143 * This function is used to remove external generic event from event scheduler. 144 * @param evnt_hndl [in] : Event handle of generic event to be removed from scheduler. 145 * @retval Status (0: SUCCESS, 0xXX: ERROR_CODE from @ref ble_stat_t). 146 */ 147 uint32_t evnt_schdlr_unrgstr_gnrc_evnt(ext_evnt_hndl_t evnt_hndl); 148 /** 149 * @brief register external on idle event. 150 * 151 * the external on idle event is low priority event that will be executed in scheduler idle time. 152 * if multiple on idle events are registered the scheduler will divide the idle on them in round robin manner. 153 * @note All parameters in in @ ref _extrnl_evnt_st_t will be ignored except ptr_priv parameter, 154 * as it will be passed to event started call back 155 * @note @ref evnt_strtd_cbk and @ref evnt_abortd_cbk pointers must not be NULL, 156 * as event scheduler will call evnt_abortd_cbk to stop current running on idle event 157 * if other higher event wants to access air while on idle event has grant to access it. 158 * 159 * @note There is no need to call this function more than once as the event scheduler 160 * stores the event and will call it every time it has a window to start on idle event 161 * 162 * @param p_extrnl_evnt_st [in] : Pointer to external event structure. 163 * @retval evnt_hndl_t : The event handle of registered event. 164 * @retval NULL : means that the event is not registered. 165 */ 166 ext_evnt_hndl_t evnt_schdlr_rgstr_on_idle_evnt(extrnl_evnt_st_t* p_extrnl_evnt_st); 167 #if SUPPORT_COEXISTENCE 168 /** 169 * @brief Disable aborting the on idle event given by the handle @ref on_idle_evnt_hdl. the user should call @ref evnt_schdlr_gnrc_evnt_cmplt after the event is completed 170 * 171 * @note the usage of this function should be limited to the cases where the event can't be aborted like MAC DTM. and the user should return the grant to scheduler as fast as possible. 172 * if this function is called where the event is granted, scheduler will ignore all other event till the grant is return to scheduler. it is not recommended to use this function 173 * 174 * @param on_idle_evnt_hdl [in] : handle of the on the idle event to disable aborting it 175 * @retval None 176 */ 177 void evnt_schdlr_disable_idle_abort(ext_evnt_hndl_t on_idle_evnt_hdl); 178 #endif /* SUPPORT_COEXISTENCE */ 179 #endif /* (#if SUPPORT_COEXISTENCE || SUPPORT_GNRC_SCHDLR_IF) */ 180 181 /** 182 * @brief external generic event complete. 183 * 184 * This function is used to return the grant back to event scheduler 185 * at the end of duration given at the started function from event scheduler @ref _extrnl_evnt_st_t for more info 186 * 187 * @param evnt_hndl_t [in] : Event handle of registered event. 188 * @retval Status (0: SUCCESS, 0xXX: ERROR_CODE from @ref ble_stat_t). 189 */ 190 uint32_t evnt_schdlr_gnrc_evnt_cmplt(ext_evnt_hndl_t evnt_hndl); 191 #if(SUPPORT_COEXISTENCE || SUPPORT_GNRC_SCHDLR_IF) 192 /** 193 * @brief Confirm the event currently has grant to access phy from event scheduler. 194 * 195 * @param evnt_hndl [in] : pointer of event scheduler handle. 196 * @retval 1: grant given. 197 * @retval 0: no grant given. 198 */ 199 uint8_t evnt_schdlr_confrm_grant(void * evnt_hndl); 200 #endif /* (SUPPORT_COEXISTENCE || SUPPORT_GNRC_SCHDLR_IF) */ 201 202 #endif /* INCLUDE_EVNT_SCHDLR_IF_H */ 203 /** 204 * @} 205 */ 206
