Bluetooth HCI

Interfaces for Bluetooth Host Controller Interface (HCI). More...

Topics
	Bluetooth H:4 UART driver vendor extension interface
	Bluetooth H:4 UART driver vendor extension interface.
	Bluetooth HCI Driver Backend API
	Bluetooth HCI lockstep command helper
	Bluetooth HCI lockstep command helper.

Files
file	bluetooth.h
	Bluetooth HCI driver API.

Data Structures
struct	bt_hci_setup_params
	Parameters of the setup() driver API op. More...
struct	bt_hci_driver_config
	Common Bluetooth HCI driver configuration. More...

Macros
#define	BT_DT_HCI_QUIRK_OR(node_id, prop, idx)
#define	BT_DT_HCI_QUIRKS_GET(node_id)
#define	BT_DT_HCI_QUIRKS_INST_GET(inst)
#define	BT_DT_HCI_NAME_GET(node_id)
#define	BT_DT_HCI_NAME_INST_GET(inst)
#define	BT_PRIV_HCI_BUS_DEFAULT   (0)
#define	BT_DT_HCI_BUS_GET(node_id)
#define	BT_DT_HCI_BUS_INST_GET(inst)
#define	BT_DT_HCI_DRIVER_CONFIG_GET(node_id)
	Static initializer for bt_hci_driver_config struct.
#define	BT_DT_HCI_DRIVER_CONFIG_INST_GET(inst)
	Static initializer for bt_hci_driver_config struct from DT_DRV_COMPAT instance.

Enumerations
enum	{ BT_HCI_QUIRK_NO_RESET = BIT(0) , BT_HCI_QUIRK_NO_AUTO_DLE = BIT(1) , BT_HCI_QUIRK_NO_FLOW_CONTROL = BIT(2) }

Functions
static int	bt_hci_recv_err (const struct device *dev, struct net_buf *buf)
	Deliver an HCI packet from the driver.
static void	bt_hci_recv (const struct device *dev, struct net_buf *buf)
	Deliver an HCI packet from the driver.
static int	bt_hci_open (const struct device *dev, bt_hci_recv_t recv)
	Open the HCI transport.
static bool	bt_hci_can_close (const struct device *dev)
	Check whether the HCI transport can be closed.
static int	bt_hci_close (const struct device *dev)
	Close the HCI transport.
static int	bt_hci_send (const struct device *dev, struct net_buf *buf)
	Send HCI buffer to controller.
static int	bt_hci_setup (const struct device *dev, struct bt_hci_setup_params *params)
	HCI vendor-specific setup.
void	bt_hci_set_public_addr (const struct device *dev, const bt_addr_t *addr)
	Set the public identity address for the controller.
const bt_addr_t *	bt_hci_get_public_addr (const struct device *dev)
	Get the public identity address the driver is to configure.

Detailed Description

Interfaces for Bluetooth Host Controller Interface (HCI).

Since

3.7

Version

0.3.0

Macro Definition Documentation

BT_DT_HCI_BUS_GET

#define BT_DT_HCI_BUS_GET

(

node_id

)

#include <zephyr/drivers/bluetooth.h>

Value:

DT_ENUM_IDX_OR(node_id, bt_hci_bus, BT_PRIV_HCI_BUS_DEFAULT)

BT_DT_HCI_BUS_INST_GET

#define BT_DT_HCI_BUS_INST_GET

(

inst

)

#include <zephyr/drivers/bluetooth.h>

Value:

BT_DT_HCI_BUS_GET(DT_DRV_INST(inst))

BT_DT_HCI_DRIVER_CONFIG_GET

#define BT_DT_HCI_DRIVER_CONFIG_GET

(

node_id

)

#include <zephyr/drivers/bluetooth.h>

Value:

{                                                                                       \
        .quirks = (uint32_t)BT_DT_HCI_QUIRKS_GET(node_id),                                \
}

Static initializer for bt_hci_driver_config struct.

Parameters

node_id

Devicetree node identifier

BT_DT_HCI_DRIVER_CONFIG_INST_GET

#define BT_DT_HCI_DRIVER_CONFIG_INST_GET

(

inst

)

#include <zephyr/drivers/bluetooth.h>

Value:

BT_DT_HCI_DRIVER_CONFIG_GET(DT_DRV_INST(inst))

Static initializer for bt_hci_driver_config struct from DT_DRV_COMPAT instance.

Parameters

inst	DT_DRV_COMPAT instance number

See also

BT_DT_HCI_DRIVER_CONFIG_GET()

BT_DT_HCI_NAME_GET

#define BT_DT_HCI_NAME_GET

(

node_id

)

#include <zephyr/drivers/bluetooth.h>

Value:

DT_PROP_OR(node_id, bt_hci_name, "HCI")

BT_DT_HCI_NAME_INST_GET

#define BT_DT_HCI_NAME_INST_GET

(

inst

)

#include <zephyr/drivers/bluetooth.h>

Value:

BT_DT_HCI_NAME_GET(DT_DRV_INST(inst))

BT_DT_HCI_QUIRK_OR

#define BT_DT_HCI_QUIRK_OR	(		node_id,
			prop,
			idx )

#include <zephyr/drivers/bluetooth.h>

Value:

UTIL_CAT(BT_HCI_QUIRK_, DT_STRING_UPPER_TOKEN_BY_IDX(node_id, prop, idx))

BT_DT_HCI_QUIRKS_GET

#define BT_DT_HCI_QUIRKS_GET

(

node_id

)

#include <zephyr/drivers/bluetooth.h>

Value:

COND_CODE_1(DT_NODE_HAS_PROP(node_id, bt_hci_quirks), \
(DT_FOREACH_PROP_ELEM_SEP(node_id, \
                          bt_hci_quirks, \
                          BT_DT_HCI_QUIRK_OR, \
                          (|))), \
(0))

BT_DT_HCI_QUIRKS_INST_GET

#define BT_DT_HCI_QUIRKS_INST_GET

(

inst

)

#include <zephyr/drivers/bluetooth.h>

Value:

BT_DT_HCI_QUIRKS_GET(DT_DRV_INST(inst))

BT_PRIV_HCI_BUS_DEFAULT

#define BT_PRIV_HCI_BUS_DEFAULT   (0)

#include <zephyr/drivers/bluetooth.h>

Enumeration Type Documentation

anonymous enum

anonymous enum

#include <zephyr/drivers/bluetooth.h>

Enumerator
BT_HCI_QUIRK_NO_RESET
BT_HCI_QUIRK_NO_AUTO_DLE
BT_HCI_QUIRK_NO_FLOW_CONTROL	The controller advertises the controller to host flow control commands as supported but does not accept them. The host treats the feature as not supported.

Function Documentation

bt_hci_can_close()

bool bt_hci_can_close ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/bluetooth.h>

Check whether the HCI transport can be closed.

Closing the transport is an optional driver operation. This tells its user up front whether bt_hci_close() can work, for example before it does something that only makes sense if the transport is closed afterwards.

Parameters

dev	HCI device

Return values

true	The driver supports closing the transport.
false	The driver does not support closing the transport.

bt_hci_close()

int bt_hci_close ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/bluetooth.h>

Close the HCI transport.

Closes the HCI transport. When it succeeds, this function must not return until the transport is closed: the driver then no longer calls the recv callback, and the transport can be opened again with bt_hci_open(). When the function fails, the transport is still open and can be used as before.

The function must not be called while a bt_hci_send() call is in progress, nor while another call to it, or to bt_hci_open(), is in progress, and bt_hci_send() must not be called while it runs. It must not be called from the recv callback, so that a driver is free to stop the thread it delivers its data from. It may block, and is called from thread context.

The transport must be open, see bt_hci_send().

Parameters

dev	HCI device

Returns

0 on success or negative POSIX error number on failure.

Return values

-ENOSYS

The driver does not support closing the transport.

bt_hci_get_public_addr()

const bt_addr_t * bt_hci_get_public_addr

(

const struct device *

dev

)

#include <zephyr/drivers/bluetooth.h>

Get the public identity address the driver is to configure.

Returns the address stored with bt_hci_set_public_addr(), for the driver to write into the controller while opening the transport. It does not query the controller.

"No address" is BT_ADDR_ANY and not BT_ADDR_NONE, even though the name of the latter suggests it. BT_ADDR_ANY is the address part of BT_ADDR_LE_ANY, with which the Host marks an identity that has no address, and it is what the setup() op receives in bt_hci_setup_params::public_addr when there is no public identity, so a driver has one check whichever way it gets the address. It is also the all-zero address, so driver data that has never been written already reads as "no address". This function cannot fail, so the driver compares the address it returns with BT_ADDR_ANY, using bt_addr_eq(), before it uses it.

Attention

Available only when the following Kconfig option is enabled: CONFIG_BT_HCI_SET_PUBLIC_ADDR.

Parameters

dev	HCI device

Returns

The address to configure, never NULL, valid until the next bt_hci_set_public_addr() call for the device. It compares equal to BT_ADDR_ANY when no public address has been set, or it has been cleared.

bt_hci_open()

int bt_hci_open ( const struct device * dev, bt_hci_recv_t recv )

inlinestatic

#include <zephyr/drivers/bluetooth.h>

Open the HCI transport.

Opens the HCI transport for operation. This function must not return until the transport is ready for operation, meaning it is safe to start calling the send() handler. It may block, and is called from thread context.

When this function fails, the transport is closed: the driver has stopped what the call had started, no longer calls the recv callback, and bt_hci_close() is not called for it. The exception is -EALREADY, which this function returns without calling the driver when the transport is open already, and which leaves it open.

A transport that has been closed with bt_hci_close() can be opened again. The function must not be called while another call to it, or to bt_hci_close(), is in progress.

Parameters

dev	HCI device
recv	This is callback through which the HCI driver provides the host with data from the controller. The callback is expected to be called from thread context, and it may be called already before bt_hci_open() returns.

Returns

0 on success or negative POSIX error number on failure.

Return values

-EALREADY

The HCI transport is already open.

bt_hci_recv()

void bt_hci_recv ( const struct device * dev, struct net_buf * buf )

inlinestatic

#include <zephyr/drivers/bluetooth.h>

Deliver an HCI packet from the driver.

This function is the same as bt_hci_recv_err except that it will internally handle error situations and always consume the buffer reference.

Parameters

dev	HCI device
buf	Buffer containing data received from the controller.

bt_hci_recv_err()

int bt_hci_recv_err ( const struct device * dev, struct net_buf * buf )

inlinestatic

#include <zephyr/drivers/bluetooth.h>

Deliver an HCI packet from the driver.

This function is called by the HCI driver to deliver data received from the controller to the host. The buffer contains the raw HCI packet, including the packet type prefix encoded in the H:4 format.

If the function returns 0 (success) the reference to buf was moved to the higher layer (e.g. host stack). On error, the caller (HCI driver) still owns the reference and is responsible for eventually calling net_buf_unref on it.

Parameters

dev	HCI device
buf	Buffer containing data received from the controller.

Returns

0 on success or negative POSIX error number on failure.

Return values

-ENOTCONN

The HCI transport is not open.

bt_hci_send()

int bt_hci_send ( const struct device * dev, struct net_buf * buf )

inlinestatic

#include <zephyr/drivers/bluetooth.h>

Send HCI buffer to controller.

Send an HCI packet to the controller. The packet type is encoded as H:4, i.e. the UART transport encoding, as a prefix to the actual payload. This means that HCI drivers that use H:4 as their native encoding don't need to do any special handling of the packet type.

If the function returns 0 (success) the reference to buf was moved to the HCI driver. On error, the caller still owns the reference and is responsible for eventually calling net_buf_unref on it.

The transport must be open: the function may only be called after bt_hci_open() has returned successfully, and neither while a bt_hci_close() call is in progress nor after one has succeeded. There is no query for that: the one user of the transport knows it from its own calls. Calling the function for a transport that is not open is an error of the caller with undefined results, which a driver is not required to detect. Nor may the function be called while another call to it is in progress.

Note

This function must only be called from a cooperative thread.

Parameters

dev	HCI device
buf	Buffer containing data to be sent to the controller.

Returns

0 on success or negative POSIX error number on failure.

bt_hci_set_public_addr()

void bt_hci_set_public_addr	(	const struct device *	dev,
		const bt_addr_t *	addr )

#include <zephyr/drivers/bluetooth.h>

Set the public identity address for the controller.

Stores the public address the driver should configure in the controller.

The Bluetooth Host calls this before bt_hci_open() when the application has created a public identity with bt_id_create(). A controller-only application can likewise call it before opening the transport.

The driver reads the address with bt_hci_get_public_addr() and applies it while opening the transport, or in its setup() implementation.

Attention

Available only when the following Kconfig option is enabled: CONFIG_BT_HCI_SET_PUBLIC_ADDR.

Parameters

dev	HCI device
addr	Public address, or BT_ADDR_ANY to clear a previously set one. BT_ADDR_NONE does not clear it, see bt_hci_get_public_addr().

bt_hci_setup()

int bt_hci_setup ( const struct device * dev, struct bt_hci_setup_params * params )

inlinestatic

#include <zephyr/drivers/bluetooth.h>

HCI vendor-specific setup.

Executes vendor-specific commands sequence to initialize BT Controller before BT Host executes Reset sequence. This is normally called directly after bt_hci_open().

Note

CONFIG_BT_HCI_SETUP must be selected for this field to be available.

Deprecated

A driver performs its vendor-specific initialization inside open(), over its own transport. See the 4.5 migration guide.

Returns

0 on success or negative POSIX error number on failure.