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