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 <net/buf.h>
22 #include <bluetooth/buf.h>
23 #include <bluetooth/hci_vs.h>
24 #include <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 CONFIG_BT_RECV_IS_RX_THREAD 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 CONFIG_BT_RECV_IS_RX_THREAD 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 * @param buf Network buffer containing data from the controller.
93 *
94 * @return 0 on success or negative error number on failure.
95 */
96 int bt_recv(struct net_buf *buf);
97
98 /**
99 * @brief Receive high priority data from the controller/HCI driver.
100 *
101 * This is the same as bt_recv(), except that it should be used for
102 * so-called high priority HCI events. There's a separate
103 * bt_hci_evt_get_flags() helper that can be used to identify which events
104 * have the BT_HCI_EVT_FLAG_RECV_PRIO flag set.
105 *
106 * As with bt_recv(), the buffer needs to have its type set with the help of
107 * bt_buf_set_type() before calling this API. The only exception is so called
108 * high priority HCI events which should be delivered to the host stack through
109 * bt_recv_prio() instead.
110 *
111 * @param buf Network buffer containing data from the controller.
112 *
113 * @return 0 on success or negative error number on failure.
114 */
115 int bt_recv_prio(struct net_buf *buf);
116
117 /** @brief Read static addresses from the controller.
118 *
119 * @param addrs Random static address and Identity Root (IR) array.
120 * @param size Size of array.
121 *
122 * @return Number of addresses read.
123 */
124 uint8_t bt_read_static_addr(struct bt_hci_vs_static_addr addrs[], uint8_t size);
125
126 /** Possible values for the 'bus' member of the bt_hci_driver struct */
127 enum bt_hci_driver_bus {
128 BT_HCI_DRIVER_BUS_VIRTUAL = 0,
129 BT_HCI_DRIVER_BUS_USB = 1,
130 BT_HCI_DRIVER_BUS_PCCARD = 2,
131 BT_HCI_DRIVER_BUS_UART = 3,
132 BT_HCI_DRIVER_BUS_RS232 = 4,
133 BT_HCI_DRIVER_BUS_PCI = 5,
134 BT_HCI_DRIVER_BUS_SDIO = 6,
135 BT_HCI_DRIVER_BUS_SPI = 7,
136 BT_HCI_DRIVER_BUS_I2C = 8,
137 BT_HCI_DRIVER_BUS_IPM = 9,
138 };
139
140 /**
141 * @brief Abstraction which represents the HCI transport to the controller.
142 *
143 * This struct is used to represent the HCI transport to the Bluetooth
144 * controller.
145 */
146 struct bt_hci_driver {
147 /** Name of the driver */
148 const char *name;
149
150 /** Bus of the transport (BT_HCI_DRIVER_BUS_*) */
151 enum bt_hci_driver_bus bus;
152
153 /** Specific controller quirks. These are set by the HCI driver
154 * and acted upon by the host. They can either be statically
155 * set at buildtime, or set at runtime before the HCI driver's
156 * open() callback returns.
157 */
158 uint32_t quirks;
159
160 /**
161 * @brief Open the HCI transport.
162 *
163 * Opens the HCI transport for operation. This function must not
164 * return until the transport is ready for operation, meaning it
165 * is safe to start calling the send() handler.
166 *
167 * If the driver uses its own RX thread, i.e.
168 * CONFIG_BT_RECV_IS_RX_THREAD is set, then this
169 * function is expected to start that thread.
170 *
171 * @return 0 on success or negative error number on failure.
172 */
173 int (*open)(void);
174
175 /**
176 * @brief Send HCI buffer to controller.
177 *
178 * Send an HCI command or ACL data to the controller. The exact
179 * type of the data can be checked with the help of bt_buf_get_type().
180 *
181 * @note This function must only be called from a cooperative thread.
182 *
183 * @param buf Buffer containing data to be sent to the controller.
184 *
185 * @return 0 on success or negative error number on failure.
186 */
187 int (*send)(struct net_buf *buf);
188 };
189
190 /**
191 * @brief Register a new HCI driver to the Bluetooth stack.
192 *
193 * This needs to be called before any application code runs. The bt_enable()
194 * API will fail if there is no driver registered.
195 *
196 * @param drv A bt_hci_driver struct representing the driver.
197 *
198 * @return 0 on success or negative error number on failure.
199 */
200 int bt_hci_driver_register(const struct bt_hci_driver *drv);
201
202 /**
203 * @brief Setup the HCI transport, which usually means to reset the
204 * Bluetooth IC.
205 *
206 * @note A weak version of this function is included in the H4 driver, so
207 * defining it is optional per board.
208 *
209 * @param dev The device structure for the bus connecting to the IC
210 *
211 * @return 0 on success, negative error value on failure
212 */
213 int bt_hci_transport_setup(const struct device *dev);
214
215 /** Allocate an HCI event buffer.
216 *
217 * This function allocates a new buffer for an HCI event. It is given the
218 * avent code and the total length of the parameters. Upon successful return
219 * the buffer is ready to have the parameters encoded into it.
220 *
221 * @param evt Event OpCode.
222 * @param len Length of event parameters.
223 *
224 * @return Newly allocated buffer.
225 */
226 struct net_buf *bt_hci_evt_create(uint8_t evt, uint8_t len);
227
228 /** Allocate an HCI Command Complete event buffer.
229 *
230 * This function allocates a new buffer for HCI Command Complete event.
231 * It is given the OpCode (encoded e.g. using the BT_OP macro) and the total
232 * length of the parameters. Upon successful return the buffer is ready to have
233 * the parameters encoded into it.
234 *
235 * @param op Command OpCode.
236 * @param plen Length of command parameters.
237 *
238 * @return Newly allocated buffer.
239 */
240 struct net_buf *bt_hci_cmd_complete_create(uint16_t op, uint8_t plen);
241
242 /** Allocate an HCI Command Status event buffer.
243 *
244 * This function allocates a new buffer for HCI Command Status event.
245 * It is given the OpCode (encoded e.g. using the BT_OP macro) and the status
246 * code. Upon successful return the buffer is ready to have the parameters
247 * encoded into it.
248 *
249 * @param op Command OpCode.
250 * @param status Status code.
251 *
252 * @return Newly allocated buffer.
253 */
254 struct net_buf *bt_hci_cmd_status_create(uint16_t op, uint8_t status);
255
256 #ifdef __cplusplus
257 }
258 #endif
259
260 /**
261 * @}
262 */
263
264 #endif /* ZEPHYR_INCLUDE_DRIVERS_BLUETOOTH_HCI_DRIVER_H_ */
265
