Bluetooth HCI packet helpers

Bluetooth HCI packet helpers. More...

Data Structures
struct	bt_hci_pkt_cmd_rsp
	Decoded HCI command response. More...

Macros
#define	BT_HCI_PKT_CMD_HDR_SIZE   (sizeof(uint8_t) + BT_HCI_CMD_HDR_SIZE)
	Size of the prefix of an HCI command packet.
#define	BT_HCI_PKT_CMD_SIZE(param_len)
	Size of an HCI command packet with param_len bytes of parameters.
#define	BT_HCI_PKT_CMD_DEFINE(_name, _max_param_len)
	Define a buffer for an HCI command packet.
#define	BT_HCI_PKT_CMD_DEFINE_STATIC(_name, _max_param_len)
	Define a static buffer for an HCI command packet.

Functions
void	bt_hci_pkt_reset_cmd (struct net_buf_simple *buf)
	Reset a buffer for a new HCI command packet.
int	bt_hci_pkt_push_cmd_hdr (struct net_buf_simple *buf, uint16_t opcode)
	Push the packet indicator and command header of an HCI command packet.
int	bt_hci_pkt_pull_cmd_complete (struct net_buf_simple *buf, struct bt_hci_pkt_cmd_rsp *rsp)
	Pull an HCI_Command_Complete event.
int	bt_hci_pkt_pull_cmd_status (struct net_buf_simple *buf, struct bt_hci_pkt_cmd_rsp *rsp)
	Pull an HCI_Command_Status event.
int	bt_hci_pkt_parse_cmd_rsp (const uint8_t *pkt, size_t len, struct bt_hci_pkt_cmd_rsp *rsp)
	Parse an HCI command response from a complete HCI packet.

Detailed Description

Bluetooth HCI packet helpers.

Since

4.5

Version

0.1.0

Stateless helpers for framing HCI command packets and for parsing the HCI events that carry command responses, operating on net_buf_simple buffers and on packet bytes. They depend on neither the Bluetooth Host nor the HCI driver interface and can be used in any build type: by the Host, by HCI drivers (for example to perform vendor-specific controller initialization over the driver's own transport) and by controller-only applications.

Note

These are not general application APIs, even though the header lives in the application-visible include directory: the intended users are HCI drivers and Bluetooth stack internals. Applications that need to send HCI commands alongside a running Host use the higher-level bt_hci_cmd_alloc(), bt_hci_cmd_send() and bt_hci_cmd_send_sync() APIs of hci.h, which cooperate with the Host's command flow control.

Packets are handled in the form used throughout Zephyr: the HCI packet indicator (BT_HCI_H4_CMD, BT_HCI_H4_EVT, ...) is the first byte, followed by the packet header and the parameters. Parameters are encoded and decoded by the caller with the packed bt_hci_cp_* and bt_hci_rp_* structures and the net_buf_simple API, exactly as in the Bluetooth Host.

Macro Definition Documentation

BT_HCI_PKT_CMD_DEFINE

#define BT_HCI_PKT_CMD_DEFINE	(		_name,
			_max_param_len )

#include <hci_pkt.h>

Value:

Z_BT_HCI_PKT_CMD_DEFINE(_name, _max_param_len,)

Define a buffer for an HCI command packet.

Defines and initializes a net_buf_simple with storage for an HCI command packet carrying up to _max_param_len bytes of parameters. The buffer starts out empty, with headroom reserved for bt_hci_pkt_push_cmd_hdr(): parameters are added with the net_buf_simple API, after which the header is pushed in front of them.

To reuse the buffer for another command, or to prepare a buffer over other storage, use bt_hci_pkt_reset_cmd().

Parameters

_name	Name of the net_buf_simple object.
_max_param_len	Maximum number of parameter bytes the buffer holds.

BT_HCI_PKT_CMD_DEFINE_STATIC

#define BT_HCI_PKT_CMD_DEFINE_STATIC	(		_name,
			_max_param_len )

#include <hci_pkt.h>

Value:

Z_BT_HCI_PKT_CMD_DEFINE(_name, _max_param_len, static)

Define a static buffer for an HCI command packet.

Same as BT_HCI_PKT_CMD_DEFINE(), with static storage duration.

Parameters

_name	Name of the net_buf_simple object.
_max_param_len	Maximum number of parameter bytes the buffer holds.

BT_HCI_PKT_CMD_HDR_SIZE

#define BT_HCI_PKT_CMD_HDR_SIZE   (sizeof(uint8_t) + BT_HCI_CMD_HDR_SIZE)

#include <hci_pkt.h>

Size of the prefix of an HCI command packet.

The packet indicator followed by the HCI command header, which precede the command parameters. Equals the reservation the Bluetooth Host's command buffers use (see BT_BUF_CMD_SIZE); kept separate so that this header has no dependency on the Host's buffer API.

BT_HCI_PKT_CMD_SIZE

#define BT_HCI_PKT_CMD_SIZE

(

param_len

)

#include <hci_pkt.h>

Value:

(BT_HCI_PKT_CMD_HDR_SIZE + (param_len))

Size of an HCI command packet with param_len bytes of parameters.

Function Documentation

bt_hci_pkt_parse_cmd_rsp()

int bt_hci_pkt_parse_cmd_rsp	(	const uint8_t *	pkt,
		size_t	len,
		struct bt_hci_pkt_cmd_rsp *	rsp )

#include <hci_pkt.h>

Parse an HCI command response from a complete HCI packet.

Examines a complete HCI packet, starting with its packet indicator, and decodes it when it is an HCI_Command_Complete or HCI_Command_Status event, leaving the return parameters of the command in bt_hci_pkt_cmd_rsp::rp. Bytes beyond the length given in the event header are ignored, and the packet is not modified, so any received packet can be examined in place.

Parameters

pkt	Complete HCI packet.
len	Length of pkt in bytes.
rsp	Decoded response.

Return values

0	The packet is a command response.
-ENODATA	The packet is an HCI_Command_Complete for a command that carries no return parameters, not even the status; rsp is filled in with BT_HCI_ERR_UNSPECIFIED as status.
-ENOMSG	The packet is not a command response; rsp is unchanged.
-EINVAL	The packet is a malformed HCI event; rsp is unchanged.

bt_hci_pkt_pull_cmd_complete()

int bt_hci_pkt_pull_cmd_complete	(	struct net_buf_simple *	buf,
		struct bt_hci_pkt_cmd_rsp *	rsp )

#include <hci_pkt.h>

Pull an HCI_Command_Complete event.

Decodes the event parameters of an HCI_Command_Complete event from buf, which must be positioned at the start of the event parameters, i.e. after the HCI event header. On success the event parameters preceding the return parameters have been pulled, leaving buf positioned at the return parameters of the command, which start with the status (as the bt_hci_rp_* structures do).

Parameters

buf	Buffer positioned at the event parameters.
rsp	Decoded response.

Return values

0	Success; buf is positioned at the return parameters.
-ENODATA	The event responds to a command but carries no return parameters, not even the status; rsp is filled in with BT_HCI_ERR_UNSPECIFIED as status and buf is positioned as on success.
-EINVAL	The event is malformed; buf and rsp are unchanged.

bt_hci_pkt_pull_cmd_status()

int bt_hci_pkt_pull_cmd_status	(	struct net_buf_simple *	buf,
		struct bt_hci_pkt_cmd_rsp *	rsp )

#include <hci_pkt.h>

Pull an HCI_Command_Status event.

Decodes the event parameters of an HCI_Command_Status event from buf, which must be positioned at the start of the event parameters, i.e. after the HCI event header. On success the event parameters have been pulled.

Parameters

buf	Buffer positioned at the event parameters.
rsp	Decoded response.

Return values

0	Success; the event parameters have been pulled from buf.
-EINVAL	The event is malformed; buf and rsp are unchanged.

bt_hci_pkt_push_cmd_hdr()

int bt_hci_pkt_push_cmd_hdr	(	struct net_buf_simple *	buf,
		uint16_t	opcode )

#include <hci_pkt.h>

Push the packet indicator and command header of an HCI command packet.

Prepends BT_HCI_H4_CMD and an HCI command header with opcode to the contents of buf, which must hold the command parameters (if any). The parameter length in the header is derived from the length of buf, and the buffer then contains the complete command packet.

Parameters

buf	Buffer holding the command parameters, with at least BT_HCI_PKT_CMD_HDR_SIZE bytes of headroom, as set up by BT_HCI_PKT_CMD_DEFINE() or bt_hci_pkt_reset_cmd().
opcode	HCI command opcode.

Return values

0	Success; buf holds the complete command packet.
-EINVAL	buf has insufficient headroom for the prefix.
-EMSGSIZE	buf holds more parameter bytes than an HCI command can carry.

bt_hci_pkt_reset_cmd()

void bt_hci_pkt_reset_cmd

(

struct net_buf_simple *

buf

)

#include <hci_pkt.h>

Reset a buffer for a new HCI command packet.

Empties buf and reserves headroom for bt_hci_pkt_push_cmd_hdr(), so that command parameters can be added with the net_buf_simple API. Use it to reuse a buffer defined with BT_HCI_PKT_CMD_DEFINE(), or to prepare a net_buf_simple initialized over caller-provided storage (for example with net_buf_simple_init_with_data()). The storage must hold at least BT_HCI_PKT_CMD_HDR_SIZE bytes.

Parameters

buf	Buffer to reset.