1 /* 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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_ */ 220
