1 /** @file
2 * @brief Bluetooth HCI driver API.
3 *
4 * Copyright (c) 2024 Johan Hedberg
5 *
6 * SPDX-License-Identifier: Apache-2.0
7 */
8 #ifndef ZEPHYR_INCLUDE_DRIVERS_BLUETOOTH_H_
9 #define ZEPHYR_INCLUDE_DRIVERS_BLUETOOTH_H_
10
11 /**
12 * @brief Bluetooth HCI APIs
13 * @defgroup bt_hci_api Bluetooth HCI APIs
14 *
15 * @since 3.7
16 * @version 0.2.0
17 *
18 * @ingroup bluetooth
19 * @{
20 */
21
22 #include <stdbool.h>
23 #include <stdint.h>
24 #include <zephyr/net_buf.h>
25 #include <zephyr/bluetooth/buf.h>
26 #include <zephyr/bluetooth/addr.h>
27 #include <zephyr/bluetooth/hci_vs.h>
28 #include <zephyr/device.h>
29
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33
34 struct bt_hci_setup_params {
35 /** The public identity address to give to the controller. This field is used when the
36 * driver selects @kconfig{CONFIG_BT_HCI_SET_PUBLIC_ADDR} to indicate that it supports
37 * setting the controller's public address.
38 */
39 bt_addr_t public_addr;
40 };
41
42 enum {
43 /* The host should never send HCI_Reset */
44 BT_HCI_QUIRK_NO_RESET = BIT(0),
45 /* The controller does not auto-initiate a DLE procedure when the
46 * initial connection data length parameters are not equal to the
47 * default data length parameters. Therefore the host should initiate
48 * the DLE procedure after connection establishment.
49 *
50 * That requirement is stated in Core Spec v5.4 Vol 6 Part B. 4.5.10
51 * Data PDU length management:
52 *
53 * > For a new connection:
54 * > - ... If either value is not 27, then the Controller should
55 * > initiate the Data Length Update procedure at the earliest
56 * > practical opportunity.
57 */
58 BT_HCI_QUIRK_NO_AUTO_DLE = BIT(1),
59 };
60
61 /** Possible values for the 'bus' member of the bt_hci_driver struct */
62 enum bt_hci_bus {
63 BT_HCI_BUS_VIRTUAL = 0,
64 BT_HCI_BUS_USB = 1,
65 BT_HCI_BUS_PCCARD = 2,
66 BT_HCI_BUS_UART = 3,
67 BT_HCI_BUS_RS232 = 4,
68 BT_HCI_BUS_PCI = 5,
69 BT_HCI_BUS_SDIO = 6,
70 BT_HCI_BUS_SPI = 7,
71 BT_HCI_BUS_I2C = 8,
72 BT_HCI_BUS_SMD = 9,
73 BT_HCI_BUS_VIRTIO = 10,
74 BT_HCI_BUS_IPC = 11,
75 /* IPM is deprecated and simply an alias for IPC */
76 BT_HCI_BUS_IPM = BT_HCI_BUS_IPC,
77 };
78
79 #define BT_DT_HCI_QUIRK_OR(node_id, prop, idx) \
80 UTIL_CAT(BT_HCI_QUIRK_, DT_STRING_UPPER_TOKEN_BY_IDX(node_id, prop, idx))
81 #define BT_DT_HCI_QUIRKS_GET(node_id) COND_CODE_1(DT_NODE_HAS_PROP(node_id, bt_hci_quirks), \
82 (DT_FOREACH_PROP_ELEM_SEP(node_id, \
83 bt_hci_quirks, \
84 BT_DT_HCI_QUIRK_OR, \
85 (|))), \
86 (0))
87 #define BT_DT_HCI_QUIRKS_INST_GET(inst) BT_DT_HCI_QUIRKS_GET(DT_DRV_INST(inst))
88
89 #define BT_DT_HCI_NAME_GET(node_id) DT_PROP_OR(node_id, bt_hci_name, "HCI")
90 #define BT_DT_HCI_NAME_INST_GET(inst) BT_DT_HCI_NAME_GET(DT_DRV_INST(inst))
91
92 #define BT_DT_HCI_BUS_GET(node_id) \
93 UTIL_CAT(BT_HCI_BUS_, DT_STRING_UPPER_TOKEN_OR(node_id, bt_hci_bus, VIRTUAL))
94 #define BT_DT_HCI_BUS_INST_GET(inst) BT_DT_HCI_BUS_GET(DT_DRV_INST(inst))
95
96 typedef int (*bt_hci_recv_t)(const struct device *dev, struct net_buf *buf);
97
98 __subsystem struct bt_hci_driver_api {
99 int (*open)(const struct device *dev, bt_hci_recv_t recv);
100 int (*close)(const struct device *dev);
101 int (*send)(const struct device *dev, struct net_buf *buf);
102 #if defined(CONFIG_BT_HCI_SETUP)
103 int (*setup)(const struct device *dev,
104 const struct bt_hci_setup_params *param);
105 #endif /* defined(CONFIG_BT_HCI_SETUP) */
106 };
107
108 /**
109 * @brief Open the HCI transport.
110 *
111 * Opens the HCI transport for operation. This function must not
112 * return until the transport is ready for operation, meaning it
113 * is safe to start calling the send() handler.
114 *
115 * @param dev HCI device
116 * @param recv This is callback through which the HCI driver provides the
117 * host with data from the controller. The buffer passed to
118 * the callback will have its type set with bt_buf_set_type().
119 * The callback is expected to be called from thread context.
120 *
121 * @return 0 on success or negative POSIX error number on failure.
122 */
bt_hci_open(const struct device * dev,bt_hci_recv_t recv)123 static inline int bt_hci_open(const struct device *dev, bt_hci_recv_t recv)
124 {
125 const struct bt_hci_driver_api *api = (const struct bt_hci_driver_api *)dev->api;
126
127 return api->open(dev, recv);
128 }
129
130 /**
131 * @brief Close the HCI transport.
132 *
133 * Closes the HCI transport. This function must not return until the
134 * transport is closed.
135 *
136 * @param dev HCI device
137 *
138 * @return 0 on success or negative POSIX error number on failure.
139 */
bt_hci_close(const struct device * dev)140 static inline int bt_hci_close(const struct device *dev)
141 {
142 const struct bt_hci_driver_api *api = (const struct bt_hci_driver_api *)dev->api;
143
144 if (api->close == NULL) {
145 return -ENOSYS;
146 }
147
148 return api->close(dev);
149 }
150
151 /**
152 * @brief Send HCI buffer to controller.
153 *
154 * Send an HCI packet to the controller. The packet type of the buffer
155 * must be set using bt_buf_set_type().
156 *
157 * @note This function must only be called from a cooperative thread.
158 *
159 * @param dev HCI device
160 * @param buf Buffer containing data to be sent to the controller.
161 *
162 * @return 0 on success or negative POSIX error number on failure.
163 */
bt_hci_send(const struct device * dev,struct net_buf * buf)164 static inline int bt_hci_send(const struct device *dev, struct net_buf *buf)
165 {
166 const struct bt_hci_driver_api *api = (const struct bt_hci_driver_api *)dev->api;
167
168 return api->send(dev, buf);
169 }
170
171 #if defined(CONFIG_BT_HCI_SETUP) || defined(__DOXYGEN__)
172 /**
173 * @brief HCI vendor-specific setup
174 *
175 * Executes vendor-specific commands sequence to initialize
176 * BT Controller before BT Host executes Reset sequence. This is normally
177 * called directly after bt_hci_open().
178 *
179 * @note @kconfig{CONFIG_BT_HCI_SETUP} must be selected for this
180 * field to be available.
181 *
182 * @return 0 on success or negative POSIX error number on failure.
183 */
bt_hci_setup(const struct device * dev,struct bt_hci_setup_params * params)184 static inline int bt_hci_setup(const struct device *dev, struct bt_hci_setup_params *params)
185 {
186 const struct bt_hci_driver_api *api = (const struct bt_hci_driver_api *)dev->api;
187
188 if (api->setup == NULL) {
189 return -ENOSYS;
190 }
191
192 return api->setup(dev, params);
193 }
194 #endif
195
196 /**
197 * @}
198 */
199
200 /* The following functions are not strictly part of the HCI driver API, in that
201 * they do not take as input a struct device which implements the HCI driver API.
202 */
203
204 /**
205 * @brief Setup the HCI transport, which usually means to reset the
206 * Bluetooth IC.
207 *
208 * @note A weak version of this function is included in the H4 driver, so
209 * defining it is optional per board.
210 *
211 * @param dev The device structure for the bus connecting to the IC
212 *
213 * @return 0 on success, negative error value on failure
214 */
215 int bt_hci_transport_setup(const struct device *dev);
216
217 /**
218 * @brief Teardown the HCI transport.
219 *
220 * @note A weak version of this function is included in the IPC driver, so
221 * defining it is optional. NRF5340 includes support to put network core
222 * in reset state.
223 *
224 * @param dev The device structure for the bus connecting to the IC
225 *
226 * @return 0 on success, negative error value on failure
227 */
228 int bt_hci_transport_teardown(const struct device *dev);
229
230 /** Allocate an HCI event buffer.
231 *
232 * This function allocates a new buffer for an HCI event. It is given the
233 * event code and the total length of the parameters. Upon successful return
234 * the buffer is ready to have the parameters encoded into it.
235 *
236 * @param evt HCI event OpCode.
237 * @param len Length of event parameters.
238 *
239 * @return Newly allocated buffer.
240 */
241 struct net_buf *bt_hci_evt_create(uint8_t evt, uint8_t len);
242
243 /** Allocate an HCI Command Complete event buffer.
244 *
245 * This function allocates a new buffer for HCI Command Complete event.
246 * It is given the OpCode (encoded e.g. using the BT_OP macro) and the total
247 * length of the parameters. Upon successful return the buffer is ready to have
248 * the parameters encoded into it.
249 *
250 * @param op HCI command OpCode.
251 * @param plen Length of command parameters.
252 *
253 * @return Newly allocated buffer.
254 */
255 struct net_buf *bt_hci_cmd_complete_create(uint16_t op, uint8_t plen);
256
257 /** Allocate an HCI Command Status event buffer.
258 *
259 * This function allocates a new buffer for HCI Command Status event.
260 * It is given the OpCode (encoded e.g. using the BT_OP macro) and the status
261 * code. Upon successful return the buffer is ready to have the parameters
262 * encoded into it.
263 *
264 * @param op HCI command OpCode.
265 * @param status Status code.
266 *
267 * @return Newly allocated buffer.
268 */
269 struct net_buf *bt_hci_cmd_status_create(uint16_t op, uint8_t status);
270
271 #ifdef __cplusplus
272 }
273 #endif
274
275 #endif /* ZEPHYR_INCLUDE_DRIVERS_BLUETOOTH_H_ */
276
