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