1 /** 2 **************************************************************************************** 3 * 4 * @file rwip.h 5 * 6 * @brief RW IP SW main module 7 * 8 * Copyright (C) RivieraWaves 2009-2015 9 * 10 * 11 **************************************************************************************** 12 */ 13 #ifndef _RWIP_H_ 14 #define _RWIP_H_ 15 16 /** 17 **************************************************************************************** 18 * @addtogroup ROOT 19 * @brief Entry points of the RW IP stacks/modules 20 * 21 * This module contains the primitives that allow an application accessing and running the 22 * RW IP protocol stacks / modules. 23 * 24 * @{ 25 **************************************************************************************** 26 */ 27 28 #include "rwip_config.h" // stack configuration 29 30 #include <stdint.h> // standard integer definitions 31 #include <stdbool.h> // standard boolean definitions 32 33 /// retrieve 10ms time according to clock time 34 #define RWIP_CLOCK_TO_10MS_TIME(clock) ((clock) >> 4) 35 /// retrieve clock time according to 10ms time 36 #define RWIP_10MS_TIME_TO_CLOCK(time) ((time) << 4) 37 /// Invalid target time 38 #define RWIP_INVALID_TARGET_TIME (0xFFFFFFFFL) 39 40 #if (DEEP_SLEEP) 41 /// Definition of the bits preventing the system from sleeping 42 enum prevent_sleep 43 { 44 /// Flag indicating that the wake up process is ongoing 45 RW_WAKE_UP_ONGOING = 0x0001, 46 /// Flag indicating that an TX transfer is ongoing on Transport Layer 47 RW_TL_TX_ONGOING = 0x0002, 48 /// Flag indicating that an RX transfer is ongoing on Transport Layer 49 RW_TL_RX_ONGOING = 0x0004, 50 /// Flag indicating HCI timeout is ongoing 51 RW_AHI_TIMEOUT = 0x0008, 52 /// Flag indicating that an encryption is ongoing 53 RW_CRYPT_ONGOING = 0x0010, 54 /// Flag indicating that a element deletion is on going 55 RW_DELETE_ELT_ONGOING = 0x0020, 56 /// Flag indicating that controller shall not sleep due to not CSB LPO_Allowed 57 RW_CSB_NOT_LPO_ALLOWED = 0x0040, 58 /// Flag indicating the MWS/WLAN Event Generator is in operation 59 RW_MWS_WLAN_EVENT_GENERATOR_ACTIVE = 0x0080 60 }; 61 #endif //DEEP_SLEEP 62 63 64 65 /** 66 * External interface type types. 67 */ 68 enum rwip_eif_types 69 { 70 /// Host Controller Interface - Controller part 71 RWIP_EIF_HCIC, 72 73 /// Host Controller Interface - Host part 74 RWIP_EIF_HCIH, 75 76 /// Application Host interface 77 RWIP_EIF_AHI, 78 }; 79 80 81 /// Enumeration of External Interface status codes 82 enum rwip_eif_status 83 { 84 /// EIF status OK 85 RWIP_EIF_STATUS_OK, 86 /// EIF status KO 87 RWIP_EIF_STATUS_ERROR, 88 89 #if (BLE_EMB_PRESENT == 0) 90 /// External interface detached 91 RWIP_EIF_STATUS_DETACHED, 92 /// External interface attached 93 RWIP_EIF_STATUS_ATTACHED, 94 #endif // (BLE_EMB_PRESENT == 0) 95 }; 96 97 /// Enumeration of RF modulations 98 enum rwip_rf_mod 99 { 100 MOD_GFSK = 0x01, 101 MOD_DQPSK = 0x02, 102 MOD_8DPSK = 0x03, 103 }; 104 105 /// API functions of the RF driver that are used by the BLE or BT software 106 struct rwip_rf_api 107 { 108 /// Function called upon HCI reset command reception 109 void (*reset)(void); 110 /// Function called to enable/disable force AGC mechanism (true: en / false : dis) 111 void (*force_agc_enable)(bool); 112 /// Function called when TX power has to be decreased for a specific link id 113 bool (*txpwr_dec)(uint8_t); 114 /// Function called when TX power has to be increased for a specific link id 115 bool (*txpwr_inc)(uint8_t); 116 /// Function called when TX power has to be set to max for a specific link id 117 void (*txpwr_max_set)(uint8_t); 118 /// Function called to convert a TX power CS power field into the corresponding value in dBm 119 uint8_t (*txpwr_dbm_get)(uint8_t, uint8_t); 120 /// Function called to convert a power in dBm into a control structure tx power field 121 uint8_t (*txpwr_cs_get)(int8_t); 122 /// Function called to convert the RSSI read from the control structure into a real RSSI 123 int8_t (*rssi_convert)(uint8_t); 124 /// Function used to read a RF register 125 uint32_t (*reg_rd)(uint16_t); 126 /// Function used to write a RF register 127 void (*reg_wr)(uint16_t, uint32_t); 128 /// Function called to put the RF in deep sleep mode 129 void (*sleep)(void); 130 /// Index of maximum TX power 131 uint8_t txpwr_max; 132 /// RSSI high threshold ('real' signed value in dBm) 133 int8_t rssi_high_thr; 134 /// RSSI low threshold ('real' signed value in dBm) 135 int8_t rssi_low_thr; 136 /// interferer threshold ('real' signed value in dBm) 137 int8_t rssi_interf_thr; 138 /// RF wakeup delay (in slots) 139 uint8_t wakeup_delay; 140 }; 141 142 /// Internal API for priority 143 struct rwip_prio 144 { 145 ///value 146 uint8_t value; 147 ///Increment 148 uint8_t increment; 149 }; 150 151 /// Internal API for COEX 152 struct rwip_coex 153 { 154 ///Coexistence control field 155 uint8_t coex_cntl; 156 }; 157 158 159 /** 160 **************************************************************************************** 161 * @brief Function called when packet transmission/reception is finished. 162 163 * @param[in] dummy Dummy data pointer returned to callback when operation is over. 164 * @param[in] status Ok if action correctly performed, else reason status code. 165 ***************************************************************************************** 166 */ 167 typedef void (*rwip_eif_callback) (void*, uint8_t); 168 169 /** 170 * Transport layer communication interface. 171 */ 172 struct rwip_eif_api 173 { 174 /** 175 ************************************************************************************* 176 * @brief Starts a data reception. 177 * 178 * @param[out] bufptr Pointer to the RX buffer 179 * @param[in] size Size of the expected reception 180 * @param[in] callback Pointer to the function called back when transfer finished 181 * @param[in] dummy Dummy data pointer returned to callback when reception is finished 182 ************************************************************************************* 183 */ 184 void (*read) (uint8_t *bufptr, uint32_t size, rwip_eif_callback callback, void* dummy); 185 186 /** 187 ************************************************************************************* 188 * @brief Starts a data transmission. 189 * 190 * @param[in] bufptr Pointer to the TX buffer 191 * @param[in] size Size of the transmission 192 * @param[in] callback Pointer to the function called back when transfer finished 193 * @param[in] dummy Dummy data pointer returned to callback when transmission is finished 194 ************************************************************************************* 195 */ 196 void (*write)(uint8_t *bufptr, uint32_t size, rwip_eif_callback callback, void* dummy); 197 198 /** 199 ************************************************************************************* 200 * @brief Enable Interface flow. 201 ************************************************************************************* 202 */ 203 void (*flow_on)(void); 204 205 /** 206 ************************************************************************************* 207 * @brief Disable Interface flow. 208 * 209 * @return True if flow has been disabled, False else. 210 ************************************************************************************* 211 */ 212 bool (*flow_off)(void); 213 }; 214 215 /* 216 * VARIABLE DECLARATION 217 ***************************************************************************************** 218 */ 219 220 /// API for RF driver 221 extern struct rwip_rf_api rwip_rf; 222 #if (BLE_EMB_PRESENT || BT_EMB_PRESENT) 223 /// API for dual mode priority 224 extern const struct rwip_prio rwip_priority[RWIP_PRIO_IDX_MAX]; 225 /// API for COEX 226 extern const uint8_t rwip_coex_cfg[RWIP_COEX_CFG_MAX]; 227 #endif //#if (BLE_EMB_PRESENT || BT_EMB_PRESENT) 228 229 /* 230 * MACROS 231 **************************************************************************************** 232 */ 233 234 /// Get Event status flag 235 #define RWIP_COEX_GET(coex_cfg_idx, bit_field) \ 236 (uint8_t)(((rwip_coex_cfg[RWIP_COEX_ ## coex_cfg_idx ##_IDX]) >> RWIP_ ## bit_field ## _POS ) & RWIP_COEX_BIT_MASK) 237 238 /* 239 * FUNCTION DECLARATION 240 ***************************************************************************************** 241 */ 242 243 /** 244 **************************************************************************************** 245 * @brief Initializes the RW BT SW. 246 * 247 **************************************************************************************** 248 */ 249 void rwip_init(uint32_t error); 250 251 /** 252 **************************************************************************************** 253 * @brief Reset the RW BT SW. 254 * 255 **************************************************************************************** 256 */ 257 void rwip_reset(void); 258 259 /** 260 **************************************************************************************** 261 * @brief Gives FW/HW versions of RW-BT stack. 262 * 263 **************************************************************************************** 264 */ 265 void rwip_version(uint8_t* fw_version, uint8_t* hw_version); 266 267 /** 268 **************************************************************************************** 269 * @brief Schedule all pending events. 270 * 271 **************************************************************************************** 272 */ 273 void rwip_schedule(void); 274 275 /** 276 **************************************************************************************** 277 * @brief Invoke the sleep function. 278 * 279 * @return true: processor sleep allowed, false otherwise 280 **************************************************************************************** 281 */ 282 bool rwip_sleep(void); 283 284 #if DEEP_SLEEP 285 /** 286 **************************************************************************************** 287 * @brief Handle wake-up. 288 **************************************************************************************** 289 */ 290 void rwip_wakeup(void); 291 292 /** 293 **************************************************************************************** 294 * @brief Handle end of wake-up. 295 **************************************************************************************** 296 */ 297 void rwip_wakeup_end(void); 298 299 /** 300 **************************************************************************************** 301 * @brief Set the wake-up delay 302 * 303 * @param[in] wakeup_delay Wake-up delay in us 304 **************************************************************************************** 305 */ 306 void rwip_wakeup_delay_set(uint16_t wakeup_delay); 307 308 /** 309 **************************************************************************************** 310 * @brief Set a bit in the prevent sleep bit field, in order to prevent the system from 311 * going to sleep 312 * 313 * @param[in] prv_slp_bit Bit to be set in the prevent sleep bit field 314 **************************************************************************************** 315 */ 316 void rwip_prevent_sleep_set(uint16_t prv_slp_bit); 317 318 /** 319 **************************************************************************************** 320 * @brief Clears a bit in the prevent sleep bit field, in order to allow the system 321 * going to sleep 322 * 323 * @param[in] prv_slp_bit Bit to be cleared in the prevent sleep bit field 324 **************************************************************************************** 325 */ 326 void rwip_prevent_sleep_clear(uint16_t prv_slp_bit); 327 328 /** 329 **************************************************************************************** 330 * @brief Check if sleep mode is enable 331 * 332 * @return true if sleep is enable, false otherwise 333 **************************************************************************************** 334 */ 335 bool rwip_sleep_enable(void); 336 337 /** 338 **************************************************************************************** 339 * @brief Check if external wake-up is enable 340 * 341 * @return true if external wakeup is enable, false otherwise 342 **************************************************************************************** 343 */ 344 bool rwip_ext_wakeup_enable(void); 345 346 /** 347 **************************************************************************************** 348 * @brief Converts a duration in lp cycles into a duration is us. 349 * 350 * The function converts a duration in lp cycles into a duration is us, according to the 351 * low power clock frequency (32768Hz or 32000Hz). 352 * 353 * To do this the following formulae are applied: 354 * 355 * Tus = x*30.517578125 = 30*x + x/2 + x/64 + x/512 for a 32.768kHz clock or 356 * Tus = x*31.25 = 31*x + x/4 for a 32kHz clock 357 * 358 * @note This function is also performing a compensation of accumulated drift created by 359 * rounding present in the algorithm 360 * 361 * @param[in] lpcycles duration in lp cycles 362 * 363 * @return duration in us 364 **************************************************************************************** 365 */ 366 uint32_t rwip_sleep_lpcycles_2_us(uint32_t lpcycles); 367 368 369 /** 370 **************************************************************************************** 371 * @brief Converts a duration in us into a duration in lp cycles. 372 * 373 * The function converts a duration in us into a duration is lp cycles, according to the 374 * low power clock frequency (32768Hz or 32000Hz). 375 * 376 * @param[in] us duration in us 377 * 378 * @return duration in lpcycles 379 **************************************************************************************** 380 */ 381 uint32_t rwip_us_2_lpcycles(uint32_t us); 382 #endif // DEEP_SLEEP 383 384 #if (BT_EMB_PRESENT) 385 386 #if PCA_SUPPORT 387 /** 388 **************************************************************************************** 389 * @brief Check if clock dragging limitation 390 * 391 * @return true if clock dragging must be used 392 **************************************************************************************** 393 */ 394 bool rwip_pca_clock_dragging_only(void); 395 #endif //PCA_SUPPORT 396 397 /** 398 **************************************************************************************** 399 * @brief Set current time 400 * 401 * @param clock value in half-slots 402 **************************************************************************************** 403 */ 404 void rwip_time_set(uint32_t clock); 405 #endif // (BT_EMB_PRESENT) 406 407 #if (BT_EMB_PRESENT || BLE_EMB_PRESENT) 408 #if (RW_MWS_COEX) 409 /** 410 **************************************************************************************** 411 * @brief Enable/Disable the MWS coexistence interface. 412 * 413 * @param[in] CoexSetting Coexistence value 414 * 415 **************************************************************************************** 416 */ 417 void rwip_mwscoex_set(bool state); 418 #endif //RW_MWS_COEX 419 420 #if (RW_WLAN_COEX) 421 /** 422 **************************************************************************************** 423 * @brief Enable/Disable the Wireless LAN coexistence interface. 424 * 425 * @param[in] CoexSetting Coexistence value 426 * 427 **************************************************************************************** 428 */ 429 void rwip_wlcoex_set(bool state); 430 #endif //RW_WLAN_COEX 431 #endif //(BT_EMB_PRESENT || BLE_EMB_PRESENT) 432 433 /** 434 **************************************************************************************** 435 * @brief Function to implement in platform in order to retrieve expected external 436 * interface such as UART for Host Control Interface. 437 * 438 * @param[in] type external interface type (@see rwip_eif_types) 439 * 440 * @return External interface api structure 441 **************************************************************************************** 442 */ 443 444 extern const struct rwip_eif_api spi_api; 445 446 extern const struct rwip_eif_api uart_api; 447 448 449 450 451 ///@} ROOT 452 453 #endif // _RWIP_H_ 454