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 */
32typedef 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
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 */
157    BT_VND_OP_EPILOG,
158} bt_vendor_opcode_t;
159
160/** Power on/off control states */
161typedef enum {
162    BT_VND_PWR_OFF,
163    BT_VND_PWR_ON,
164}  bt_vendor_power_state_t;
165
166/** Define HCI channel identifier in the file descriptors array
167    used in BT_VND_OP_USERIAL_OPEN operation.
168 */
169typedef 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
176}  bt_vendor_hci_channels_t;
177
178/** LPM disable/enable request */
179typedef enum {
180    BT_VND_LPM_DISABLE,
181    BT_VND_LPM_ENABLE,
182} bt_vendor_lpm_mode_t;
183
184/** LPM WAKE set state request */
185typedef enum {
186    BT_VND_LPM_WAKE_ASSERT,
187    BT_VND_LPM_WAKE_DEASSERT,
188} bt_vendor_lpm_wake_state_t;
189
190/** Callback result values */
191typedef enum {
192    BT_VND_OP_RESULT_SUCCESS,
193    BT_VND_OP_RESULT_FAIL,
194} bt_vendor_op_result_t;
195
196/*
197 * Bluetooth Host/Controller Vendor callback structure.
198 */
199
200/* vendor initialization/configuration callback */
201typedef 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 */
241typedef void* (*malloc_cb)(int size);
242
243/* datapath buffer deallocation callback (callout) */
244typedef 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 */
252typedef 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 */
269typedef uint8_t (*cmd_xmit_cb)(uint16_t opcode, void *p_buf, tINT_CMD_CBACK p_cback);
270
271typedef 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 */
281    cfg_result_cb  fwcfg_cb;
282
283    /* notifies caller result of sco configuration request */
284    cfg_result_cb  scocfg_cb;
285
286    /* notifies caller result of lpm enable/disable */
287    cfg_result_cb  lpm_cb;
288
289    /* buffer allocation request */
290    malloc_cb   alloc;
291
292    /* buffer deallocation request */
293    mdealloc_cb dealloc;
294
295    /* hci command packet transmit request */
296    cmd_xmit_cb xmit_cb;
297
298    /* notifies caller completion of epilog process */
299    cfg_result_cb epilog_cb;
300} bt_vendor_callbacks_t;
301
302/*
303 * Bluetooth Host/Controller VENDOR Interface
304 */
305typedef 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);
324} bt_vendor_interface_t;
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 */
337extern const bt_vendor_interface_t BLUETOOTH_VENDOR_LIB_INTERFACE;
338
339#endif /* BT_VENDOR_LIB_H */
340
341