1 /****************************************************************************** 2 * 3 * Copyright (C) 2009-2012 Broadcom Corporation 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at: 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 ******************************************************************************/ 18 19 #ifndef BT_VENDOR_LIB_H 20 #define BT_VENDOR_LIB_H 21 22 #include <stdint.h> 23 #include <sys/cdefs.h> 24 #include <sys/types.h> 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 /** Struct types */ 31 32 /** Typedefs and defines */ 33 34 /** Vendor specific operations OPCODE */ 35 typedef enum { 36 /* [operation] 37 * Power on or off the BT Controller. 38 * [input param] 39 * A pointer to int type with content of bt_vendor_power_state_t. 40 * Typecasting conversion: (int *) param. 41 * [return] 42 * 0 - default, don't care. 43 * [callback] 44 * None. 45 */ 46 BT_VND_OP_POWER_CTRL, 47 48 /* [operation] 49 * Perform any vendor specific initialization or configuration 50 * on the BT Controller. This is called before stack initialization. 51 * [input param] 52 * None. 53 * [return] 54 * 0 - default, don't care. 55 * [callback] 56 * Must call fwcfg_cb to notify the stack of the completion of vendor 57 * specific initialization once it has been done. 58 */ 59 BT_VND_OP_FW_CFG, 60 61 /* [operation] 62 * Perform any vendor specific SCO/PCM configuration on the BT 63 * Controller. 64 * This is called after stack initialization. 65 * [input param] 66 * None. 67 * [return] 68 * 0 - default, don't care. 69 * [callback] 70 * Must call scocfg_cb to notify the stack of the completion of vendor 71 * specific SCO configuration once it has been done. 72 */ 73 BT_VND_OP_SCO_CFG, 74 75 /* [operation] 76 * Open UART port on where the BT Controller is attached. 77 * This is called before stack initialization. 78 * [input param] 79 * A pointer to int array type for open file descriptors. 80 * The mapping of HCI channel to fd slot in the int array is given in 81 * bt_vendor_hci_channels_t. 82 * And, it requires the vendor lib to fill up the content before 83 * returning 84 * the call. 85 * Typecasting conversion: (int (*)[]) param. 86 * [return] 87 * Numbers of opened file descriptors. 88 * Valid number: 89 * 1 - CMD/EVT/ACL-In/ACL-Out via the same fd (e.g. UART) 90 * 2 - CMD/EVT on one fd, and ACL-In/ACL-Out on the other fd 91 * 4 - CMD, EVT, ACL-In, ACL-Out are on their individual fd 92 * [callback] 93 * None. 94 */ 95 BT_VND_OP_USERIAL_OPEN, 96 97 /* [operation] 98 * Close the previously opened UART port. 99 * [input param] 100 * None. 101 * [return] 102 * 0 - default, don't care. 103 * [callback] 104 * None. 105 */ 106 BT_VND_OP_USERIAL_CLOSE, 107 108 /* [operation] 109 * Get the LPM idle timeout in milliseconds. 110 * The stack uses this information to launch a timer delay before it 111 * attempts to de-assert LPM WAKE signal once downstream HCI packet 112 * has been delivered. 113 * [input param] 114 * A pointer to uint32_t type which is passed in by the stack. And, it 115 * requires the vendor lib to fill up the content before returning 116 * the call. 117 * Typecasting conversion: (uint32_t *) param. 118 * [return] 119 * 0 - default, don't care. 120 * [callback] 121 * None. 122 */ 123 BT_VND_OP_GET_LPM_IDLE_TIMEOUT, 124 125 /* [operation] 126 * Enable or disable LPM mode on BT Controller. 127 * [input param] 128 * A pointer to uint8_t type with content of bt_vendor_lpm_mode_t. 129 * Typecasting conversion: (uint8_t *) param. 130 * [return] 131 * 0 - default, don't care. 132 * [callback] 133 * Must call lpm_cb to notify the stack of the completion of LPM 134 * disable/enable process once it has been done. 135 */ 136 BT_VND_OP_LPM_SET_MODE, 137 138 /* [operation] 139 * Assert or Deassert LPM WAKE on BT Controller. 140 * [input param] 141 * A pointer to uint8_t type with content of bt_vendor_lpm_wake_state_t. 142 * Typecasting conversion: (uint8_t *) param. 143 * [return] 144 * 0 - default, don't care. 145 * [callback] 146 * None. 147 */ 148 BT_VND_OP_LPM_WAKE_SET_STATE, 149 150 /* [operation] 151 * Perform any vendor specific commands related to audio state changes. 152 * [input param] 153 * a pointer to bt_vendor_op_audio_state_t indicating what audio state is 154 * set. 155 * [return] 156 * 0 - default, don't care. 157 * [callback] 158 * None. 159 */ 160 BT_VND_OP_SET_AUDIO_STATE, 161 162 /* [operation] 163 * The epilog call to the vendor module so that it can perform any 164 * vendor-specific processes (e.g. send a HCI_RESET to BT Controller) 165 * before the caller calls for cleanup(). 166 * [input param] 167 * None. 168 * [return] 169 * 0 - default, don't care. 170 * [callback] 171 * Must call epilog_cb to notify the stack of the completion of vendor 172 * specific epilog process once it has been done. 173 */ 174 BT_VND_OP_EPILOG, 175 176 /* [operation] 177 * Call to the vendor module so that it can perform all vendor-specific 178 * operations to start offloading a2dp media encode & tx. 179 * [input param] 180 * pointer to bt_vendor_op_a2dp_offload_start_t containing elements 181 * required for VND FW to setup a2dp offload. 182 * [return] 183 * 0 - default, dont care. 184 * [callback] 185 * Must call a2dp_offload_start_cb to notify the stack of the 186 * completion of vendor specific setup process once it has been done. 187 */ 188 BT_VND_OP_A2DP_OFFLOAD_START, 189 190 /* [operation] 191 * Call to the vendor module so that it can perform all vendor-specific 192 * operations to suspend offloading a2dp media encode & tx. 193 * [input param] 194 * pointer to bt_vendor_op_a2dp_offload_t containing elements 195 * required for VND FW to setup a2dp offload. 196 * [return] 197 * 0 - default, dont care. 198 * [callback] 199 * Must call a2dp_offload_cb to notify the stack of the 200 * completion of vendor specific setup process once it has been done. 201 */ 202 BT_VND_OP_A2DP_OFFLOAD_STOP, 203 204 } bt_vendor_opcode_t; 205 206 /** Power on/off control states */ 207 typedef enum { 208 BT_VND_PWR_OFF, 209 BT_VND_PWR_ON, 210 } bt_vendor_power_state_t; 211 212 /** Define HCI channel identifier in the file descriptors array 213 used in BT_VND_OP_USERIAL_OPEN operation. 214 */ 215 typedef enum { 216 CH_CMD, // HCI Command channel 217 CH_EVT, // HCI Event channel 218 CH_ACL_OUT, // HCI ACL downstream channel 219 CH_ACL_IN, // HCI ACL upstream channel 220 221 CH_MAX // Total channels 222 } bt_vendor_hci_channels_t; 223 224 /** LPM disable/enable request */ 225 typedef enum { 226 BT_VND_LPM_DISABLE, 227 BT_VND_LPM_ENABLE, 228 } bt_vendor_lpm_mode_t; 229 230 /** LPM WAKE set state request */ 231 typedef enum { 232 BT_VND_LPM_WAKE_ASSERT, 233 BT_VND_LPM_WAKE_DEASSERT, 234 } bt_vendor_lpm_wake_state_t; 235 236 /** Callback result values */ 237 typedef enum { 238 BT_VND_OP_RESULT_SUCCESS, 239 BT_VND_OP_RESULT_FAIL, 240 } bt_vendor_op_result_t; 241 242 /** audio (SCO) state changes triggering VS commands for configuration */ 243 typedef struct { 244 uint16_t handle; 245 uint16_t peer_codec; 246 uint16_t state; 247 } bt_vendor_op_audio_state_t; 248 249 /* 250 * Bluetooth Host/Controller Vendor callback structure. 251 */ 252 253 /* vendor initialization/configuration callback */ 254 typedef void (*cfg_result_cb)(bt_vendor_op_result_t result); 255 256 /* datapath buffer allocation callback (callout) 257 * 258 * Vendor lib needs to request a buffer through the alloc callout function 259 * from HCI lib if the buffer is for constructing a HCI Command packet which 260 * will be sent through xmit_cb to BT Controller. 261 * 262 * For each buffer allocation, the requested size needs to be big enough to 263 * accommodate the below header plus a complete HCI packet -- 264 * typedef struct 265 * { 266 * uint16_t event; 267 * uint16_t len; 268 * uint16_t offset; 269 * uint16_t layer_specific; 270 * } HC_BT_HDR; 271 * 272 * HCI lib returns a pointer to the buffer where Vendor lib should use to 273 * construct a HCI command packet as below format: 274 * 275 * -------------------------------------------- 276 * | HC_BT_HDR | HCI command | 277 * -------------------------------------------- 278 * where 279 * HC_BT_HDR.event = 0x2000; 280 * HC_BT_HDR.len = Length of HCI command; 281 * HC_BT_HDR.offset = 0; 282 * HC_BT_HDR.layer_specific = 0; 283 * 284 * For example, a HCI_RESET Command will be formed as 285 * ------------------------ 286 * | HC_BT_HDR |03|0c|00| 287 * ------------------------ 288 * with 289 * HC_BT_HDR.event = 0x2000; 290 * HC_BT_HDR.len = 3; 291 * HC_BT_HDR.offset = 0; 292 * HC_BT_HDR.layer_specific = 0; 293 */ 294 typedef void* (*malloc_cb)(int size); 295 296 /* datapath buffer deallocation callback (callout) */ 297 typedef void (*mdealloc_cb)(void* p_buf); 298 299 /* define callback of the cmd_xmit_cb 300 * 301 * The callback function which HCI lib will call with the return of command 302 * complete packet. Vendor lib is responsible for releasing the buffer passed 303 * in at the p_mem parameter by calling dealloc callout function. 304 */ 305 typedef void (*tINT_CMD_CBACK)(void* p_mem); 306 307 /* hci command packet transmit callback (callout) 308 * 309 * Vendor lib calls xmit_cb callout function in order to send a HCI Command 310 * packet to BT Controller. The buffer carrying HCI Command packet content 311 * needs to be first allocated through the alloc callout function. 312 * HCI lib will release the buffer for Vendor lib once it has delivered the 313 * packet content to BT Controller. 314 * 315 * Vendor lib needs also provide a callback function (p_cback) which HCI lib 316 * will call with the return of command complete packet. 317 * 318 * The opcode parameter gives the HCI OpCode (combination of OGF and OCF) of 319 * HCI Command packet. For example, opcode = 0x0c03 for the HCI_RESET command 320 * packet. 321 */ 322 typedef uint8_t (*cmd_xmit_cb)(uint16_t opcode, void* p_buf, 323 tINT_CMD_CBACK p_cback); 324 325 typedef void (*cfg_a2dp_cb)(bt_vendor_op_result_t result, bt_vendor_opcode_t op, 326 uint8_t bta_av_handle); 327 328 typedef struct { 329 /** set to sizeof(bt_vendor_callbacks_t) */ 330 size_t size; 331 332 /* 333 * Callback and callout functions have implemented in HCI libray 334 * (libbt-hci.so). 335 */ 336 337 /* notifies caller result of firmware configuration request */ 338 cfg_result_cb fwcfg_cb; 339 340 /* notifies caller result of sco configuration request */ 341 cfg_result_cb scocfg_cb; 342 343 /* notifies caller result of lpm enable/disable */ 344 cfg_result_cb lpm_cb; 345 346 /* notifies the result of codec setting */ 347 cfg_result_cb audio_state_cb; 348 349 /* buffer allocation request */ 350 malloc_cb alloc; 351 352 /* buffer deallocation request */ 353 mdealloc_cb dealloc; 354 355 /* hci command packet transmit request */ 356 cmd_xmit_cb xmit_cb; 357 358 /* notifies caller completion of epilog process */ 359 cfg_result_cb epilog_cb; 360 361 /* notifies status of a2dp offload cmd's */ 362 cfg_a2dp_cb a2dp_offload_cb; 363 } bt_vendor_callbacks_t; 364 365 /** A2DP offload request */ 366 typedef struct { 367 uint8_t bta_av_handle; /* BTA_AV Handle for callbacks */ 368 uint16_t xmit_quota; /* Total ACL quota for light stack */ 369 uint16_t acl_data_size; /* Max ACL data size across HCI transport */ 370 uint16_t stream_mtu; 371 uint16_t local_cid; 372 uint16_t remote_cid; 373 uint16_t lm_handle; 374 uint8_t is_flushable; /* true if flushable channel */ 375 uint32_t stream_source; 376 uint8_t codec_info[10]; /* Codec capabilities array */ 377 } bt_vendor_op_a2dp_offload_t; 378 379 /* 380 * Bluetooth Host/Controller VENDOR Interface 381 */ 382 typedef struct { 383 /** Set to sizeof(bt_vndor_interface_t) */ 384 size_t size; 385 386 /* 387 * Functions need to be implemented in Vendor libray (libbt-vendor.so). 388 */ 389 390 /** 391 * Caller will open the interface and pass in the callback routines 392 * to the implemenation of this interface. 393 */ 394 int (*init)(const bt_vendor_callbacks_t* p_cb, unsigned char* local_bdaddr); 395 396 /** Vendor specific operations */ 397 int (*op)(bt_vendor_opcode_t opcode, void* param); 398 399 /** Closes the interface */ 400 void (*cleanup)(void); 401 } bt_vendor_interface_t; 402 403 /* 404 * External shared lib functions/data 405 */ 406 407 /* Entry point of DLib -- 408 * Vendor library needs to implement the body of bt_vendor_interface_t 409 * structure and uses the below name as the variable name. HCI library 410 * will use this symbol name to get address of the object through the 411 * dlsym call. 412 */ 413 extern const bt_vendor_interface_t BLUETOOTH_VENDOR_LIB_INTERFACE; 414 415 // MODIFICATION FOR NEW HAL/HIDL IMPLEMENTATION: 416 // EXPOSE THE BT_HDR STRUCT HERE FOR THE VENDOR INTERFACE 417 // ONLY, WITHOUT REQUIRING INCLUDES FROM system/bt OR OTHER 418 // DIRECTORIES. 419 // ONLY USED INSIDE transmit_cb. 420 // DO NOT USE IN NEW HAL IMPLEMENTATIONS GOING FORWARD 421 typedef struct 422 { 423 uint16_t event; 424 uint16_t len; 425 uint16_t offset; 426 uint16_t layer_specific; 427 uint8_t data[]; 428 } HC_BT_HDR; 429 // /MODIFICATION 430 431 #ifdef __cplusplus 432 } 433 #endif 434 435 #endif /* BT_VENDOR_LIB_H */ 436