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