Skip to content

Cherry pick hci deprecation #3043

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

Cherry pick hci deprecation #3043

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
14ae1e0
[nrf fromtree] Bluetooth: Host: Mark bt_hci_cmd_create() as deprecated
jhedberg Jun 19, 2025
596aada
[nrf fromtree] doc: migration-guide-4.2: Add note about bt_hci_cmd_cr…
jhedberg Jun 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions doc/releases/migration-guide-4.2.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -410,6 +410,10 @@ Bluetooth HCI
have been deprecated, but are still usable, with the exception that they can only be
called once per buffer.

* The :c:func:`bt_hci_cmd_create` function has been depracated and the new :c:func:`bt_hci_cmd_alloc`
function should be used instead. The new function takes no parameters because the command
sending functions have been updated to do the command header encoding.

Bluetooth Host
==============

Expand Down
8 changes: 5 additions & 3 deletions include/zephyr/bluetooth/hci.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,12 +56,14 @@
* of the parameters. Upon successful return the buffer is ready to have
* the parameters encoded into it.
*
* @deprecated Use bt_hci_cmd_alloc() instead.
*
* @param opcode Command OpCode.
* @param param_len Length of command parameters.
*
* @return Newly allocated buffer.
*/
struct net_buf *bt_hci_cmd_create(uint16_t opcode, uint8_t param_len);
__deprecated struct net_buf *bt_hci_cmd_create(uint16_t opcode, uint8_t param_len);

Check notice on line 66 in include/zephyr/bluetooth/hci.h

View workflow job for this annotation

GitHub Actions / Run compliance checks on patch series (PR)

You may want to run clang-format on this change 

include/zephyr/bluetooth/hci.h:66 
-  *
-  * This function allocates a new buffer for a HCI command. It is given
-  * the OpCode (encoded e.g. using the BT_OP macro) and the total length
-  * of the parameters. Upon successful return the buffer is ready to have
-  * the parameters encoded into it.
-  *
-  * @deprecated Use bt_hci_cmd_alloc() instead.
-  *
-  * @param opcode     Command OpCode.
-  * @param param_len  Length of command parameters.
-  *
-  * @return Newly allocated buffer.
-  */
+ *
+ * This function allocates a new buffer for a HCI command. It is given
+ * the OpCode (encoded e.g. using the BT_OP macro) and the total length
+ * of the parameters. Upon successful return the buffer is ready to have
+ * the parameters encoded into it.
+ *
+ * @deprecated Use bt_hci_cmd_alloc() instead.
+ *
+ * @param opcode     Command OpCode.
+ * @param param_len  Length of command parameters.
+ *
+ * @return Newly allocated buffer.
+ */

/** Allocate an HCI command buffer.
*
Expand All @@ -80,7 +82,7 @@
/** Send a HCI command asynchronously.
*
* This function is used for sending a HCI command asynchronously. It can
* either be called for a buffer created using bt_hci_cmd_create(), or
* either be called for a buffer created using bt_hci_cmd_alloc(), or
* if the command has no parameters a NULL can be passed instead. The
* sending of the command will happen asynchronously, i.e. upon successful
* return from this function the caller only knows that it was queued
Expand All @@ -99,7 +101,7 @@
/** Send a HCI command synchronously.
*
* This function is used for sending a HCI command synchronously. It can
* either be called for a buffer created using bt_hci_cmd_create(), or
* either be called for a buffer created using bt_hci_cmd_alloc(), or
* if the command has no parameters a NULL can be passed instead.
*
* The function will block until a Command Status or a Command Complete
Expand All @@ -119,7 +121,7 @@
*
* @return 0 on success or negative error value on failure.
*/
int bt_hci_cmd_send_sync(uint16_t opcode, struct net_buf *buf,

Check notice on line 124 in include/zephyr/bluetooth/hci.h

View workflow job for this annotation

GitHub Actions / Run compliance checks on patch series (PR)

You may want to run clang-format on this change 

include/zephyr/bluetooth/hci.h:124 
-  *
-  * This function is used for sending a HCI command asynchronously. It can
-  * either be called for a buffer created using bt_hci_cmd_alloc(), or
-  * if the command has no parameters a NULL can be passed instead. The
-  * sending of the command will happen asynchronously, i.e. upon successful
-  * return from this function the caller only knows that it was queued
-  * successfully.
-  *
-  * If synchronous behavior, and retrieval of the Command Complete parameters
-  * is desired, the bt_hci_cmd_send_sync() API should be used instead.
-  *
-  * @param opcode Command OpCode.
-  * @param buf    Command buffer or NULL (if no parameters).
-  *
-  * @return 0 on success or negative error value on failure.
-  */
+ *
+ * This function is used for sending a HCI command asynchronously. It can
+ * either be called for a buffer created using bt_hci_cmd_alloc(), or
+ * if the command has no parameters a NULL can be passed instead. The
+ * sending of the command will happen asynchronously, i.e. upon successful
+ * return from this function the caller only knows that it was queued
+ * successfully.
+ *
+ * If synchronous behavior, and retrieval of the Command Complete parameters
+ * is desired, the bt_hci_cmd_send_sync() API should be used instead.
+ *
+ * @param opcode Command OpCode.
+ * @param buf    Command buffer or NULL (if no parameters).
+ *
+ * @return 0 on success or negative error value on failure.
+ */
 int bt_hci_cmd_send(uint16_t opcode, struct net_buf *buf);
 
 /** Send a HCI command synchronously.
-  *
-  * This function is used for sending a HCI command synchronously. It can
-  * either be called for a buffer created using bt_hci_cmd_alloc(), or
-  * if the command has no parameters a NULL can be passed instead.
-  *
-  * The function will block until a Command Status or a Command Complete
-  * event is returned. If either of these have a non-zero status the function
-  * will return a negative error code and the response reference will not
-  * be set. If the command completed successfully and a non-NULL rsp parameter
-  * was given, this parameter will be set to point to a buffer containing
-  * the response parameters.
-  *
-  * @param opcode Command OpCode.
-  * @param buf    Command buffer or NULL (if no parameters).
-  * @param rsp    Place to store a reference to the command response. May
-  *               be NULL if the caller is not interested in the response
-  *               parameters. If non-NULL is passed the caller is responsible
-  *               for calling net_buf_unref() on the buffer when done parsing
-  *               it.
-  *
-  * @return 0 on success or negative error value on failure.
-  */
+ *
+ * This function is used for sending a HCI command synchronously. It can
+ * either be called for a buffer created using bt_hci_cmd_alloc(), or
+ * if the command has no parameters a NULL can be passed instead.
+ *
+ * The function will block until a Command Status or a Command Complete
+ * event is returned. If either of these have a non-zero status the function
+ * will return a negative error code and the response reference will not
+ * be set. If the command completed successfully and a non-NULL rsp parameter
+ * was given, this parameter will be set to point to a buffer containing
+ * the response parameters.
+ *
+ * @param opcode Command OpCode.
+ * @param buf    Command buffer or NULL (if no parameters).
+ * @param rsp    Place to store a reference to the command response. May
+ *               be NULL if the caller is not interested in the response
+ *               parameters. If non-NULL is passed the caller is responsible
+ *               for calling net_buf_unref() on the buffer when done parsing
+ *               it.
+ *
+ * @return 0 on success or negative error value on failure.
+ */
struct net_buf **rsp);

/** @brief Get connection handle for a connection.
Expand Down
Loading