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 /** Struct types */ 27 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 Controller. 60 * This is called after stack initialization. 61 * [input param] 62 * None. 63 * [return] 64 * 0 - default, don't care. 65 * [callback] 66 * Must call scocfg_cb to notify the stack of the completion of vendor 67 * specific SCO configuration once it has been done. 68 */ 69 BT_VND_OP_SCO_CFG, 70 71 /* [operation] 72 * Open UART port on where the BT Controller is attached. 73 * This is called before stack initialization. 74 * [input param] 75 * A pointer to int array type for open file descriptors. 76 * The mapping of HCI channel to fd slot in the int array is given in 77 * bt_vendor_hci_channels_t. 78 * And, it requires the vendor lib to fill up the content before returning 79 * the call. 80 * Typecasting conversion: (int (*)[]) param. 81 * [return] 82 * Numbers of opened file descriptors. 83 * Valid number: 84 * 1 - CMD/EVT/ACL-In/ACL-Out via the same fd (e.g. UART) 85 * 2 - CMD/EVT on one fd, and ACL-In/ACL-Out on the other fd 86 * 4 - CMD, EVT, ACL-In, ACL-Out are on their individual fd 87 * [callback] 88 * None. 89 */ 90 BT_VND_OP_USERIAL_OPEN, 91 92 /* [operation] 93 * Close the previously opened UART port. 94 * [input param] 95 * None. 96 * [return] 97 * 0 - default, don't care. 98 * [callback] 99 * None. 100 */ 101 BT_VND_OP_USERIAL_CLOSE, 102 103 /* [operation] 104 * Get the LPM idle timeout in milliseconds. 105 * The stack uses this information to launch a timer delay before it 106 * attempts to de-assert LPM WAKE signal once downstream HCI packet 107 * has been delivered. 108 * [input param] 109 * A pointer to uint32_t type which is passed in by the stack. And, it 110 * requires the vendor lib to fill up the content before returning 111 * the call. 112 * Typecasting conversion: (uint32_t *) param. 113 * [return] 114 * 0 - default, don't care. 115 * [callback] 116 * None. 117 */ 118 BT_VND_OP_GET_LPM_IDLE_TIMEOUT, 119 120 /* [operation] 121 * Enable or disable LPM mode on BT Controller. 122 * [input param] 123 * A pointer to uint8_t type with content of bt_vendor_lpm_mode_t. 124 * Typecasting conversion: (uint8_t *) param. 125 * [return] 126 * 0 - default, don't care. 127 * [callback] 128 * Must call lpm_cb to notify the stack of the completion of LPM 129 * disable/enable process once it has been done. 130 */ 131 BT_VND_OP_LPM_SET_MODE, 132 133 /* [operation] 134 * Assert or Deassert LPM WAKE on BT Controller. 135 * [input param] 136 * A pointer to uint8_t type with content of bt_vendor_lpm_wake_state_t. 137 * Typecasting conversion: (uint8_t *) param. 138 * [return] 139 * 0 - default, don't care. 140 * [callback] 141 * None. 142 */ 143 BT_VND_OP_LPM_WAKE_SET_STATE, 144 } bt_vendor_opcode_t; 145 146 /** Power on/off control states */ 147 typedef enum { 148 BT_VND_PWR_OFF, 149 BT_VND_PWR_ON, 150 } bt_vendor_power_state_t; 151 152 /** Define HCI channel identifier in the file descriptors array 153 used in BT_VND_OP_USERIAL_OPEN operation. 154 */ 155 typedef enum { 156 CH_CMD, // HCI Command channel 157 CH_EVT, // HCI Event channel 158 CH_ACL_OUT, // HCI ACL downstream channel 159 CH_ACL_IN, // HCI ACL upstream channel 160 161 CH_MAX // Total channels 162 } bt_vendor_hci_channels_t; 163 164 /** LPM disable/enable request */ 165 typedef enum { 166 BT_VND_LPM_DISABLE, 167 BT_VND_LPM_ENABLE, 168 } bt_vendor_lpm_mode_t; 169 170 /** LPM WAKE set state request */ 171 typedef enum { 172 BT_VND_LPM_WAKE_ASSERT, 173 BT_VND_LPM_WAKE_DEASSERT, 174 } bt_vendor_lpm_wake_state_t; 175 176 /** Callback result values */ 177 typedef enum { 178 BT_VND_OP_RESULT_SUCCESS, 179 BT_VND_OP_RESULT_FAIL, 180 } bt_vendor_op_result_t; 181 182 /* 183 * Bluetooth Host/Controller Vendor callback structure. 184 */ 185 186 /* vendor initialization/configuration callback */ 187 typedef void (*cfg_result_cb)(bt_vendor_op_result_t result); 188 189 /* datapath buffer allocation callback (callout) 190 * 191 * Vendor lib needs to request a buffer through the alloc callout function 192 * from HCI lib if the buffer is for constructing a HCI Command packet which 193 * will be sent through xmit_cb to BT Controller. 194 * 195 * For each buffer allocation, the requested size needs to be big enough to 196 * accommodate the below header plus a complete HCI packet -- 197 * typedef struct 198 * { 199 * uint16_t event; 200 * uint16_t len; 201 * uint16_t offset; 202 * uint16_t layer_specific; 203 * } HC_BT_HDR; 204 * 205 * HCI lib returns a pointer to the buffer where Vendor lib should use to 206 * construct a HCI command packet as below format: 207 * 208 * -------------------------------------------- 209 * | HC_BT_HDR | HCI command | 210 * -------------------------------------------- 211 * where 212 * HC_BT_HDR.event = 0x2000; 213 * HC_BT_HDR.len = Length of HCI command; 214 * HC_BT_HDR.offset = 0; 215 * HC_BT_HDR.layer_specific = 0; 216 * 217 * For example, a HCI_RESET Command will be formed as 218 * ------------------------ 219 * | HC_BT_HDR |03|0c|00| 220 * ------------------------ 221 * with 222 * HC_BT_HDR.event = 0x2000; 223 * HC_BT_HDR.len = 3; 224 * HC_BT_HDR.offset = 0; 225 * HC_BT_HDR.layer_specific = 0; 226 */ 227 typedef void* (*malloc_cb)(int size); 228 229 /* datapath buffer deallocation callback (callout) */ 230 typedef void (*mdealloc_cb)(void *p_buf); 231 232 /* define callback of the cmd_xmit_cb 233 * 234 * The callback function which HCI lib will call with the return of command 235 * complete packet. Vendor lib is responsible for releasing the buffer passed 236 * in at the p_mem parameter by calling dealloc callout function. 237 */ 238 typedef void (*tINT_CMD_CBACK)(void *p_mem); 239 240 /* hci command packet transmit callback (callout) 241 * 242 * Vendor lib calls xmit_cb callout function in order to send a HCI Command 243 * packet to BT Controller. The buffer carrying HCI Command packet content 244 * needs to be first allocated through the alloc callout function. 245 * HCI lib will release the buffer for Vendor lib once it has delivered the 246 * packet content to BT Controller. 247 * 248 * Vendor lib needs also provide a callback function (p_cback) which HCI lib 249 * will call with the return of command complete packet. 250 * 251 * The opcode parameter gives the HCI OpCode (combination of OGF and OCF) of 252 * HCI Command packet. For example, opcode = 0x0c03 for the HCI_RESET command 253 * packet. 254 */ 255 typedef uint8_t (*cmd_xmit_cb)(uint16_t opcode, void *p_buf, tINT_CMD_CBACK p_cback); 256 257 typedef struct { 258 /** set to sizeof(bt_vendor_callbacks_t) */ 259 size_t size; 260 261 /* 262 * Callback and callout functions have implemented in HCI libray 263 * (libbt-hci.so). 264 */ 265 266 /* notifies caller result of firmware configuration request */ 267 cfg_result_cb fwcfg_cb; 268 269 /* notifies caller result of sco configuration request */ 270 cfg_result_cb scocfg_cb; 271 272 /* notifies caller result of lpm enable/disable */ 273 cfg_result_cb lpm_cb; 274 275 /* buffer allocation request */ 276 malloc_cb alloc; 277 278 /* buffer deallocation request */ 279 mdealloc_cb dealloc; 280 281 /* hci command packet transmit request */ 282 cmd_xmit_cb xmit_cb; 283 } bt_vendor_callbacks_t; 284 285 /* 286 * Bluetooth Host/Controller VENDOR Interface 287 */ 288 typedef struct { 289 /** Set to sizeof(bt_vndor_interface_t) */ 290 size_t size; 291 292 /* 293 * Functions need to be implemented in Vendor libray (libbt-vendor.so). 294 */ 295 296 /** 297 * Caller will open the interface and pass in the callback routines 298 * to the implemenation of this interface. 299 */ 300 int (*init)(const bt_vendor_callbacks_t* p_cb, unsigned char *local_bdaddr); 301 302 /** Vendor specific operations */ 303 int (*op)(bt_vendor_opcode_t opcode, void *param); 304 305 /** Closes the interface */ 306 void (*cleanup)(void); 307 } bt_vendor_interface_t; 308 309 310 /* 311 * External shared lib functions/data 312 */ 313 314 /* Entry point of DLib -- 315 * Vendor library needs to implement the body of bt_vendor_interface_t 316 * structure and uses the below name as the variable name. HCI library 317 * will use this symbol name to get address of the object through the 318 * dlsym call. 319 */ 320 extern const bt_vendor_interface_t BLUETOOTH_VENDOR_LIB_INTERFACE; 321 322 #endif /* BT_VENDOR_LIB_H */ 323 324
