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 } bt_vendor_opcode_t; 201 202 /** Power on/off control states */ 203 typedef enum { 204 BT_VND_PWR_OFF, 205 BT_VND_PWR_ON, 206 } bt_vendor_power_state_t; 207 208 /** Define HCI channel identifier in the file descriptors array 209 used in BT_VND_OP_USERIAL_OPEN operation. 210 */ 211 typedef enum { 212 CH_CMD, // HCI Command channel 213 CH_EVT, // HCI Event channel 214 CH_ACL_OUT, // HCI ACL downstream channel 215 CH_ACL_IN, // HCI ACL upstream channel 216 217 CH_MAX // Total channels 218 } bt_vendor_hci_channels_t; 219 220 /** LPM disable/enable request */ 221 typedef enum { 222 BT_VND_LPM_DISABLE, 223 BT_VND_LPM_ENABLE, 224 } bt_vendor_lpm_mode_t; 225 226 /** LPM WAKE set state request */ 227 typedef enum { 228 BT_VND_LPM_WAKE_ASSERT, 229 BT_VND_LPM_WAKE_DEASSERT, 230 } bt_vendor_lpm_wake_state_t; 231 232 /** Callback result values */ 233 typedef enum { 234 BT_VND_OP_RESULT_SUCCESS, 235 BT_VND_OP_RESULT_FAIL, 236 } bt_vendor_op_result_t; 237 238 /** audio (SCO) state changes triggering VS commands for configuration */ 239 typedef struct { 240 uint16_t handle; 241 uint16_t peer_codec; 242 uint16_t state; 243 bool use_enhanced_sco; 244 } bt_vendor_op_audio_state_t; 245 246 /* 247 * Bluetooth Host/Controller Vendor callback structure. 248 */ 249 250 /* vendor initialization/configuration callback */ 251 typedef void (*cfg_result_cb)(bt_vendor_op_result_t result); 252 253 /* datapath buffer allocation callback (callout) 254 * 255 * Vendor lib needs to request a buffer through the alloc callout function 256 * from HCI lib if the buffer is for constructing a HCI Command packet which 257 * will be sent through xmit_cb to BT Controller. 258 * 259 * For each buffer allocation, the requested size needs to be big enough to 260 * accommodate the below header plus a complete HCI packet -- 261 * typedef struct 262 * { 263 * uint16_t event; 264 * uint16_t len; 265 * uint16_t offset; 266 * uint16_t layer_specific; 267 * } HC_BT_HDR; 268 * 269 * HCI lib returns a pointer to the buffer where Vendor lib should use to 270 * construct a HCI command packet as below format: 271 * 272 * -------------------------------------------- 273 * | HC_BT_HDR | HCI command | 274 * -------------------------------------------- 275 * where 276 * HC_BT_HDR.event = 0x2000; 277 * HC_BT_HDR.len = Length of HCI command; 278 * HC_BT_HDR.offset = 0; 279 * HC_BT_HDR.layer_specific = 0; 280 * 281 * For example, a HCI_RESET Command will be formed as 282 * ------------------------ 283 * | HC_BT_HDR |03|0c|00| 284 * ------------------------ 285 * with 286 * HC_BT_HDR.event = 0x2000; 287 * HC_BT_HDR.len = 3; 288 * HC_BT_HDR.offset = 0; 289 * HC_BT_HDR.layer_specific = 0; 290 */ 291 typedef void* (*malloc_cb)(int size); 292 293 /* datapath buffer deallocation callback (callout) */ 294 typedef void (*mdealloc_cb)(void* p_buf); 295 296 /* define callback of the cmd_xmit_cb 297 * 298 * The callback function which HCI lib will call with the return of command 299 * complete packet. Vendor lib is responsible for releasing the buffer passed 300 * in at the p_mem parameter by calling dealloc callout function. 301 */ 302 typedef void (*tINT_CMD_CBACK)(void* p_mem); 303 304 /* hci command packet transmit callback (callout) 305 * 306 * Vendor lib calls xmit_cb callout function in order to send a HCI Command 307 * packet to BT Controller. The buffer carrying HCI Command packet content 308 * needs to be first allocated through the alloc callout function. 309 * HCI lib will release the buffer for Vendor lib once it has delivered the 310 * packet content to BT Controller. 311 * 312 * Vendor lib needs also provide a callback function (p_cback) which HCI lib 313 * will call with the return of command complete packet. 314 * 315 * The opcode parameter gives the HCI OpCode (combination of OGF and OCF) of 316 * HCI Command packet. For example, opcode = 0x0c03 for the HCI_RESET command 317 * packet. 318 */ 319 typedef uint8_t (*cmd_xmit_cb)(uint16_t opcode, void* p_buf, tINT_CMD_CBACK p_cback); 320 321 typedef void (*cfg_a2dp_cb)(bt_vendor_op_result_t result, bt_vendor_opcode_t op, 322 uint8_t bta_av_handle); 323 324 typedef struct { 325 /** set to sizeof(bt_vendor_callbacks_t) */ 326 size_t size; 327 328 /* 329 * Callback and callout functions have implemented in HCI libray 330 * (libbt-hci.so). 331 */ 332 333 /* notifies caller result of firmware configuration request */ 334 cfg_result_cb fwcfg_cb; 335 336 /* notifies caller result of sco configuration request */ 337 cfg_result_cb scocfg_cb; 338 339 /* notifies caller result of lpm enable/disable */ 340 cfg_result_cb lpm_cb; 341 342 /* notifies the result of codec setting */ 343 cfg_result_cb audio_state_cb; 344 345 /* buffer allocation request */ 346 malloc_cb alloc; 347 348 /* buffer deallocation request */ 349 mdealloc_cb dealloc; 350 351 /* hci command packet transmit request */ 352 cmd_xmit_cb xmit_cb; 353 354 /* notifies caller completion of epilog process */ 355 cfg_result_cb epilog_cb; 356 357 /* notifies status of a2dp offload cmd's */ 358 cfg_a2dp_cb a2dp_offload_cb; 359 } bt_vendor_callbacks_t; 360 361 /** A2DP offload request */ 362 typedef struct { 363 uint8_t bta_av_handle; /* BTA_AV Handle for callbacks */ 364 uint16_t xmit_quota; /* Total ACL quota for light stack */ 365 uint16_t acl_data_size; /* Max ACL data size across HCI transport */ 366 uint16_t stream_mtu; 367 uint16_t local_cid; 368 uint16_t remote_cid; 369 uint16_t lm_handle; 370 uint8_t is_flushable; /* true if flushable channel */ 371 uint32_t stream_source; 372 uint8_t codec_info[10]; /* Codec capabilities array */ 373 } bt_vendor_op_a2dp_offload_t; 374 375 /* 376 * Bluetooth Host/Controller VENDOR Interface 377 */ 378 typedef struct { 379 /** Set to sizeof(bt_vndor_interface_t) */ 380 size_t size; 381 382 /* 383 * Functions need to be implemented in Vendor libray (libbt-vendor.so). 384 */ 385 386 /** 387 * Caller will open the interface and pass in the callback routines 388 * to the implemenation of this interface. 389 */ 390 int (*init)(const bt_vendor_callbacks_t* p_cb, unsigned char* local_bdaddr); 391 392 /** Vendor specific operations */ 393 int (*op)(bt_vendor_opcode_t opcode, void* param); 394 395 /** Closes the interface */ 396 void (*cleanup)(void); 397 } bt_vendor_interface_t; 398 399 /* 400 * External shared lib functions/data 401 */ 402 403 /* Entry point of DLib -- 404 * Vendor library needs to implement the body of bt_vendor_interface_t 405 * structure and uses the below name as the variable name. HCI library 406 * will use this symbol name to get address of the object through the 407 * dlsym call. 408 */ 409 extern const bt_vendor_interface_t BLUETOOTH_VENDOR_LIB_INTERFACE; 410 411 #endif /* BT_VENDOR_LIB_H */ 412