1 /* 2 * Copyright 2019-2023, Cypress Semiconductor Corporation or 3 * an affiliate of Cypress Semiconductor Corporation. All rights reserved. 4 * 5 * This software, including source code, documentation and related 6 * materials ("Software") is owned by Cypress Semiconductor Corporation 7 * or one of its affiliates ("Cypress") and is protected by and subject to 8 * worldwide patent protection (United States and foreign), 9 * United States copyright laws and international treaty provisions. 10 * Therefore, you may use this Software only as provided in the license 11 * agreement accompanying the software package from which you 12 * obtained this Software ("EULA"). 13 * If no EULA applies, Cypress hereby grants you a personal, non-exclusive, 14 * non-transferable license to copy, modify, and compile the Software 15 * source code solely for use in connection with Cypress's 16 * integrated circuit products. Any reproduction, modification, translation, 17 * compilation, or representation of this Software except as specified 18 * above is prohibited without the express written permission of Cypress. 19 * 20 * Disclaimer: THIS SOFTWARE IS PROVIDED AS-IS, WITH NO WARRANTY OF ANY KIND, 21 * EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, NONINFRINGEMENT, IMPLIED 22 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Cypress 23 * reserves the right to make changes to the Software without notice. Cypress 24 * does not assume any liability arising out of the application or use of the 25 * Software or any product or circuit described in the Software. Cypress does 26 * not authorize its products for use in any products where a malfunction or 27 * failure of the Cypress product may reasonably be expected to result in 28 * significant property damage, injury or death ("High Risk Product"). By 29 * including Cypress's product in a High Risk Product, the manufacturer 30 * of such system or application assumes all risk of such use and in doing 31 * so agrees to indemnify Cypress against all liability. 32 */ 33 /** @file 34 * 35 * Runtime Bluetooth configuration parameters 36 * 37 */ 38 /** 39 * @addtogroup wiced_bt_platform_group Bluetooth Stack Platform Interface 40 * 41 * Interface between Stack and platform. 42 * 43 * @{ 44 */ 45 46 #pragma once 47 48 #include <stdarg.h> 49 #include "wiced_bt_types.h" 50 #include "wiced_data_types.h" 51 #include "wiced_bt_cfg.h" 52 #include "wiced_bt_dev.h" 53 54 /** Wiced BT Stack Platform */ 55 typedef struct 56 { 57 /** 58 * Exception callback 59 */ 60 pf_wiced_exception pf_exception; 61 62 /** 63 * Platform function to allocate memory 64 * 65 * Called by stack code to allocate memory from the OS/Platform. 66 * Implementing function is expected to return memory allocated from 67 * the OS/Platform 68 * 69 * @param[in] size : Size of memory to be allocated 70 * 71 * @return : Pointer to allocated memory 72 */ 73 void * (*pf_os_malloc)(uint32_t size); 74 75 /** 76 * Platform memory free 77 * 78 * Called by stack code to free memory back to the OS/Platform. 79 * Implementing function is expected to free the memory allocated 80 * using pf_os_malloc (refer #pf_os_malloc ) call from the OS/Platform 81 * 82 * @param[in] p_mem : Ptr to memory to be freed 83 * 84 * @return : None 85 */ 86 void (*pf_os_free)(void* p_mem); 87 88 /** 89 * Platform function to get tick count 90 * 91 * Called by stack timer code to get the free running 64 bit tick count 92 * 93 * @param[in] None 94 * 95 * @return : 64 bit current tick count 96 */ 97 uint64_t (*pf_get_tick_count_64)(void); 98 99 /** 100 * Platform function to set the next timeout 101 * 102 * Called by stack timer code set the next timeout 103 * 104 * @param[in] abs_tick_count : 64 bit tick count instant at which the timeout has to occur 105 * 106 * @return : void 107 */ 108 void (*pf_set_next_timeout)(uint64_t abs_tick_count); 109 110 /** Stack lock */ 111 wiced_bt_lock_t stack_lock; 112 113 /** 114 * Platform function to get ACL buffer to send to lower 115 * 116 * Called by stack to get a buffer to fill in the data to be sent to 'transport' (BLE or BR/EDR) 117 * of 'size' 118 * 119 * @param[in] transport : Transport on which the buffer is to be sent 120 * @param[in] size : Size of the buffer 121 * 122 * @return : Pointer to buffer which will be filled with data 123 */ 124 uint8_t *(*pf_get_acl_to_lower_buffer)(wiced_bt_transport_t transport, uint32_t size); 125 126 /** 127 * Platform function to write ACL buffer to lower 128 * 129 * Called by stack to send the buffer allocated using pf_get_acl_to_lower_buffer 130 * after filling it with the data to send. 131 * 132 * @param[in] transport : Transport on which the buffer is to be sent 133 * @param[in] p_data : Pointer received using pf_get_acl_to_lower_buffer 134 * @param[in] len : Length of data at p_data 135 * 136 * @return : wiced_result_t 137 */ 138 wiced_result_t (*pf_write_acl_to_lower)(wiced_bt_transport_t transport, uint8_t* p_data, uint16_t len); 139 140 /** 141 * Platform function to write ISO buffer to lower 142 * 143 * Called by stack to send the buffer allocated using pf_get_acl_to_lower_buffer 144 * after filling it with the data to send. 145 * 146 * @param[in] p_data : Pointer received using pf_get_acl_to_lower_buffer 147 * @param[in] len : Length of data at p_data 148 * 149 * @return : wiced_result_t 150 */ 151 wiced_result_t (*pf_write_iso_to_lower)(uint8_t* p_data, uint16_t len); 152 153 /** 154 * Platform function to write CMD buffer to lower 155 * 156 * Called by stack to send HCI CMD buffer to lower 157 * 158 * @param[in] p_cmd : Pointer to HCI CMD data 159 * @param[in] cmd_len : Length of data at p_cmd 160 * 161 * @return : wiced_result_t 162 */ 163 wiced_result_t (*pf_write_cmd_to_lower)(uint8_t * p_cmd, uint16_t cmd_len); 164 165 /** 166 * Platform function to get SCO buffer to send to lower 167 * 168 * Called by stack to get a SCO buffer to fill in the data to be sent to HCI 169 * of 'size' 170 * 171 * @param[in] size : Size of the buffer 172 * 173 * @return : Pointer to buffer which will be filled with data 174 */ 175 uint8_t *(*pf_get_sco_to_lower_buffer)(uint32_t size); 176 177 /** 178 * Platform function to write SCO buffer to lower 179 * 180 * Called to send SCO CMD buffer to lower 181 * 182 * @param[in] p_sco_data : Pointer to SCO data 183 * @param[in] len : Length of data at p_data 184 * 185 * @return : wiced_result_t 186 */ 187 wiced_result_t (*pf_write_sco_to_lower)(uint8_t* p_sco_data, uint8_t len); 188 189 /** 190 * Callback function to trace HCI messages 191 * 192 * Called by stack to allow application to trace the HCI messages. 193 * Application/Porting code is expected to treat received data as read only, and make a 194 * copy of the data to reference it outside of the callback 195 * 196 * @param[in] type : HCI event data type 197 * @param[in] len : Length of data at p_data 198 * @param[in] p_data : Pointer to data 199 * 200 * @return : void 201 */ 202 void (*pf_hci_trace_cback_t)(wiced_bt_hci_trace_type_t type, uint16_t len, uint8_t* p_data); 203 204 /** 205 * Callback function to dump out trace messages 206 * This interface function can be NULL if no debug tracing is supported 207 * 208 * Called by stack to allow application to write debug trace messages 209 * 210 * @param[in] p_trace_buf : Pointer to the trace buffer 211 * @param[in] trace_buf_len : Length of the trace buffer 212 * @param[in] trace_type : Type of trace message 213 * 214 * @return : void 215 */ 216 void (*pf_debug_trace)(char *p_trace_buf, int trace_buf_len, wiced_bt_trace_type_t trace_type); 217 218 /** trace_buffer_len : Trace buffer len */ 219 int trace_buffer_len; 220 /** 221 * trace_buffer : Pointer to the trace buffer 222 * Applications can set this to NULL to disable traces 223 */ 224 char* trace_buffer; 225 226 227 /** 228 * Used for additional controller initialization by the porting layer to be performed 229 * after the HCI reset. Can be set to NULL if no additional initialization required 230 */ 231 void (*pf_patch_download)(void); 232 233 /** 234 *set is_legacy_bless_controller to 1 for only BLESS controllers. 235 *This is used while sending BLESS vendor specific commands. 236 */ 237 uint32_t is_legacy_bless_controller : 1; 238 } wiced_bt_stack_platform_t; 239 240 /** 241 * Initialize the platform interfaces, by providing porting functions specific to 242 * the underlying platform. 243 * 244 * @return <b> WICED_BT_SUCCESS </b> : on success; \n 245 * <b> WICED_BT_ERROR </b> : if an error occurred 246 */ 247 extern wiced_result_t wiced_bt_stack_platform_initialize(wiced_bt_stack_platform_t * platform_interfaces); 248 249 /** 250 * Called by the porting layer to process the incoming ACL data received from the 251 * remote bluetooth device 252 * 253 * @param[in] pData : Pointer to the ACL data to be processed 254 * @param[in] length : Length of the ACL data buffer 255 * 256 * @return void 257 */ 258 extern void wiced_bt_process_acl_data(uint8_t* pData, uint32_t length); 259 260 /** 261 * Called by the porting layer to process the incoming HCI events from the local 262 * bluetooth controller 263 * 264 * @param[in] pData : Pointer to the HCI Events to be processed 265 * @param[in] length : Length of the event buffer 266 * @return void 267 */ 268 extern void wiced_bt_process_hci_events(uint8_t* pData, uint32_t length); 269 270 /** 271 * Called by the porting layer to process the incoming SCO data received from the 272 * remote bluetooth device 273 * 274 * @param[in] pData : Pointer to the SCO data to be processed 275 * @param[in] length : Length of the SCO data buffer 276 * @return void 277 */ 278 279 extern void wiced_bt_process_sco_data(uint8_t *pData, uint32_t length); 280 281 /** 282 * Called by the porting layer to process the incoming ISOC data received from the 283 * remote bluetooth device 284 * 285 * @param[in] pData : Pointer to the ISOC data to be processed 286 * @param[in] length : Length of the ISOC data buffer 287 * @return void 288 */ 289 void wiced_bt_process_isoc_data(uint8_t *pData, uint32_t length); 290 291 /** 292 * Called by the porting layer on expiry of the timer to process pending timers 293 * 294 * @return void 295 */ 296 extern void wiced_bt_process_timer(void); 297 298 299 /** 300 * Called by the lower layer transport driver to restart sending ACL data to the controller 301 * Note: Porting layer API. 302 * This API is expected to be invoked by the lower layer transport driver, to restart 303 * transfers from the stack to the controller. 304 * The lower tx layer is expected to have space for atleast one complete ACL buffer 305 * Typically used in cases where the lower Tx has lesser number of buffers than allowed by controller 306 */ 307 extern void wiced_bt_stack_indicate_lower_tx_complete(void); 308 309 /** 310 * Called by the porting layer to complete/continue the reset process 311 * Typically called after downloading firmware patches to the controller 312 * 313 * @return void 314 */ 315 extern void wiced_bt_continue_reset(void); 316 317 /** 318 * Set the stack config. Invoked by the porting layer 319 * 320 * @param[in] p_bt_new_cfg_settings : Stack configuration settings 321 * 322 * @return 0 if there is any error in the configuration otherwise the dynamic 323 * memory size requirements of the stack for the configuration. 324 * 325 * 326 */ 327 extern uint32_t wiced_bt_set_stack_config(const wiced_bt_cfg_settings_t* p_bt_new_cfg_settings); 328 329 /** 330 * Function prototype for the post Stack Init Callback. 331 */ 332 typedef void (*wiced_bt_internal_post_stack_init_cb)(void); 333 334 335 /** 336 * Function prototype for the HCI event monitor function that the application may suppply. 337 * The application MUST return TRUE if the it handled the event and does not want the stack to 338 * process the event. If the application returns FALSE, the stack will process the event. 339 */ 340 typedef wiced_bool_t (*wiced_bt_internal_stack_evt_handler_cb)(uint8_t* p_event); 341 342 /** 343 * Internal stack init 344 * 345 * @param[in] mgmt_cback : Application BT Management callback 346 * @param[in] post_stack_cb : Internal post stack init callback 347 * @param[in] evt_handler_cb : Internal stack event handler 348 * 349 * @return Dynamic memory size requirements of the stack for the configuration 350 * 351 */ 352 void wiced_bt_stack_init_internal(wiced_bt_management_cback_t mgmt_cback, 353 wiced_bt_internal_post_stack_init_cb post_stack_cb, 354 wiced_bt_internal_stack_evt_handler_cb evt_handler_cb); 355 356 /** 357 * This function blocks until all de-initialisation procedures are complete. 358 * It is recommended that the application disconnect any outstanding connections prior to invoking this function. 359 * 360 * @return None 361 */ 362 void wiced_bt_stack_shutdown(void); 363 364 /**@} wiced_bt_platform_group */ 365
