1 #ifndef _RWIP_H_ 2 #define _RWIP_H_ 3 4 /** 5 **************************************************************************************** 6 * @addtogroup ROOT 7 * @brief Entry points of the RW IP stacks/modules 8 * 9 * This module contains the primitives that allow an application accessing and running the 10 * RW IP protocol stacks / modules. 11 * 12 * @{ 13 **************************************************************************************** 14 */ 15 16 /* 17 * INCLUDE FILES 18 **************************************************************************************** 19 */ 20 #include "rwip_config.h" // stack configuration 21 22 #include <stdint.h> // standard integer definitions 23 #include <stdbool.h> // standard boolean definitions 24 25 26 /* 27 * DEFINES 28 **************************************************************************************** 29 */ 30 /// Maximum value of a Bluetooth clock (in 312.5us half slots) 31 #define RWIP_MAX_CLOCK_TIME ((1L<<32) - 1) 32 /// Maximum value of a 10ms Bluetooth clock 33 #define RWIP_MAX_10MS_TIME ((1L<<25) - 1) 34 /// retrieve 10ms time according to clock time 35 #define RWIP_CLOCK_TO_10MS_TIME(clock) ((clock) >> 5) 36 /// retrieve clock time according to 10ms time 37 #define RWIP_10MS_TIME_TO_CLOCK(time) ((time) << 5) 38 /// Invalid target time 39 #define RWIP_INVALID_TARGET_TIME (0xFFFFFFFFL) 40 41 42 /// result of sleep state. 43 enum rwip_sleep_state 44 { 45 /// Some activity pending, can not enter in sleep state 46 RWIP_ACTIVE = 0, 47 /// CPU can be put in sleep state 48 RWIP_CPU_SLEEP, 49 /// IP could enter in deep sleep 50 RWIP_DEEP_SLEEP, 51 }; 52 53 54 /// Definition of the bits preventing the system from sleeping 55 enum prevent_sleep 56 { 57 /// Flag indicating that the wake up process is ongoing 58 RW_WAKE_UP_ONGOING = 0x0001, 59 /// Flag indicating that an TX transfer is ongoing on Transport Layer 60 RW_TL_TX_ONGOING = 0x0002, 61 /// Flag indicating that an RX transfer is ongoing on Transport Layer 62 RW_TL_RX_ONGOING = 0x0004, 63 /// Flag indicating HCI timeout is ongoing 64 RW_AHI_TIMEOUT = 0x0008, 65 /// Flag indicating that an encryption is ongoing 66 RW_CRYPT_ONGOING = 0x0010, 67 /// Flag indicating that controller shall not sleep due to not CSB LPO_Allowed 68 RW_CSB_NOT_LPO_ALLOWED = 0x0040, 69 /// Flag indicating the MWS/WLAN Event Generator is in operation 70 RW_MWS_WLAN_EVENT_GENERATOR_ACTIVE = 0x0080, 71 /// Flag to indicate that platform does not support deep sleep 72 RW_PLF_DEEP_SLEEP_DISABLED = 0x0100, 73 }; 74 75 /// Parameters - Possible Returned Status 76 enum PARAM_STATUS 77 { 78 /// PARAM status OK 79 PARAM_OK, 80 /// generic PARAM status KO 81 PARAM_FAIL, 82 /// PARAM ID unrecognized 83 PARAM_ID_NOT_DEFINED, 84 /// No space for PARAM 85 PARAM_NO_SPACE_AVAILABLE, 86 /// Length violation 87 PARAM_LENGTH_OUT_OF_RANGE, 88 /// PARAM parameter locked 89 PARAM_PARAM_LOCKED, 90 /// PARAM corrupted 91 PARAM_CORRUPT 92 }; 93 94 /** 95 * External interface type types. 96 */ 97 enum rwip_eif_types 98 { 99 /// Host Controller Interface - Controller part 100 RWIP_EIF_HCIC, 101 102 /// Host Controller Interface - Host part 103 RWIP_EIF_HCIH, 104 105 /// Application Host interface 106 RWIP_EIF_AHI, 107 }; 108 109 110 /// Enumeration of External Interface status codes 111 enum rwip_eif_status 112 { 113 /// EIF status OK 114 RWIP_EIF_STATUS_OK, 115 /// EIF status KO 116 RWIP_EIF_STATUS_ERROR, 117 118 #if (BLE_EMB_PRESENT == 0) 119 /// External interface detached 120 RWIP_EIF_STATUS_DETACHED, 121 /// External interface attached 122 RWIP_EIF_STATUS_ATTACHED, 123 #endif // (BLE_EMB_PRESENT == 0) 124 }; 125 126 /// Enumeration of RF modulations 127 enum rwip_rf_mod 128 { 129 MOD_GFSK = 0x01, 130 MOD_DQPSK = 0x02, 131 MOD_8DPSK = 0x03, 132 }; 133 134 /* 135 * TYPE DEFINITIONS 136 **************************************************************************************** 137 */ 138 139 /// Time information 140 typedef struct 141 { 142 /// Time in 312.5 us step. 143 uint32_t time; 144 /// number of half us before getting next tick 145 uint32_t next_tick; 146 } rwip_time_t; 147 148 149 150 /// API functions of the RF driver that are used by the BLE or BT software 151 struct rwip_rf_api 152 { 153 /// Function called upon HCI reset command reception 154 void (*reset)(void); 155 /// Function called to enable/disable force AGC mechanism (true: en / false : dis) 156 void (*force_agc_enable)(bool); 157 /// Function called when TX power has to be decreased for a specific link id 158 bool (*txpwr_dec)(uint8_t); 159 /// Function called when TX power has to be increased for a specific link id 160 bool (*txpwr_inc)(uint8_t); 161 /// Function called when TX power has to be set to max for a specific link id 162 void (*txpwr_max_set)(uint8_t); 163 /// Function called to convert a TX power CS power field into the corresponding value in dBm 164 uint8_t (*txpwr_dbm_get)(uint8_t, uint8_t); 165 /// Function called to convert a power in dBm into a control structure tx power field 166 uint8_t (*txpwr_cs_get)(int8_t, bool); 167 /// Function called to convert the RSSI read from the control structure into a real RSSI 168 int8_t (*rssi_convert)(uint8_t); 169 /// Function used to read a RF register 170 uint32_t (*reg_rd)(uint16_t); 171 /// Function used to write a RF register 172 void (*reg_wr)(uint16_t, uint32_t); 173 /// Function called to put the RF in deep sleep mode 174 void (*sleep)(void); 175 /// Index of minimum TX power 176 uint8_t txpwr_min; 177 /// Index of maximum TX power 178 uint8_t txpwr_max; 179 /// RSSI high threshold ('real' signed value in dBm) 180 int8_t rssi_high_thr; 181 /// RSSI low threshold ('real' signed value in dBm) 182 int8_t rssi_low_thr; 183 /// interferer threshold ('real' signed value in dBm) 184 int8_t rssi_interf_thr; 185 /// RF wakeup delay (in slots) 186 uint8_t wakeup_delay; 187 }; 188 189 /// API functions of the parameters that are used by the BLE or BT software 190 struct rwip_param_api 191 { 192 /** 193 * Get a parameter value 194 * @param[in] param_id Parameter identifier 195 * @param[in/out] lengthPtr Pointer to the length of the parameter (input: contain max length, output contain the effective param length) 196 * @param[out] buf Pointer to the buffer be filled with the parameter value 197 * @return status 0: success | >0 : error 198 */ 199 uint8_t (*get) (uint8_t param_id, uint8_t * lengthPtr, uint8_t *buf); 200 201 /** 202 * Set a parameter value 203 * @param[in] param_id Parameter identifier 204 * @param[in/out] length Length of the parameter 205 * @param[out] buf Pointer to the buffer containing the parameter value 206 * @return status 0: success | >0 : error 207 */ 208 uint8_t (*set) (uint8_t param_id, uint8_t length, uint8_t *buf); 209 210 /** 211 * Delete a parameter 212 * @param[in] param_id Parameter identifier 213 * @return status 0: success | >0 : error 214 */ 215 uint8_t (*del) (uint8_t param_id); 216 }; 217 218 /// Internal API for priority 219 struct rwip_prio 220 { 221 ///value 222 uint8_t value; 223 ///Increment 224 uint8_t increment; 225 }; 226 /** 227 **************************************************************************************** 228 * @brief Function called when packet transmission/reception is finished. 229 230 * @param[in] dummy Dummy data pointer returned to callback when operation is over. 231 * @param[in] status Ok if action correctly performed, else reason status code. 232 ***************************************************************************************** 233 */ 234 typedef void (*rwip_eif_callback) (void*, uint8_t); 235 236 /** 237 * Transport layer communication interface. 238 */ 239 struct rwip_eif_api 240 { 241 /** 242 ************************************************************************************* 243 * @brief Starts a data reception. 244 * 245 * @param[out] bufptr Pointer to the RX buffer 246 * @param[in] size Size of the expected reception 247 * @param[in] callback Pointer to the function called back when transfer finished 248 * @param[in] dummy Dummy data pointer returned to callback when reception is finished 249 ************************************************************************************* 250 */ 251 void (*read) (uint8_t *bufptr, uint32_t size, rwip_eif_callback callback, void* dummy); 252 253 /** 254 ************************************************************************************* 255 * @brief Starts a data transmission. 256 * 257 * @param[in] bufptr Pointer to the TX buffer 258 * @param[in] size Size of the transmission 259 * @param[in] callback Pointer to the function called back when transfer finished 260 * @param[in] dummy Dummy data pointer returned to callback when transmission is finished 261 ************************************************************************************* 262 */ 263 void (*write)(uint8_t *bufptr, uint32_t size, rwip_eif_callback callback, void* dummy); 264 265 /** 266 ************************************************************************************* 267 * @brief Enable Interface flow. 268 ************************************************************************************* 269 */ 270 void (*flow_on)(void); 271 272 /** 273 ************************************************************************************* 274 * @brief Disable Interface flow. 275 * 276 * @return True if flow has been disabled, False else. 277 ************************************************************************************* 278 */ 279 bool (*flow_off)(void); 280 }; 281 282 /* 283 * VARIABLE DECLARATION 284 ***************************************************************************************** 285 */ 286 287 /// API for RF driver 288 extern struct rwip_rf_api rwip_rf; 289 /// API for parameters 290 extern struct rwip_param_api rwip_param; 291 #if (BLE_EMB_PRESENT || BT_EMB_PRESENT) 292 /// API for dual mode priority 293 extern const struct rwip_prio rwip_priority[RWIP_PRIO_IDX_MAX]; 294 #endif //#if (BLE_EMB_PRESENT || BT_EMB_PRESENT) 295 296 #if (BT_EMB_PRESENT || BLE_EMB_PRESENT) 297 #if (RW_WLAN_COEX) 298 /// API for COEX configuration 299 extern const uint8_t rwip_coex_cfg[RWIP_COEX_CFG_MAX]; 300 #endif //(RW_WLAN_COEX) 301 #endif //(BT_EMB_PRESENT || BLE_EMB_PRESENT) 302 303 /* 304 * MACROS 305 **************************************************************************************** 306 */ 307 308 /// Get Event status flag 309 #if (BT_EMB_PRESENT || BLE_EMB_PRESENT) 310 #if (RW_WLAN_COEX) 311 #define RWIP_COEX_GET(coex_cfg_idx, bit_field) \ 312 (uint8_t)(((rwip_coex_cfg[RWIP_COEX_ ## coex_cfg_idx ##_IDX]) >> RWIP_ ## bit_field ## _POS ) & RWIP_COEX_BIT_MASK) 313 #else //(RW_WLAN_COEX) 314 #define RWIP_COEX_GET(coex_cfg_idx, bit_field) 0 315 #endif //(RW_WLAN_COEX) 316 #endif //(BT_EMB_PRESENT || BLE_EMB_PRESENT) 317 318 /* 319 * FUNCTION DECLARATION 320 ***************************************************************************************** 321 */ 322 323 /** 324 **************************************************************************************** 325 * @brief Initializes the RW BT SW. 326 * 327 **************************************************************************************** 328 */ 329 void rwip_init(uint32_t error); 330 331 /** 332 **************************************************************************************** 333 * @brief Reset the RW BT SW. 334 * 335 **************************************************************************************** 336 */ 337 void rwip_reset(void); 338 339 340 341 #if (BT_EMB_PRESENT) 342 343 #if PCA_SUPPORT 344 /** 345 **************************************************************************************** 346 * @brief Check if clock dragging limitation 347 * 348 * @return true if clock dragging must be used 349 **************************************************************************************** 350 */ 351 bool rwip_pca_clock_dragging_only(void); 352 #endif //PCA_SUPPORT 353 #endif // (BT_EMB_PRESENT) 354 355 #if (BT_EMB_PRESENT || BLE_EMB_PRESENT) 356 #if (RW_MWS_COEX) 357 /** 358 **************************************************************************************** 359 * @brief Enable/Disable the MWS coexistence interface. 360 * 361 * @param[in] CoexSetting Coexistence value 362 * 363 **************************************************************************************** 364 */ 365 //void rwip_mwscoex_set(bool state); 366 #endif //RW_MWS_COEX 367 368 #if (RW_WLAN_COEX) 369 /** 370 **************************************************************************************** 371 * @brief Enable/Disable the Wireless LAN coexistence interface. 372 * 373 * @param[in] CoexSetting Coexistence value 374 * 375 **************************************************************************************** 376 */ 377 //void rwip_wlcoex_set(bool state); 378 #endif //RW_WLAN_COEX 379 #endif //(BT_EMB_PRESENT || BLE_EMB_PRESENT) 380 381 /** 382 **************************************************************************************** 383 * @brief Function to implement in platform in order to retrieve expected external 384 * interface such as UART for Host Control Interface. 385 * 386 * @param[in] type external interface type (@see rwip_eif_types) 387 * 388 * @return External interface api structure 389 **************************************************************************************** 390 */ 391 extern const struct rwip_eif_api* rwip_eif_get(uint8_t type); 392 393 #if RW_DEBUG 394 /** 395 **************************************************************************************** 396 * @brief Raises an assertion message to the control interface (if present) 397 * 398 * @param[in] file File name 399 * @param[in] line Line number 400 * @param[in] param0 Parameter 0 (custom value given by the assert instruction) 401 * @param[in] param1 Parameter 1 (custom value given by the assert instruction) 402 **************************************************************************************** 403 */ 404 void rwip_assert_err(const char * file, int line, int param0, int param1); 405 #endif //RW_DEBUG 406 407 408 /* ************************************************************************************** 409 * Driver functions 410 * ************************************************************************************** 411 */ 412 413 /** 414 **************************************************************************************** 415 * @brief Retrieved sampled current time in half slot and next tick time in half us. 416 * 417 * @note Shall be called within a critical section 418 * 419 * @return current time sampled (@see rwip_time_t) 420 **************************************************************************************** 421 */ 422 rwip_time_t rwip_time_get(void); 423 424 425 /** 426 **************************************************************************************** 427 * @brief Set the a 10 ms target timer 428 * 429 * @note if target is RWIP_INVALID_TARGET_TIME, not timer are programmed 430 * 431 * @param[in] target 10ms Timer target value 432 **************************************************************************************** 433 */ 434 void rwip_timer_10ms_set(uint32_t target); 435 436 /** 437 **************************************************************************************** 438 * @brief Set the a half slot target timer 439 * 440 * @note if target is RWIP_INVALID_TARGET_TIME, not timer are programmed 441 * 442 * @param[in] target Half Slot Timer target value 443 **************************************************************************************** 444 */ 445 void rwip_timer_hs_set(uint32_t target); 446 447 /** 448 **************************************************************************************** 449 * @brief Gives FW/HW versions of RW-BT stack. 450 * 451 **************************************************************************************** 452 */ 453 //void rwip_version(uint8_t* fw_version, uint8_t* hw_version); 454 455 /** 456 **************************************************************************************** 457 * @brief Start AES encryption 458 * 459 * The exchange memory must be filled before calling this function. 460 * This function expect to be called from a BLE Module 461 * 462 * @param[in] key AES Encryption key must be 16 bytes 463 * @param[in] data_em_ptr Exchange memory data pointer of data to encrypt 464 **************************************************************************************** 465 */ 466 //void rwip_aes_encrypt(uint8_t *key, uint16_t data_em_ptr); 467 468 /** 469 **************************************************************************************** 470 * @brief Request a Software interrupt to be triggered 471 **************************************************************************************** 472 */ 473 //void rwip_sw_int_req(void); 474 475 /** 476 **************************************************************************************** 477 * @brief Schedule all pending events. 478 * 479 **************************************************************************************** 480 */ 481 //void rwip_schedule(void); 482 483 /** 484 **************************************************************************************** 485 * @brief Invoke the sleep function. 486 * 487 * @return sleep status (@see enum rwip_sleep_state) 488 **************************************************************************************** 489 */ 490 //uint8_t rwip_sleep(void); 491 492 /** 493 **************************************************************************************** 494 * @brief Handle the common core interrupts. 495 * 496 * @param[in] current IRQ status 497 **************************************************************************************** 498 */ 499 //void rwip_isr(uint32_t irq_stat); 500 501 /** 502 **************************************************************************************** 503 * @brief Set a bit in the prevent sleep bit field, in order to prevent the system from 504 * going to sleep 505 * 506 * @param[in] prv_slp_bit Bit to be set in the prevent sleep bit field 507 **************************************************************************************** 508 */ 509 //void rwip_prevent_sleep_set(uint16_t prv_slp_bit); 510 511 /** 512 **************************************************************************************** 513 * @brief Clears a bit in the prevent sleep bit field, in order to allow the system 514 * going to sleep 515 * 516 * @param[in] prv_slp_bit Bit to be cleared in the prevent sleep bit field 517 **************************************************************************************** 518 */ 519 //void rwip_prevent_sleep_clear(uint16_t prv_slp_bit); 520 521 ///@} ROOT 522 523 #endif // _RWIP_H_ 524