bt_vendor_lib.h
Go to the documentation of this file.
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
144 
145 /* [operation]
146  * Perform any vendor specific commands related to audio state changes.
147  * [input param]
148  * a pointer to bt_vendor_op_audio_state_t indicating what audio state is
149  * set.
150  * [return]
151  * 0 - default, don't care.
152  * [callback]
153  * None.
154  */
156 
157 /* [operation]
158  * The epilog call to the vendor module so that it can perform any
159  * vendor-specific processes (e.g. send a HCI_RESET to BT Controller)
160  * before the caller calls for cleanup().
161  * [input param]
162  * None.
163  * [return]
164  * 0 - default, don't care.
165  * [callback]
166  * Must call epilog_cb to notify the stack of the completion of vendor
167  * specific epilog process once it has been done.
168  */
171 
172 /** Power on/off control states */
173 typedef enum {
177 
178 /** Define HCI channel identifier in the file descriptors array
179  used in BT_VND_OP_USERIAL_OPEN operation.
180  */
181 typedef enum {
182  CH_CMD, // HCI Command channel
183  CH_EVT, // HCI Event channel
184  CH_ACL_OUT, // HCI ACL downstream channel
185  CH_ACL_IN, // HCI ACL upstream channel
186 
187  CH_MAX // Total channels
189 
190 /** LPM disable/enable request */
191 typedef enum {
195 
196 /** LPM WAKE set state request */
197 typedef enum {
201 
202 /** Callback result values */
203 typedef enum {
207 
208 /** audio (SCO) state changes triggering VS commands for configuration */
209 typedef struct {
210  uint16_t handle;
211  uint16_t peer_codec;
212  uint16_t state;
214 
215 /*
216  * Bluetooth Host/Controller Vendor callback structure.
217  */
218 
219 /* vendor initialization/configuration callback */
220 typedef void (*cfg_result_cb)(bt_vendor_op_result_t result);
221 
222 /* datapath buffer allocation callback (callout)
223  *
224  * Vendor lib needs to request a buffer through the alloc callout function
225  * from HCI lib if the buffer is for constructing a HCI Command packet which
226  * will be sent through xmit_cb to BT Controller.
227  *
228  * For each buffer allocation, the requested size needs to be big enough to
229  * accommodate the below header plus a complete HCI packet --
230  * typedef struct
231  * {
232  * uint16_t event;
233  * uint16_t len;
234  * uint16_t offset;
235  * uint16_t layer_specific;
236  * } HC_BT_HDR;
237  *
238  * HCI lib returns a pointer to the buffer where Vendor lib should use to
239  * construct a HCI command packet as below format:
240  *
241  * --------------------------------------------
242  * | HC_BT_HDR | HCI command |
243  * --------------------------------------------
244  * where
245  * HC_BT_HDR.event = 0x2000;
246  * HC_BT_HDR.len = Length of HCI command;
247  * HC_BT_HDR.offset = 0;
248  * HC_BT_HDR.layer_specific = 0;
249  *
250  * For example, a HCI_RESET Command will be formed as
251  * ------------------------
252  * | HC_BT_HDR |03|0c|00|
253  * ------------------------
254  * with
255  * HC_BT_HDR.event = 0x2000;
256  * HC_BT_HDR.len = 3;
257  * HC_BT_HDR.offset = 0;
258  * HC_BT_HDR.layer_specific = 0;
259  */
260 typedef void* (*malloc_cb)(int size);
261 
262 /* datapath buffer deallocation callback (callout) */
263 typedef void (*mdealloc_cb)(void *p_buf);
264 
265 /* define callback of the cmd_xmit_cb
266  *
267  * The callback function which HCI lib will call with the return of command
268  * complete packet. Vendor lib is responsible for releasing the buffer passed
269  * in at the p_mem parameter by calling dealloc callout function.
270  */
271 typedef void (*tINT_CMD_CBACK)(void *p_mem);
272 
273 /* hci command packet transmit callback (callout)
274  *
275  * Vendor lib calls xmit_cb callout function in order to send a HCI Command
276  * packet to BT Controller. The buffer carrying HCI Command packet content
277  * needs to be first allocated through the alloc callout function.
278  * HCI lib will release the buffer for Vendor lib once it has delivered the
279  * packet content to BT Controller.
280  *
281  * Vendor lib needs also provide a callback function (p_cback) which HCI lib
282  * will call with the return of command complete packet.
283  *
284  * The opcode parameter gives the HCI OpCode (combination of OGF and OCF) of
285  * HCI Command packet. For example, opcode = 0x0c03 for the HCI_RESET command
286  * packet.
287  */
288 typedef uint8_t (*cmd_xmit_cb)(uint16_t opcode, void *p_buf, tINT_CMD_CBACK p_cback);
289 
290 typedef struct {
291  /** set to sizeof(bt_vendor_callbacks_t) */
292  size_t size;
293 
294  /*
295  * Callback and callout functions have implemented in HCI libray
296  * (libbt-hci.so).
297  */
298 
299  /* notifies caller result of firmware configuration request */
301 
302  /* notifies caller result of sco configuration request */
304 
305  /* notifies caller result of lpm enable/disable */
307 
308  /* notifies the result of codec setting */
310 
311  /* buffer allocation request */
313 
314  /* buffer deallocation request */
316 
317  /* hci command packet transmit request */
319 
320  /* notifies caller completion of epilog process */
323 
324 /*
325  * Bluetooth Host/Controller VENDOR Interface
326  */
327 typedef struct {
328  /** Set to sizeof(bt_vndor_interface_t) */
329  size_t size;
330 
331  /*
332  * Functions need to be implemented in Vendor libray (libbt-vendor.so).
333  */
334 
335  /**
336  * Caller will open the interface and pass in the callback routines
337  * to the implemenation of this interface.
338  */
339  int (*init)(const bt_vendor_callbacks_t* p_cb, unsigned char *local_bdaddr);
340 
341  /** Vendor specific operations */
342  int (*op)(bt_vendor_opcode_t opcode, void *param);
343 
344  /** Closes the interface */
345  void (*cleanup)(void);
347 
348 
349 /*
350  * External shared lib functions/data
351  */
352 
353 /* Entry point of DLib --
354  * Vendor library needs to implement the body of bt_vendor_interface_t
355  * structure and uses the below name as the variable name. HCI library
356  * will use this symbol name to get address of the object through the
357  * dlsym call.
358  */
360 
361 #endif /* BT_VENDOR_LIB_H */
362 
bt_vendor_lpm_wake_state_t
void(* mdealloc_cb)(void *p_buf)
const bt_vendor_interface_t BLUETOOTH_VENDOR_LIB_INTERFACE
bt_vendor_lpm_mode_t
cfg_result_cb fwcfg_cb
bt_vendor_op_result_t
void *(* malloc_cb)(int size)
cfg_result_cb lpm_cb
bt_vendor_power_state_t
cfg_result_cb scocfg_cb
uint8_t(* cmd_xmit_cb)(uint16_t opcode, void *p_buf, tINT_CMD_CBACK p_cback)
bt_vendor_opcode_t
Definition: bt_vendor_lib.h:32
cfg_result_cb audio_state_cb
cfg_result_cb epilog_cb
void(* cfg_result_cb)(bt_vendor_op_result_t result)
bt_vendor_hci_channels_t
void(* tINT_CMD_CBACK)(void *p_mem)