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 : /* IPM is deprecated and simply an alias for IPC */
76 : BT_HCI_BUS_IPM = BT_HCI_BUS_IPC,
77 : };
78 :
79 0 : #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 0 : #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 0 : #define BT_DT_HCI_QUIRKS_INST_GET(inst) BT_DT_HCI_QUIRKS_GET(DT_DRV_INST(inst))
88 :
89 0 : #define BT_DT_HCI_NAME_GET(node_id) DT_PROP_OR(node_id, bt_hci_name, "HCI")
90 0 : #define BT_DT_HCI_NAME_INST_GET(inst) BT_DT_HCI_NAME_GET(DT_DRV_INST(inst))
91 :
92 0 : #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 0 : #define BT_DT_HCI_BUS_INST_GET(inst) BT_DT_HCI_BUS_GET(DT_DRV_INST(inst))
95 :
96 0 : typedef int (*bt_hci_recv_t)(const struct device *dev, struct net_buf *buf);
97 :
98 0 : __subsystem struct bt_hci_driver_api {
99 0 : int (*open)(const struct device *dev, bt_hci_recv_t recv);
100 0 : int (*close)(const struct device *dev);
101 0 : 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 : */
123 1 : 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 : */
140 1 : 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 : */
164 1 : 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 : */
184 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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_ */
|
