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