Line data Source code
1 0 : /* hci.h - Bluetooth Host Control Interface definitions */
2 :
3 : /*
4 : * Copyright (c) 2015-2016 Intel Corporation
5 : *
6 : * SPDX-License-Identifier: Apache-2.0
7 : */
8 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_HCI_H_
9 : #define ZEPHYR_INCLUDE_BLUETOOTH_HCI_H_
10 :
11 : #include <stdbool.h>
12 : #include <stddef.h>
13 : #include <stdint.h>
14 :
15 : #include <zephyr/bluetooth/bluetooth.h>
16 : #include <zephyr/net_buf.h>
17 : #include <zephyr/bluetooth/addr.h>
18 : #include <zephyr/bluetooth/conn.h>
19 : #include <zephyr/bluetooth/hci_types.h>
20 :
21 : #ifdef __cplusplus
22 : extern "C" {
23 : #endif
24 :
25 : /** Converts a HCI error to string.
26 : *
27 : * The error codes are described in the Bluetooth Core specification,
28 : * Vol 1, Part F, Section 2.
29 : *
30 : * The HCI documentation found in Vol 4, Part E,
31 : * describes when the different error codes are used.
32 : *
33 : * See also the defined BT_HCI_ERR_* macros.
34 : *
35 : * @return The string representation of the HCI error code.
36 : * If @kconfig{CONFIG_BT_HCI_ERR_TO_STR} is not enabled,
37 : * this just returns the empty string
38 : */
39 : #if defined(CONFIG_BT_HCI_ERR_TO_STR)
40 : const char *bt_hci_err_to_str(uint8_t hci_err);
41 : #else
42 : #include <zephyr/toolchain.h>
43 :
44 1 : static inline const char *bt_hci_err_to_str(uint8_t hci_err)
45 : {
46 : ARG_UNUSED(hci_err);
47 :
48 : return "";
49 : }
50 : #endif
51 :
52 : /** Allocate a HCI command buffer.
53 : *
54 : * This function allocates a new buffer for a HCI command. It is given
55 : * the OpCode (encoded e.g. using the BT_OP macro) and the total length
56 : * of the parameters. Upon successful return the buffer is ready to have
57 : * the parameters encoded into it.
58 : *
59 : * @deprecated Use bt_hci_cmd_alloc() instead.
60 : *
61 : * @param opcode Command OpCode.
62 : * @param param_len Length of command parameters.
63 : *
64 : * @return Newly allocated buffer.
65 : */
66 1 : __deprecated struct net_buf *bt_hci_cmd_create(uint16_t opcode, uint8_t param_len);
67 :
68 : /** Allocate an HCI command buffer.
69 : *
70 : * This function allocates a new buffer for an HCI command. Upon successful
71 : * return the buffer is ready to have the command parameters encoded into it.
72 : * Sufficient headroom gets automatically reserved in the buffer, allowing
73 : * the actual command and H:4 headers to be encoded later, as part of
74 : * calling bt_hci_cmd_send() or bt_hci_cmd_send_sync().
75 : *
76 : * @param timeout Timeout for the allocation.
77 : *
78 : * @return Newly allocated buffer or NULL if allocation failed.
79 : */
80 1 : struct net_buf *bt_hci_cmd_alloc(k_timeout_t timeout);
81 :
82 : /** Send a HCI command asynchronously.
83 : *
84 : * This function is used for sending a HCI command asynchronously. It can
85 : * either be called for a buffer created using bt_hci_cmd_alloc(), or
86 : * if the command has no parameters a NULL can be passed instead. The
87 : * sending of the command will happen asynchronously, i.e. upon successful
88 : * return from this function the caller only knows that it was queued
89 : * successfully.
90 : *
91 : * If synchronous behavior, and retrieval of the Command Complete parameters
92 : * is desired, the bt_hci_cmd_send_sync() API should be used instead.
93 : *
94 : * @param opcode Command OpCode.
95 : * @param buf Command buffer or NULL (if no parameters).
96 : *
97 : * @return 0 on success or negative error value on failure.
98 : */
99 1 : int bt_hci_cmd_send(uint16_t opcode, struct net_buf *buf);
100 :
101 : /** Send a HCI command synchronously.
102 : *
103 : * This function is used for sending a HCI command synchronously. It can
104 : * either be called for a buffer created using bt_hci_cmd_alloc(), or
105 : * if the command has no parameters a NULL can be passed instead.
106 : *
107 : * The function will block until a Command Status or a Command Complete
108 : * event is returned. If either of these have a non-zero status the function
109 : * will return a negative error code and the response reference will not
110 : * be set. If the command completed successfully and a non-NULL rsp parameter
111 : * was given, this parameter will be set to point to a buffer containing
112 : * the response parameters.
113 : *
114 : * @param opcode Command OpCode.
115 : * @param buf Command buffer or NULL (if no parameters).
116 : * @param rsp Place to store a reference to the command response. May
117 : * be NULL if the caller is not interested in the response
118 : * parameters. If non-NULL is passed the caller is responsible
119 : * for calling net_buf_unref() on the buffer when done parsing
120 : * it.
121 : *
122 : * @return 0 on success or negative error value on failure.
123 : */
124 1 : int bt_hci_cmd_send_sync(uint16_t opcode, struct net_buf *buf,
125 : struct net_buf **rsp);
126 :
127 : /** @brief Get connection handle for a connection.
128 : *
129 : * @param conn Connection object.
130 : * @param conn_handle Place to store the Connection handle.
131 : *
132 : * @return 0 on success or negative error value on failure.
133 : */
134 1 : int bt_hci_get_conn_handle(const struct bt_conn *conn, uint16_t *conn_handle);
135 :
136 : /** @brief Get connection given a connection handle.
137 : *
138 : * The caller gets a new reference to the connection object which must be
139 : * released with bt_conn_unref() once done using the object.
140 : *
141 : * @param handle The connection handle
142 : *
143 : * @returns The corresponding connection object on success.
144 : * NULL if it does not exist.
145 : */
146 1 : struct bt_conn *bt_hci_conn_lookup_handle(uint16_t handle);
147 :
148 : /** @brief Get advertising handle for an advertising set.
149 : *
150 : * @param adv Advertising set.
151 : * @param adv_handle Place to store the advertising handle.
152 : *
153 : * @return 0 on success or negative error value on failure.
154 : */
155 1 : int bt_hci_get_adv_handle(const struct bt_le_ext_adv *adv, uint8_t *adv_handle);
156 :
157 : /** @brief Get advertising set given an advertising handle
158 : *
159 : * @param handle The advertising handle
160 : *
161 : * @returns The corresponding advertising set on success,
162 : * NULL if it does not exist.
163 : */
164 1 : struct bt_le_ext_adv *bt_hci_adv_lookup_handle(uint8_t handle);
165 :
166 : /** @brief Get periodic advertising sync handle.
167 : *
168 : * @param sync Periodic advertising sync set.
169 : * @param sync_handle Place to store the periodic advertising sync handle.
170 : *
171 : * @return 0 on success or negative error value on failure.
172 : */
173 1 : int bt_hci_get_adv_sync_handle(const struct bt_le_per_adv_sync *sync, uint16_t *sync_handle);
174 :
175 : /** @brief Get periodic advertising sync given an periodic advertising sync handle.
176 : *
177 : * @param handle The periodic sync set handle
178 : *
179 : * @retval The corresponding periodic advertising sync set object on success,
180 : * NULL if it does not exist.
181 : */
182 1 : struct bt_le_per_adv_sync *bt_hci_per_adv_sync_lookup_handle(uint16_t handle);
183 :
184 : /** @brief Obtain the version string given a core version number.
185 : *
186 : * The core version of a controller can be obtained by issuing
187 : * the HCI Read Local Version Information command.
188 : *
189 : * See also the defines prefixed with BT_HCI_VERSION_.
190 : *
191 : * @param core_version The core version.
192 : *
193 : * @return Version string corresponding to the core version number.
194 : */
195 1 : const char *bt_hci_get_ver_str(uint8_t core_version);
196 :
197 : /** @typedef bt_hci_vnd_evt_cb_t
198 : * @brief Callback type for vendor handling of HCI Vendor-Specific Events.
199 : *
200 : * A function of this type is registered with bt_hci_register_vnd_evt_cb()
201 : * and will be called for any HCI Vendor-Specific Event.
202 : *
203 : * @param buf Buffer containing event parameters.
204 : *
205 : * @return true if the function handles the event or false to defer the
206 : * handling of this event back to the stack.
207 : */
208 1 : typedef bool bt_hci_vnd_evt_cb_t(struct net_buf_simple *buf);
209 :
210 : /** Register user callback for HCI Vendor-Specific Events
211 : *
212 : * @param cb Callback to be called when the stack receives a
213 : * HCI Vendor-Specific Event.
214 : *
215 : * @return 0 on success or negative error value on failure.
216 : */
217 1 : int bt_hci_register_vnd_evt_cb(bt_hci_vnd_evt_cb_t cb);
218 :
219 : /** @brief Get Random bytes from the LE Controller.
220 : *
221 : * Send the HCI_LE_Rand to the LE Controller as many times as required to
222 : * fill the provided @p buffer.
223 : *
224 : * @note This function is provided as a helper to gather an arbitrary number of
225 : * random bytes from an LE Controller using the HCI_LE_Rand command.
226 : *
227 : * @param buffer Buffer to fill with random bytes.
228 : * @param len Length of the buffer in bytes.
229 : *
230 : * @return 0 on success or negative error value on failure.
231 : */
232 1 : int bt_hci_le_rand(void *buffer, size_t len);
233 :
234 :
235 : #ifdef __cplusplus
236 : }
237 : #endif
238 :
239 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_HCI_H_ */
|
