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