1 /** @file
2 * @brief Bluetooth HCI driver API.
3 */
4
5 /*
6 * Copyright (c) 2015-2016 Intel Corporation
7 *
8 * SPDX-License-Identifier: Apache-2.0
9 */
10 #ifndef ZEPHYR_INCLUDE_DRIVERS_BLUETOOTH_HCI_DRIVER_H_
11 #define ZEPHYR_INCLUDE_DRIVERS_BLUETOOTH_HCI_DRIVER_H_
12
13 /**
14 * @brief HCI drivers
15 * @defgroup bt_hci_driver HCI drivers
16 * @ingroup bluetooth
17 * @{
18 */
19
20 #include <stdbool.h>
21 #include <zephyr/net/buf.h>
22 #include <zephyr/bluetooth/buf.h>
23 #include <zephyr/bluetooth/hci_vs.h>
24 #include <zephyr/device.h>
25
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29
30 enum {
31 /* The host should never send HCI_Reset */
32 BT_QUIRK_NO_RESET = BIT(0),
33 /* The controller does not auto-initiate a DLE procedure when the
34 * initial connection data length parameters are not equal to the
35 * default data length parameters. Therefore the host should initiate
36 * the DLE procedure after connection establishment. */
37 BT_QUIRK_NO_AUTO_DLE = BIT(1),
38 };
39
40 #define IS_BT_QUIRK_NO_AUTO_DLE(bt_dev) ((bt_dev)->drv->quirks & BT_QUIRK_NO_AUTO_DLE)
41
42 /* @brief The HCI event shall be given to bt_recv_prio */
43 #define BT_HCI_EVT_FLAG_RECV_PRIO BIT(0)
44 /* @brief The HCI event shall be given to bt_recv. */
45 #define BT_HCI_EVT_FLAG_RECV BIT(1)
46
47 /** @brief Get HCI event flags.
48 *
49 * Helper for the HCI driver to get HCI event flags that describes rules that.
50 * must be followed.
51 *
52 * When @kconfig{CONFIG_BT_RECV_BLOCKING} is enabled the flags
53 * BT_HCI_EVT_FLAG_RECV and BT_HCI_EVT_FLAG_RECV_PRIO indicates if the event
54 * should be given to bt_recv or bt_recv_prio.
55 *
56 * @param evt HCI event code.
57 *
58 * @return HCI event flags for the specified event.
59 */
bt_hci_evt_get_flags(uint8_t evt)60 static inline uint8_t bt_hci_evt_get_flags(uint8_t evt)
61 {
62 switch (evt) {
63 case BT_HCI_EVT_DISCONN_COMPLETE:
64 return BT_HCI_EVT_FLAG_RECV | BT_HCI_EVT_FLAG_RECV_PRIO;
65 /* fallthrough */
66 #if defined(CONFIG_BT_CONN) || defined(CONFIG_BT_ISO)
67 case BT_HCI_EVT_NUM_COMPLETED_PACKETS:
68 #if defined(CONFIG_BT_CONN)
69 case BT_HCI_EVT_DATA_BUF_OVERFLOW:
70 __fallthrough;
71 #endif /* defined(CONFIG_BT_CONN) */
72 #endif /* CONFIG_BT_CONN || CONFIG_BT_ISO */
73 case BT_HCI_EVT_CMD_COMPLETE:
74 case BT_HCI_EVT_CMD_STATUS:
75 return BT_HCI_EVT_FLAG_RECV_PRIO;
76 default:
77 return BT_HCI_EVT_FLAG_RECV;
78 }
79 }
80
81 /**
82 * @brief Receive data from the controller/HCI driver.
83 *
84 * This is the main function through which the HCI driver provides the
85 * host with data from the controller. The buffer needs to have its type
86 * set with the help of bt_buf_set_type() before calling this API.
87 *
88 * When @kconfig{CONFIG_BT_RECV_BLOCKING} is defined then this API should not be used
89 * for so-called high priority HCI events, which should instead be delivered to
90 * the host stack through bt_recv_prio().
91 *
92 * @note This function must only be called from a cooperative thread.
93 *
94 * @param buf Network buffer containing data from the controller.
95 *
96 * @return 0 on success or negative error number on failure.
97 */
98 int bt_recv(struct net_buf *buf);
99
100 /**
101 * @brief Receive high priority data from the controller/HCI driver.
102 *
103 * This is the same as bt_recv(), except that it should be used for
104 * so-called high priority HCI events. There's a separate
105 * bt_hci_evt_get_flags() helper that can be used to identify which events
106 * have the BT_HCI_EVT_FLAG_RECV_PRIO flag set.
107 *
108 * As with bt_recv(), the buffer needs to have its type set with the help of
109 * bt_buf_set_type() before calling this API. The only exception is so called
110 * high priority HCI events which should be delivered to the host stack through
111 * bt_recv_prio() instead.
112 *
113 * @param buf Network buffer containing data from the controller.
114 *
115 * @return 0 on success or negative error number on failure.
116 */
117 int bt_recv_prio(struct net_buf *buf);
118
119 /** @brief Read static addresses from the controller.
120 *
121 * @param addrs Random static address and Identity Root (IR) array.
122 * @param size Size of array.
123 *
124 * @return Number of addresses read.
125 */
126 uint8_t bt_read_static_addr(struct bt_hci_vs_static_addr addrs[], uint8_t size);
127
128 /** Possible values for the 'bus' member of the bt_hci_driver struct */
129 enum bt_hci_driver_bus {
130 BT_HCI_DRIVER_BUS_VIRTUAL = 0,
131 BT_HCI_DRIVER_BUS_USB = 1,
132 BT_HCI_DRIVER_BUS_PCCARD = 2,
133 BT_HCI_DRIVER_BUS_UART = 3,
134 BT_HCI_DRIVER_BUS_RS232 = 4,
135 BT_HCI_DRIVER_BUS_PCI = 5,
136 BT_HCI_DRIVER_BUS_SDIO = 6,
137 BT_HCI_DRIVER_BUS_SPI = 7,
138 BT_HCI_DRIVER_BUS_I2C = 8,
139 BT_HCI_DRIVER_BUS_IPM = 9,
140 };
141
142 /**
143 * @brief Abstraction which represents the HCI transport to the controller.
144 *
145 * This struct is used to represent the HCI transport to the Bluetooth
146 * controller.
147 */
148 struct bt_hci_driver {
149 /** Name of the driver */
150 const char *name;
151
152 /** Bus of the transport (BT_HCI_DRIVER_BUS_*) */
153 enum bt_hci_driver_bus bus;
154
155 /** Specific controller quirks. These are set by the HCI driver
156 * and acted upon by the host. They can either be statically
157 * set at buildtime, or set at runtime before the HCI driver's
158 * open() callback returns.
159 */
160 uint32_t quirks;
161
162 /**
163 * @brief Open the HCI transport.
164 *
165 * Opens the HCI transport for operation. This function must not
166 * return until the transport is ready for operation, meaning it
167 * is safe to start calling the send() handler.
168 *
169 * If the driver uses its own RX thread, i.e.
170 * @kconfig{CONFIG_BT_RECV_BLOCKING} is set, then this
171 * function is expected to start that thread.
172 *
173 * @return 0 on success or negative error number on failure.
174 */
175 int (*open)(void);
176
177 /**
178 * @brief Close the HCI transport.
179 *
180 * Closes the HCI transport. This function must not return until the
181 * transport is closed.
182 *
183 * If the driver uses its own RX thread, i.e.
184 * @kconfig{CONFIG_BT_RECV_BLOCKING} is set, then this
185 * function is expected to abort that thread.
186 * @return 0 on success or negative error number on failure.
187 */
188 int (*close)(void);
189
190 /**
191 * @brief Send HCI buffer to controller.
192 *
193 * Send an HCI command or ACL data to the controller. The exact
194 * type of the data can be checked with the help of bt_buf_get_type().
195 *
196 * @note This function must only be called from a cooperative thread.
197 *
198 * @param buf Buffer containing data to be sent to the controller.
199 *
200 * @return 0 on success or negative error number on failure.
201 */
202 int (*send)(struct net_buf *buf);
203
204 #if defined(CONFIG_BT_HCI_SETUP) || defined(__DOXYGEN__)
205 /**
206 * @brief HCI vendor-specific setup
207 *
208 * Executes vendor-specific commands sequence to initialize
209 * BT Controller before BT Host executes Reset sequence.
210 *
211 * @note @kconfig{CONFIG_BT_HCI_SETUP} must be selected for this
212 * field to be available.
213 *
214 * @return 0 on success or negative error number on failure.
215 */
216 int (*setup)(void);
217 #endif /* defined(CONFIG_BT_HCI_SETUP) || defined(__DOXYGEN__)*/
218 };
219
220 /**
221 * @brief Register a new HCI driver to the Bluetooth stack.
222 *
223 * This needs to be called before any application code runs. The bt_enable()
224 * API will fail if there is no driver registered.
225 *
226 * @param drv A bt_hci_driver struct representing the driver.
227 *
228 * @return 0 on success or negative error number on failure.
229 */
230 int bt_hci_driver_register(const struct bt_hci_driver *drv);
231
232 /**
233 * @brief Setup the HCI transport, which usually means to reset the
234 * Bluetooth IC.
235 *
236 * @note A weak version of this function is included in the H4 driver, so
237 * defining it is optional per board.
238 *
239 * @param dev The device structure for the bus connecting to the IC
240 *
241 * @return 0 on success, negative error value on failure
242 */
243 int bt_hci_transport_setup(const struct device *dev);
244
245 /**
246 * @brief Teardown the HCI transport.
247 *
248 * @note A weak version of this function is included in the RPMSG driver, so
249 * defining it is optional. NRF5340 includes support to put network core
250 * in reset state.
251 *
252 * @param dev The device structure for the bus connecting to the IC
253 *
254 * @return 0 on success, negative error value on faulure
255 */
256 int bt_hci_transport_teardown(const struct device *dev);
257
258 /** Allocate an HCI event buffer.
259 *
260 * This function allocates a new buffer for an HCI event. It is given the
261 * event code and the total length of the parameters. Upon successful return
262 * the buffer is ready to have the parameters encoded into it.
263 *
264 * @param evt Event OpCode.
265 * @param len Length of event parameters.
266 *
267 * @return Newly allocated buffer.
268 */
269 struct net_buf *bt_hci_evt_create(uint8_t evt, uint8_t len);
270
271 /** Allocate an HCI Command Complete event buffer.
272 *
273 * This function allocates a new buffer for HCI Command Complete event.
274 * It is given the OpCode (encoded e.g. using the BT_OP macro) and the total
275 * length of the parameters. Upon successful return the buffer is ready to have
276 * the parameters encoded into it.
277 *
278 * @param op Command OpCode.
279 * @param plen Length of command parameters.
280 *
281 * @return Newly allocated buffer.
282 */
283 struct net_buf *bt_hci_cmd_complete_create(uint16_t op, uint8_t plen);
284
285 /** Allocate an HCI Command Status event buffer.
286 *
287 * This function allocates a new buffer for HCI Command Status event.
288 * It is given the OpCode (encoded e.g. using the BT_OP macro) and the status
289 * code. Upon successful return the buffer is ready to have the parameters
290 * encoded into it.
291 *
292 * @param op Command OpCode.
293 * @param status Status code.
294 *
295 * @return Newly allocated buffer.
296 */
297 struct net_buf *bt_hci_cmd_status_create(uint16_t op, uint8_t status);
298
299 #ifdef __cplusplus
300 }
301 #endif
302
303 /**
304 * @}
305 */
306
307 #endif /* ZEPHYR_INCLUDE_DRIVERS_BLUETOOTH_HCI_DRIVER_H_ */
308
