1 /*$Id: //dwh/bluetooth/DWC_ble154combo/firmware/rel/1.30a-SOW05Patchv6_2/firmware/public_inc/os_wrapper.h#1 $*/ 2 /** 3 ******************************************************************************** 4 * @file os_wrapper.h 5 * @brief Wrapper header for OS porting 6 ****************************************************************************** 7 * @copy 8 * This Synopsys DWC Bluetooth Low Energy Combo Link Layer/MAC software and 9 * associated documentation ( hereinafter the "Software") is an unsupported 10 * proprietary work of Synopsys, Inc. unless otherwise expressly agreed to in 11 * writing between Synopsys and you. The Software IS NOT an item of Licensed 12 * Software or a Licensed Product under any End User Software License Agreement 13 * or Agreement for Licensed Products with Synopsys or any supplement thereto. 14 * Synopsys is a registered trademark of Synopsys, Inc. Other names included in 15 * the SOFTWARE may be the trademarks of their respective owners. 16 * 17 * Synopsys MIT License: 18 * Copyright (c) 2020-Present Synopsys, Inc 19 * 20 * Permission is hereby granted, free of charge, to any person obtaining a copy of 21 * the Software), to deal in the Software without restriction, including without 22 * limitation the rights to use, copy, modify, merge, publish, distribute, 23 * sublicense, and/or sell copies of the Software, and to permit persons to whom 24 * the Software is furnished to do so, subject to the following conditions: 25 * 26 * The above copyright notice and this permission notice shall be included in all 27 * copies or substantial portions of the Software. 28 * 29 * THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 30 * IMPLIED, INCLUDING, BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 31 * FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE 32 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 33 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE ARISING FROM, 34 * OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 35 * 36 * */ 37 38 /* Define to prevent recursive inclusion */ 39 #ifndef INCLUDE_OS_WRAPPER_H_ 40 #define INCLUDE_OS_WRAPPER_H_ 41 42 #include "stdint.h" 43 44 /* Exported Defines -----------------------------------------------------------*/ 45 46 #define os_Pool_Def(type) \ 47 os_pool_def_t os_pool_##type 48 49 #define os_Pool(type) \ 50 &os_pool_##type 51 52 #define os_Pool_Def_extern(type) \ 53 extern os_pool_def_t os_pool_##type 54 55 /* Exported macros ------------------------------------------------------------*/ 56 /* Exported types -------------------------------------------------------------*/ 57 58 /** 59 * @brief Interrupt status. 60 */ 61 typedef enum int_state { 62 NOT_ACTIVE, 63 LINK_LAYER_INTRPT, 64 LINK_LAYER_LOW_PRIORITY_INTRPT, 65 UART_READ_INTRPT, 66 UART_WRITE_INTRPT, 67 TIMER_INTRPT, 68 MAC_INTRPT, 69 TOTAL_INTERRUPTS 70 } int_state_e; 71 72 /** 73 * @brief Priority used for thread control. 74 */ 75 typedef enum { 76 os_priority_high, 77 os_priority_normal, 78 os_priority_low, 79 } os_priority; 80 81 /** 82 * @brief SW Timer Activity Status. 83 */ 84 typedef enum _sw_timer_activity_status_e { 85 SW_TIMER_NOT_ACTIVE = 0x00, 86 SW_TIMER_ACTIVE = 0x01, 87 SW_TIMER_MAY_BE_NOT_ACTIVE = 0x02 88 } sw_timer_activity_status_e; 89 90 /** 91 * @brief SW Timer Type. 92 */ 93 typedef enum { 94 os_timer_once = 0, ///< one-shot timer 95 os_timer_periodic = 1 ///< repeating timer 96 } os_timer_type; 97 98 99 /** 100 * @brief SW Timer Priority. 101 */ 102 typedef enum { 103 lw_prio_tmr = 0, // Low Priority Timer 104 hg_prio_tmr = 1 // High Priority Timer 105 } os_timer_prio; 106 107 108 /** 109 * @brief Software Timer State Active, Expired or Stopped 110 */ 111 typedef enum { 112 osTimerActive, /**< @brief Active timer : Timer in the list waiting for its time to fire */ 113 osTimerExpired, /**< @brief Expired timer: Timer fired and removed form the list, or created and not exist in the list */ 114 osTimerStopped /**< @brief Stopped timer: Timer stopped and removed form the list */ 115 } os_timer_state; 116 117 // Thread Management 118 typedef void (*os_pthread) (void const *argument); 119 typedef void* os_thread_id; 120 121 // Timer Management 122 typedef void (*t_timer_callbk)(const void*); 123 typedef void* os_timer_id; 124 typedef void (*os_timer_activity_cb_t)(sw_timer_activity_status_e timer_activity); 125 typedef struct sw_timer sw_timer_t; 126 127 // Mutex Management 128 typedef void os_mutex_def_t; 129 typedef void * os_mutex_id; 130 131 // Semaphore Management 132 typedef void os_semaphore_def_t; 133 typedef void * os_semaphore_id; 134 135 /** 136 * @brief Software Timer structure. 137 */ 138 struct sw_timer { 139 sw_timer_t *stnext; /**< @brief Next timer in the timers list. */ 140 uint32_t vtime; /**< @brief value of timer */ 141 uint32_t rtime; /**< @brief remain time. */ 142 t_timer_callbk ptimer; /**< @brief Timer callback function pointer. */ 143 void *argument; /**< @brief Timer callback function arguments. */ 144 uint16_t overflow_flag : 1; 145 uint16_t frac_time : 5; /** < @brief fraction time of period [0:31] in terms of us */ 146 uint16_t cycles : 5; /** < @brief cycles [0:31] number of elapsed cycles of periodic timer */ 147 uint16_t rem_time : 5; /** < @brief remainder to be added to the fraction [0:31] in terms of us */ 148 uint8_t state; /**< @brief Timer State : Active or Expired or Stopped */ 149 uint8_t type:1 ; /**< @brief Timer Type : one-shot (0) or periodic (1) */ 150 uint8_t prio:1 ; /* used to indicate if this timer ISR should be handled from hg isr in case of allow_lw_isr==1 */ 151 }; 152 153 /** 154 * @brief Memory Block Structure 155 */ 156 typedef struct _mem_blck_t { 157 /* 8 bits | 8 bits | 8 bits | 8 bits * 158 * Free memory chunk flag | sub-pool number | reserved | handle_id */ 159 uint32_t flag; 160 struct _mem_blck_t * next; 161 } mem_blck_t; 162 163 /** 164 * @brief Memory Pool Block Structure 165 */ 166 typedef struct { 167 uint32_t blck_size; /* block size */ 168 mem_blck_t* next_blck; /* next free block */ 169 } os_pool_def_t; 170 171 /* Exported functions ---------------------------------------------------------*/ 172 173 /** 174 * @brief Creates a thread 175 * 176 * @param thread Pointer to a function to be executed by the thread 177 * @param name Thread's name 178 * @param pri Thread's priority 179 * @param argu Arguments to be passed to the function executed by the thread 180 * @param stack_size Thread stack size 181 * 182 * @retval Handle of the created task 183 */ 184 os_thread_id os_thread_create( 185 os_pthread thread, 186 char* name, 187 os_priority pri, 188 void* argu, 189 uint32_t stack_size); 190 191 /** 192 * @brief Registers an interrupt function corresponding to the passed interrupt ID 193 * 194 * @param ptr_int_hndlr Interrupt function 195 * @param int_id Interrupt ID 196 */ 197 void intr_hndlr_reg( 198 void (*ptr_int_hndlr)(void), 199 int_state_e int_id); 200 201 /** 202 * @brief initialize function to to os_wrapper 203 */ 204 void os_wrapper_init(void); 205 206 /** 207 * @brief reset function to os_wrapper component 208 */ 209 void os_wrapper_reset(void); 210 211 212 /** 213 * @brief initialize timer function 214 */ 215 void os_timer_init(void); 216 217 /** 218 * @brief initialize timer function 219 */ 220 void os_timer_reset(void); 221 222 /** @ingroup SW_TIMER 223 * @{ 224 */ 225 /** 226 * @brief create a new timer 227 * 228 * @param p_callbk pointer to the call_back function. 229 * @param type os_timer_once for one-shot or os_timer_periodic for periodic behavior. 230 * @param argument argument to the timer call back function. 231 * 232 * @retval timer ID for reference by other functions or NULL in case of error. 233 */ 234 void* os_timer_create( 235 t_timer_callbk p_callbk, 236 os_timer_type type, 237 void *argument); 238 239 240 /** 241 * @brief set the timer priority 242 * 243 * @param timer id 244 * @param tmr_prio: the new priority of the timer in case of allow_lw_isr==1 245 * 246 * @retval None 247 */ 248 void os_timer_set_prio(os_timer_id timer_id , 249 os_timer_prio tmr_prio); 250 251 /** 252 * @brief get the timer priority 253 * 254 * @retval get the priority of the SW timers head 255 */ 256 uint8_t os_timer_is_any_near_sw_timer_hg_prio(void); 257 258 259 /** 260 * @brief start a running timer. 261 * 262 * @param timer_id timer Id. 263 * @param steps number of steps in 31.25 us resolution 264 * 265 * @retval error code. 266 */ 267 int32_t os_timer_start( 268 os_timer_id timer_id, 269 uint32_t steps); 270 271 /** 272 * @brief start a running timer. 273 * 274 * @param timer_id timer Id. 275 * @param time_us time in us 276 * 277 * @retval error code. 278 */ 279 int32_t os_timer_start_in_us( 280 os_timer_id timer_id, 281 uint32_t time_us); 282 283 /** 284 * @brief stop a running timer. 285 * 286 * @param timer_id timer Id. 287 * 288 * @retval error code. 289 */ 290 int32_t os_timer_stop( 291 os_timer_id timer_id); 292 293 /** 294 * @brief free an allocated timer. 295 * 296 * @param timer_id timer Id. 297 * 298 * @retval error code. 299 */ 300 int32_t os_timer_free( 301 os_timer_id timer_id); 302 303 /** 304 * @brief Stop the timer if it is running and delete it. 305 * 306 * @param ptr_timer_id pointer to the timer ID obtained by os_timer_create. 307 * 308 * @retval status code that indicates the execution status of the function. 309 */ 310 int32_t os_timer_stop_free( 311 os_timer_id *ptr_timer_id); 312 313 /** 314 * @brief Stop the timer if it is running and start it with the new value. 315 * 316 * @param timer timer ID obtained by \ref os_timer_create. 317 * @param steps steps to set the timer with. 318 * 319 * @retval status code that indicates the execution status of the function. 320 */ 321 int32_t os_timer_set( 322 os_timer_id timer, 323 uint32_t steps); 324 325 /** 326 * @brief get the starte of the timer. 327 * 328 * @param timer_id timer Id. 329 * 330 * @retval os_timer_state. Active , Expired, or stopped 331 */ 332 os_timer_state os_get_tmr_state( 333 os_timer_id timer_id); 334 /**@} 335 * * 336 */ 337 /** 338 * @brief Get the number of active SW timers. 339 * 340 * @retval active_sw_timers_num: The number of currently active SW timers 341 */ 342 uint32_t os_timer_get_active_sw_timers_number(void); 343 344 /** 345 * @brief Register a callback function to show whether the timer is in use or not. 346 * 347 * @param cbk : [in] Callback function. 348 */ 349 void os_timer_rgstr_timer_activity_cbk( 350 os_timer_activity_cb_t cbk); 351 352 /** 353 * @brief Gets the remaining time of the first time set to fire, if exists 354 * 355 * @retval Remaining time. 0 if no timers exist. 356 */ 357 uint64_t os_timer_get_earliest_time(void); 358 359 /** 360 * @brief This function calls the proper handling based on the incming interrupt 361 * 362 * @param intrpt_fired current interrupt to be served. 363 */ 364 void os_process_isr( 365 int_state_e intrpt_fired); 366 367 /** 368 * @ingroup os_wrappers 369 * @{ 370 */ 371 /** 372 * @brief disables system Interrupts 373 */ 374 void os_disable_isr(void); 375 376 /** 377 * @brief enables system Interrupts, the imp. should respect the nested disable calls 378 */ 379 void os_enable_isr(void); 380 381 // ==== Mutex Management ==== 382 383 /** 384 * @brief create a new recursive mutex 385 * 386 * @retval handle to the created mutex 387 */ 388 os_mutex_id os_rcrsv_mutex_create(void); 389 390 /** 391 * @brief Wait until a mutex becames available 392 * 393 * @param mutex_id mutex id. 394 * @param millisec time-out value, 0 for no time-out. 395 * 396 * @retval status code , 0 for success 397 */ 398 int32_t os_rcrsv_mutex_wait( 399 os_mutex_id mutex_id, 400 uint32_t millisec); 401 402 /** 403 * @brief Release a mutex 404 * 405 * @param mutex_id mutex id. 406 * 407 * @retval status code, 0 for success 408 */ 409 int32_t os_rcrsv_mutex_release( 410 os_mutex_id mutex_id); 411 412 // ==== Semaphore Management Functions ==== 413 /** 414 * @brief Create and initialize a semaphore 415 * 416 * @param max_count The max value to which the semaphore can count. 417 * @param initial_count initial value assigned to the count. 418 * 419 * @retval semaphore id for reference 420 */ 421 os_semaphore_id os_semaphore_create( 422 int32_t max_count, 423 int32_t initial_count); 424 425 /** 426 * @brief Wait until a semaphore becomes available 427 * 428 * @param semaphore_id semaphore id. 429 * @param millisec time-out value, 0 for no time-out. 430 * 431 * @retval status code, 0 for success 432 */ 433 int32_t os_semaphore_wait( 434 os_semaphore_id semaphore_id, 435 uint32_t millisec); 436 437 /** 438 * @brief Release a semaphore 439 * 440 * @param semaphore_id semaphore id. 441 * 442 * @retval status code, 0 for success 443 */ 444 int32_t os_semaphore_release( 445 os_semaphore_id semaphore_id); 446 447 /** 448 * @brief Release an ISR semaphore 449 * 450 * @param semaphore_id semaphore id. 451 * 452 * @retval status code, 0 for success 453 */ 454 int32_t os_semaphore_release_isr( 455 os_semaphore_id semaphore_id); 456 457 /** 458 * @} 459 */ 460 /* ==== Memory Pool Management Functions ==== */ 461 462 /** 463 * @brief Allocates from the passed memory pool 464 * 465 * @param pool Pointer to the pool to allocate from 466 * 467 * @retval Pointer at the allocated block 468 */ 469 void * os_mem_pool_alloc( 470 os_pool_def_t * pool); 471 472 /** 473 * @brief Frees from the passed memory pool 474 * 475 * @param block Pointer at the block that will be freed 476 */ 477 void os_mem_pool_free( 478 void *block); 479 480 /** 481 * @brief Allocates from the shared memory pool 482 * 483 * @param pool Pointer to the pool to allocate from 484 * 485 * @retval Pointer at the allocated block 486 */ 487 void* os_shrd_mem_alloc( 488 os_pool_def_t * pool); 489 490 /** 491 * @fn uint8_t os_wrapper_is_rtos_used() 492 * 493 * @brief This function used to detect whether RTOS configuration is enabled or not. 494 * @param None. 495 * @return is_rtos_enabled : TRUE: RTOS enabled. FALSE: otherwise 496 */ 497 uint8_t os_wrapper_is_rtos_used(void); 498 499 #endif /* INCLUDE_CONN_MNGR_H_ */ 500
