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 : #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 0 : 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 1 : bt_addr_t public_addr;
40 : };
41 :
42 0 : 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 0 : 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 : };
76 :
77 0 : #define BT_DT_HCI_QUIRK_OR(node_id, prop, idx) \
78 : UTIL_CAT(BT_HCI_QUIRK_, DT_STRING_UPPER_TOKEN_BY_IDX(node_id, prop, idx))
79 0 : #define BT_DT_HCI_QUIRKS_GET(node_id) COND_CODE_1(DT_NODE_HAS_PROP(node_id, bt_hci_quirks), \
80 : (DT_FOREACH_PROP_ELEM_SEP(node_id, \
81 : bt_hci_quirks, \
82 : BT_DT_HCI_QUIRK_OR, \
83 : (|))), \
84 : (0))
85 0 : #define BT_DT_HCI_QUIRKS_INST_GET(inst) BT_DT_HCI_QUIRKS_GET(DT_DRV_INST(inst))
86 :
87 0 : #define BT_DT_HCI_NAME_GET(node_id) DT_PROP_OR(node_id, bt_hci_name, "HCI")
88 0 : #define BT_DT_HCI_NAME_INST_GET(inst) BT_DT_HCI_NAME_GET(DT_DRV_INST(inst))
89 :
90 0 : #define BT_DT_HCI_BUS_GET(node_id) DT_ENUM_IDX_OR(node_id, bt_hci_bus, BT_HCI_BUS_VIRTUAL)
91 :
92 0 : #define BT_DT_HCI_BUS_INST_GET(inst) BT_DT_HCI_BUS_GET(DT_DRV_INST(inst))
93 :
94 0 : typedef int (*bt_hci_recv_t)(const struct device *dev, struct net_buf *buf);
95 :
96 0 : __subsystem struct bt_hci_driver_api {
97 0 : int (*open)(const struct device *dev, bt_hci_recv_t recv);
98 0 : int (*close)(const struct device *dev);
99 0 : int (*send)(const struct device *dev, struct net_buf *buf);
100 : #if defined(CONFIG_BT_HCI_SETUP)
101 : int (*setup)(const struct device *dev,
102 : const struct bt_hci_setup_params *param);
103 : #endif /* defined(CONFIG_BT_HCI_SETUP) */
104 : };
105 :
106 : /**
107 : * @brief Open the HCI transport.
108 : *
109 : * Opens the HCI transport for operation. This function must not
110 : * return until the transport is ready for operation, meaning it
111 : * is safe to start calling the send() handler.
112 : *
113 : * @param dev HCI device
114 : * @param recv This is callback through which the HCI driver provides the
115 : * host with data from the controller. The callback is expected
116 : * to be called from thread context.
117 : *
118 : * @return 0 on success or negative POSIX error number on failure.
119 : */
120 1 : static inline int bt_hci_open(const struct device *dev, bt_hci_recv_t recv)
121 : {
122 : const struct bt_hci_driver_api *api = (const struct bt_hci_driver_api *)dev->api;
123 :
124 : return api->open(dev, recv);
125 : }
126 :
127 : /**
128 : * @brief Close the HCI transport.
129 : *
130 : * Closes the HCI transport. This function must not return until the
131 : * transport is closed.
132 : *
133 : * @param dev HCI device
134 : *
135 : * @return 0 on success or negative POSIX error number on failure.
136 : */
137 1 : static inline int bt_hci_close(const struct device *dev)
138 : {
139 : const struct bt_hci_driver_api *api = (const struct bt_hci_driver_api *)dev->api;
140 :
141 : if (api->close == NULL) {
142 : return -ENOSYS;
143 : }
144 :
145 : return api->close(dev);
146 : }
147 :
148 : /**
149 : * @brief Send HCI buffer to controller.
150 : *
151 : * Send an HCI packet to the controller. The packet type is encoded as H:4,
152 : * i.e. the UART transport encoding, as a prefix to the actual payload. This means
153 : * that HCI drivers that use H:4 as their native encoding don't need to do any
154 : * special handling of the packet type.
155 : *
156 : * If the function returns 0 (success) the reference to @c buf was moved to the
157 : * HCI driver. On error, the caller still owns the reference and is responsible
158 : * for eventually calling @ref net_buf_unref on it.
159 : *
160 : * @note This function must only be called from a cooperative thread.
161 : *
162 : * @param dev HCI device
163 : * @param buf Buffer containing data to be sent to the controller.
164 : *
165 : * @return 0 on success or negative POSIX error number on failure.
166 : */
167 1 : static inline int bt_hci_send(const struct device *dev, struct net_buf *buf)
168 : {
169 : const struct bt_hci_driver_api *api = (const struct bt_hci_driver_api *)dev->api;
170 :
171 : return api->send(dev, buf);
172 : }
173 :
174 : #if defined(CONFIG_BT_HCI_SETUP) || defined(__DOXYGEN__)
175 : /**
176 : * @brief HCI vendor-specific setup
177 : *
178 : * Executes vendor-specific commands sequence to initialize
179 : * BT Controller before BT Host executes Reset sequence. This is normally
180 : * called directly after bt_hci_open().
181 : *
182 : * @note @kconfig{CONFIG_BT_HCI_SETUP} must be selected for this
183 : * field to be available.
184 : *
185 : * @return 0 on success or negative POSIX error number on failure.
186 : */
187 1 : static inline int bt_hci_setup(const struct device *dev, struct bt_hci_setup_params *params)
188 : {
189 : const struct bt_hci_driver_api *api = (const struct bt_hci_driver_api *)dev->api;
190 :
191 : if (api->setup == NULL) {
192 : return -ENOSYS;
193 : }
194 :
195 : return api->setup(dev, params);
196 : }
197 : #endif
198 :
199 : /**
200 : * @}
201 : */
202 :
203 : /* The following functions are not strictly part of the HCI driver API, in that
204 : * they do not take as input a struct device which implements the HCI driver API.
205 : */
206 :
207 : /**
208 : * @brief Setup the HCI transport, which usually means to reset the
209 : * Bluetooth IC.
210 : *
211 : * @note A weak version of this function is included in the H4 driver, so
212 : * defining it is optional per board.
213 : *
214 : * @param dev The device structure for the bus connecting to the IC
215 : *
216 : * @return 0 on success, negative error value on failure
217 : */
218 1 : int bt_hci_transport_setup(const struct device *dev);
219 :
220 : /**
221 : * @brief Teardown the HCI transport.
222 : *
223 : * @note A weak version of this function is included in the IPC driver, so
224 : * defining it is optional. NRF5340 includes support to put network core
225 : * in reset state.
226 : *
227 : * @param dev The device structure for the bus connecting to the IC
228 : *
229 : * @return 0 on success, negative error value on failure
230 : */
231 1 : int bt_hci_transport_teardown(const struct device *dev);
232 :
233 : /** Allocate an HCI event buffer.
234 : *
235 : * This function allocates a new buffer for an HCI event. It is given the
236 : * event code and the total length of the parameters. Upon successful return
237 : * the buffer is ready to have the parameters encoded into it.
238 : *
239 : * @param evt HCI event OpCode.
240 : * @param len Length of event parameters.
241 : *
242 : * @return Newly allocated buffer.
243 : */
244 1 : struct net_buf *bt_hci_evt_create(uint8_t evt, uint8_t len);
245 :
246 : /** Allocate an HCI Command Complete event buffer.
247 : *
248 : * This function allocates a new buffer for HCI Command Complete event.
249 : * It is given the OpCode (encoded e.g. using the BT_OP macro) and the total
250 : * length of the parameters. Upon successful return the buffer is ready to have
251 : * the parameters encoded into it.
252 : *
253 : * @param op HCI command OpCode.
254 : * @param plen Length of command parameters.
255 : *
256 : * @return Newly allocated buffer.
257 : */
258 1 : struct net_buf *bt_hci_cmd_complete_create(uint16_t op, uint8_t plen);
259 :
260 : /** Allocate an HCI Command Status event buffer.
261 : *
262 : * This function allocates a new buffer for HCI Command Status event.
263 : * It is given the OpCode (encoded e.g. using the BT_OP macro) and the status
264 : * code. Upon successful return the buffer is ready to have the parameters
265 : * encoded into it.
266 : *
267 : * @param op HCI command OpCode.
268 : * @param status Status code.
269 : *
270 : * @return Newly allocated buffer.
271 : */
272 1 : struct net_buf *bt_hci_cmd_status_create(uint16_t op, uint8_t status);
273 :
274 : #ifdef __cplusplus
275 : }
276 : #endif
277 :
278 : #endif /* ZEPHYR_INCLUDE_DRIVERS_BLUETOOTH_H_ */
|
