Oveview

Lightweight proxy for augmenting Bluetooth functionality. Main docs: https://pigweed.dev/pw_bluetooth_proxy.

Classes
class	pw::bluetooth::proxy::H4PacketInterface

class	pw::bluetooth::proxy::H4PacketWithHci
	H4PacketWithHci is an H4Packet backed by an HCI buffer. More...

class	pw::bluetooth::proxy::H4PacketWithH4
	H4PacketWithH4 is an H4Packet backed by an H4 buffer. More...

class	pw::bluetooth::proxy::ProxyHost

Functions
	pw::bluetooth::proxy::H4PacketInterface::H4PacketInterface (const H4PacketInterface &other)=delete

	pw::bluetooth::proxy::H4PacketInterface::H4PacketInterface (H4PacketInterface &&other)=default

H4PacketInterface &	pw::bluetooth::proxy::H4PacketInterface::operator= (H4PacketInterface &&other)=default

virtual emboss::H4PacketType	pw::bluetooth::proxy::H4PacketInterface::GetH4Type ()=0

virtual void	pw::bluetooth::proxy::H4PacketInterface::SetH4Type (emboss::H4PacketType)=0
	Sets HCI packet type indicator.

virtual pw::span< uint8_t >	pw::bluetooth::proxy::H4PacketInterface::GetHciSpan ()=0

H4PacketInterface &	pw::bluetooth::proxy::H4PacketInterface::operator= (const H4PacketInterface &other)=default

	pw::bluetooth::proxy::H4PacketWithHci::H4PacketWithHci (emboss::H4PacketType h4_type, pw::span< uint8_t > hci_span)

	pw::bluetooth::proxy::H4PacketWithHci::H4PacketWithHci (pw::span< uint8_t > h4_span)

	pw::bluetooth::proxy::H4PacketWithHci::H4PacketWithHci (const H4PacketWithHci &other)=delete

	pw::bluetooth::proxy::H4PacketWithHci::H4PacketWithHci (H4PacketWithHci &&other)=default

H4PacketWithHci &	pw::bluetooth::proxy::H4PacketWithHci::operator= (H4PacketWithHci &&other)=default

emboss::H4PacketType	pw::bluetooth::proxy::H4PacketWithHci::GetH4Type () final

void	pw::bluetooth::proxy::H4PacketWithHci::SetH4Type (emboss::H4PacketType h4_type) final
	Sets HCI packet type indicator.

pw::span< uint8_t >	pw::bluetooth::proxy::H4PacketWithHci::GetHciSpan () final

	pw::bluetooth::proxy::H4PacketWithH4::H4PacketWithH4 (pw::span< uint8_t > h4_span)

	pw::bluetooth::proxy::H4PacketWithH4::H4PacketWithH4 (pw::span< uint8_t > h4_span, pw::Function< void(const uint8_t *buffer)> &&release_fn)
	release_fn (if callable) will be called when H4PacketWithH4 is destructed.

	pw::bluetooth::proxy::H4PacketWithH4::H4PacketWithH4 (emboss::H4PacketType h4_type, pw::span< uint8_t > h4_span)

	pw::bluetooth::proxy::H4PacketWithH4::H4PacketWithH4 (const H4PacketWithH4 &other)=delete

H4PacketWithH4 &	pw::bluetooth::proxy::H4PacketWithH4::operator= (const H4PacketWithH4 &other)=delete

	pw::bluetooth::proxy::H4PacketWithH4::H4PacketWithH4 (H4PacketWithH4 &&other)

H4PacketWithH4 &	pw::bluetooth::proxy::H4PacketWithH4::operator= (H4PacketWithH4 &&other)

emboss::H4PacketType	pw::bluetooth::proxy::H4PacketWithH4::GetH4Type () final

void	pw::bluetooth::proxy::H4PacketWithH4::SetH4Type (emboss::H4PacketType h4_type) final
	Sets HCI packet type indicator.

bool	pw::bluetooth::proxy::H4PacketWithH4::HasReleaseFn ()

pw::Function< void(const uint8_t *)>	pw::bluetooth::proxy::H4PacketWithH4::ResetAndReturnReleaseFn ()

pw::span< uint8_t >	pw::bluetooth::proxy::H4PacketWithH4::GetHciSpan () final

pw::span< uint8_t >	pw::bluetooth::proxy::H4PacketWithH4::GetH4Span ()

	pw::bluetooth::proxy::ProxyHost::ProxyHost (pw::Function< void(H4PacketWithHci &&packet)> &&send_to_host_fn, pw::Function< void(H4PacketWithH4 &&packet)> &&send_to_controller_fn, uint16_t le_acl_credits_to_reserve, uint16_t br_edr_acl_credits_to_reserve)

	pw::bluetooth::proxy::ProxyHost::ProxyHost (const ProxyHost &)=delete

ProxyHost &	pw::bluetooth::proxy::ProxyHost::operator= (const ProxyHost &)=delete

	pw::bluetooth::proxy::ProxyHost::ProxyHost (ProxyHost &&)=delete

ProxyHost &	pw::bluetooth::proxy::ProxyHost::operator= (ProxyHost &&)=delete

	pw::bluetooth::proxy::ProxyHost::~ProxyHost ()

void	pw::bluetooth::proxy::ProxyHost::HandleH4HciFromHost (H4PacketWithH4 &&h4_packet)

void	pw::bluetooth::proxy::ProxyHost::HandleH4HciFromController (H4PacketWithHci &&h4_packet)

void	pw::bluetooth::proxy::ProxyHost::Reset ()

void	pw::bluetooth::proxy::ProxyHost::RegisterL2capStatusDelegate (L2capStatusDelegate &delegate)

void	pw::bluetooth::proxy::ProxyHost::UnregisterL2capStatusDelegate (L2capStatusDelegate &delegate)

pw::Result< L2capCoc >	pw::bluetooth::proxy::ProxyHost::AcquireL2capCoc (pw::multibuf::MultiBufAllocator &rx_multibuf_allocator, uint16_t connection_handle, L2capCoc::CocConfig rx_config, L2capCoc::CocConfig tx_config, Function< void(multibuf::MultiBuf &&payload)> &&receive_fn, ChannelEventCallback &&event_fn)

pw::Status	pw::bluetooth::proxy::ProxyHost::SendAdditionalRxCredits (uint16_t connection_handle, uint16_t local_cid, uint16_t additional_rx_credits)

pw::Result< BasicL2capChannel >	pw::bluetooth::proxy::ProxyHost::AcquireBasicL2capChannel (multibuf::MultiBufAllocator &rx_multibuf_allocator, uint16_t connection_handle, uint16_t local_cid, uint16_t remote_cid, AclTransportType transport, OptionalPayloadReceiveCallback &&payload_from_controller_fn, OptionalPayloadReceiveCallback &&payload_from_host_fn, ChannelEventCallback &&event_fn)

pw::Result< GattNotifyChannel >	pw::bluetooth::proxy::ProxyHost::AcquireGattNotifyChannel (int16_t connection_handle, uint16_t attribute_handle, ChannelEventCallback &&event_fn)

pw::Result< RfcommChannel >	pw::bluetooth::proxy::ProxyHost::AcquireRfcommChannel (multibuf::MultiBufAllocator &rx_multibuf_allocator, uint16_t connection_handle, RfcommChannel::Config rx_config, RfcommChannel::Config tx_config, uint8_t channel_number, Function< void(multibuf::MultiBuf &&payload)> &&payload_from_controller_fn, ChannelEventCallback &&event_fn)

bool	pw::bluetooth::proxy::ProxyHost::HasSendLeAclCapability () const

bool	pw::bluetooth::proxy::ProxyHost::HasSendBrEdrAclCapability () const

uint16_t	pw::bluetooth::proxy::ProxyHost::GetNumFreeLeAclPackets () const

uint16_t	pw::bluetooth::proxy::ProxyHost::GetNumFreeBrEdrAclPackets () const

static constexpr size_t	pw::bluetooth::proxy::ProxyHost::GetNumSimultaneousAclSendsSupported ()

static constexpr size_t	pw::bluetooth::proxy::ProxyHost::GetMaxAclSendSize ()
	Returns the max LE ACL packet size supported to be sent.

static constexpr size_t	pw::bluetooth::proxy::ProxyHost::GetMaxNumAclConnections ()
	Returns the max number of simultaneous LE ACL connections supported.

Variables
static constexpr std::uint8_t	pw::bluetooth::proxy::H4PacketInterface::kH4PacketIndicatorSize = 1

Function Documentation

◆ AcquireBasicL2capChannel()

pw::Result< BasicL2capChannel > pw::bluetooth::proxy::ProxyHost::AcquireBasicL2capChannel	(	multibuf::MultiBufAllocator &	rx_multibuf_allocator,
		uint16_t	connection_handle,
		uint16_t	local_cid,
		uint16_t	remote_cid,
		AclTransportType	transport,
		OptionalPayloadReceiveCallback &&	payload_from_controller_fn,
		OptionalPayloadReceiveCallback &&	payload_from_host_fn,
		ChannelEventCallback &&	event_fn
	)

Returns an L2CAP channel operating in basic mode that supports writing to and reading from a remote peer.

Parameters

[in]	rx_multibuf_allocator	Provides the allocator the channel will use for its Rx buffers (for both queueing and returning to the client).
[in]	connection_handle	The connection handle of the remote peer.
[in]	local_cid	L2CAP channel ID of the local endpoint.
[in]	remote_cid	L2CAP channel ID of the remote endpoint.
[in]	transport	Logical link transport type.
[in]	payload_from_controller_fn	Read callback to be invoked on Rx SDUs. Return value of passed-in multibuf indicates the packet should be forwarded on to host.
[in]	payload_from_host_fn	Read callback to be invoked on Tx SDUs. Return value of passed-in multibuf indicates the packet should be forwarded on to the controller.
[in]	event_fn	Handle asynchronous events such as errors encountered by the channel. See `l2cap_channel_common.h`.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
*   INVALID_ARGUMENT: If arguments are invalid (check logs).
*   UNAVAILABLE:      If channel could not be created because no memory was
*                     available to accommodate an additional ACL connection.
*

◆ AcquireGattNotifyChannel()

pw::Result< GattNotifyChannel > pw::bluetooth::proxy::ProxyHost::AcquireGattNotifyChannel	(	int16_t	connection_handle,
		uint16_t	attribute_handle,
		ChannelEventCallback &&	event_fn
	)

Returns a GATT Notify channel channel that supports sending notifications to a particular connection handle and attribute.

Parameters

[in]	connection_handle	The connection handle of the peer to notify. Maximum valid connection handle is 0x0EFF.
[in]	attribute_handle	The attribute handle the notify should be sent on. Cannot be 0.
[in]	event_fn	Handle asynchronous events such as errors and flow control events encountered by the channel. See `l2cap_channel_common.h`.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
*   INVALID_ARGUMENT: If arguments are invalid (check logs).
*   UNAVAILABLE:      If channel could not be created because no memory was
*                     available to accommodate an additional ACL connection.
*

◆ AcquireL2capCoc()

pw::Result< L2capCoc > pw::bluetooth::proxy::ProxyHost::AcquireL2capCoc	(	pw::multibuf::MultiBufAllocator &	rx_multibuf_allocator,
		uint16_t	connection_handle,
		L2capCoc::CocConfig	rx_config,
		L2capCoc::CocConfig	tx_config,
		Function< void(multibuf::MultiBuf &&payload)> &&	receive_fn,
		ChannelEventCallback &&	event_fn
	)

Returns an L2CAP connection-oriented channel that supports writing to and reading from a remote peer.

Parameters

[in]	rx_multibuf_allocator	Provides the allocator the channel will use for its Rx buffers (for both queueing and returning to the client).
[in]	connection_handle	The connection handle of the remote peer.
[in]	rx_config	Parameters applying to reading packets. See `l2cap_coc.h` for details.
[in]	tx_config	Parameters applying to writing packets. See `l2cap_coc.h` for details.
[in]	receive_fn	Read callback to be invoked on Rx SDUs.
[in]	event_fn	Handle asynchronous events such as errors and flow control events encountered by the channel. See `l2cap_channel_common.h`.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
*   INVALID_ARGUMENT: If arguments are invalid (check logs).
*   UNAVAILABLE:      If channel could not be created because no memory was
*                     available to accommodate an additional ACL connection.
*

◆ AcquireRfcommChannel()

pw::Result< RfcommChannel > pw::bluetooth::proxy::ProxyHost::AcquireRfcommChannel	(	multibuf::MultiBufAllocator &	rx_multibuf_allocator,
		uint16_t	connection_handle,
		RfcommChannel::Config	rx_config,
		RfcommChannel::Config	tx_config,
		uint8_t	channel_number,
		Function< void(multibuf::MultiBuf &&payload)> &&	payload_from_controller_fn,
		ChannelEventCallback &&	event_fn
	)

Returns an RFCOMM channel that supports writing to and reading from a remote peer.

Parameters

[in]	rx_multibuf_allocator	Provides the allocator the channel will use for its Rx buffers (for both queueing and returning to the client).
[in]	connection_handle	The connection handle of the remote peer.
[in]	rx_config	Parameters applying to reading packets. See `rfcomm_channel.h` for details.
[in]	tx_config	Parameters applying to writing packets. See `rfcomm_channel.h` for details.
[in]	channel_number	RFCOMM channel number to use.
[in]	payload_from_controller_fn	Read callback to be invoked on Rx frames.
[in]	event_fn	Handle asynchronous events such as errors encountered by the channel. See `l2cap_channel_common.h`.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
*   INVALID_ARGUMENT: If arguments are invalid (check logs).
*   UNAVAILABLE: If channel could not be created.
*

◆ GetH4Type() [1/3]

emboss::H4PacketType pw::bluetooth::proxy::H4PacketWithHci::GetH4Type ( )

inlinefinalvirtual

Returns HCI packet type indicator as defined in BT Core Spec Version 5.4 | Vol 4, Part A, Section 2.

Implements pw::bluetooth::proxy::H4PacketInterface.

◆ GetH4Type() [2/3]

emboss::H4PacketType pw::bluetooth::proxy::H4PacketWithH4::GetH4Type ( )

inlinefinalvirtual

Returns HCI packet type indicator as defined in BT Core Spec Version 5.4 | Vol 4, Part A, Section 2.

Implements pw::bluetooth::proxy::H4PacketInterface.

◆ GetH4Type() [3/3]

virtual emboss::H4PacketType pw::bluetooth::proxy::H4PacketInterface::GetH4Type ( )

pure virtual

Returns HCI packet type indicator as defined in BT Core Spec Version 5.4 | Vol 4, Part A, Section 2.

Implemented in pw::bluetooth::proxy::H4PacketWithHci, and pw::bluetooth::proxy::H4PacketWithH4.

◆ GetHciSpan() [1/3]

pw::span< uint8_t > pw::bluetooth::proxy::H4PacketWithHci::GetHciSpan ( )

inlinefinalvirtual

Returns pw::span of HCI packet as defined in BT Core Spec Version 5.4 | Vol 4, Part E, Section 5.4.

Implements pw::bluetooth::proxy::H4PacketInterface.

◆ GetHciSpan() [2/3]

pw::span< uint8_t > pw::bluetooth::proxy::H4PacketWithH4::GetHciSpan ( )

inlinefinalvirtual

Returns pw::span of HCI packet as defined in BT Core Spec Version 5.4 | Vol 4, Part E, Section 5.4.

Implements pw::bluetooth::proxy::H4PacketInterface.

◆ GetHciSpan() [3/3]

virtual pw::span< uint8_t > pw::bluetooth::proxy::H4PacketInterface::GetHciSpan ( )

pure virtual

Returns pw::span of HCI packet as defined in BT Core Spec Version 5.4 | Vol 4, Part E, Section 5.4.

Implemented in pw::bluetooth::proxy::H4PacketWithHci, and pw::bluetooth::proxy::H4PacketWithH4.

◆ GetNumFreeBrEdrAclPackets()

uint16_t pw::bluetooth::proxy::ProxyHost::GetNumFreeBrEdrAclPackets ( ) const

Returns the number of available BR/EDR ACL send credits for the proxy. Can be zero if the controller has not yet been initialized by the host.

◆ GetNumFreeLeAclPackets()

uint16_t pw::bluetooth::proxy::ProxyHost::GetNumFreeLeAclPackets ( ) const

Returns the number of available LE ACL send credits for the proxy. Can be zero if the controller has not yet been initialized by the host.

◆ GetNumSimultaneousAclSendsSupported()

static constexpr size_t pw::bluetooth::proxy::ProxyHost::GetNumSimultaneousAclSendsSupported ( )

inlinestaticconstexpr

Returns the max number of LE ACL sends that can be in-flight at one time. That is, ACL packets that have been sent and not yet released.

◆ HandleH4HciFromController()

void pw::bluetooth::proxy::ProxyHost::HandleH4HciFromController ( H4PacketWithHci && h4_packet )

Called by container to ask proxy to handle a H4 packet sent from the controller side towards the host side. Proxy will in turn call the send_to_host_fn provided during construction to pass the packet on to the host. Some packets may be modified, added, or removed.

To support all of its current functionality, the proxy host needs at least the following from-controller packets passed through it. It will pass on all other packets, so containers can choose to just pass all from-controller packets through the proxy host.

All packets of this type:

L2CAP over ACL packets (specifically those addressed to channels managed by the proxy host, including signaling packets)

HCI_Command_Complete events (7.7.14) containing return parameters for these commands:

HCI_LE_Read_Buffer_Size [v1] command (7.8.2)
HCI_LE_Read_Buffer_Size [v2] command (7.8.2)

These HCI event packets:

HCI_Number_Of_Completed_Packets event (7.7.19)
HCI_Disconnection_Complete event (7.7.5)

Container is required to call this function synchronously (one packet at a time).

◆ HandleH4HciFromHost()

void pw::bluetooth::proxy::ProxyHost::HandleH4HciFromHost ( H4PacketWithH4 && h4_packet )

Called by container to ask proxy to handle a H4 HCI packet sent from the host side towards the controller side. Proxy will in turn call the send_to_controller_fn provided during construction to pass the packet on to the controller. Some packets may be modified, added, or removed.

The proxy host currently does not require any from-host packets to support its current functionality. It will pass on all packets, so containers can choose to just pass all from-host packets through it.

Container is required to call this function synchronously (one packet at a time).

◆ HasSendBrEdrAclCapability()

bool pw::bluetooth::proxy::ProxyHost::HasSendBrEdrAclCapability ( ) const

Indicates whether the proxy has the capability of sending BR/EDR ACL packets. Note that this indicates intention, so it can be true even if the proxy has not yet or has been unable to reserve credits from the host.

◆ HasSendLeAclCapability()

bool pw::bluetooth::proxy::ProxyHost::HasSendLeAclCapability ( ) const

Indicates whether the proxy has the capability of sending LE ACL packets. Note that this indicates intention, so it can be true even if the proxy has not yet or has been unable to reserve credits from the host.

◆ ProxyHost()

pw::bluetooth::proxy::ProxyHost::ProxyHost	(	pw::Function< void(H4PacketWithHci &&packet)> &&	send_to_host_fn,
		pw::Function< void(H4PacketWithH4 &&packet)> &&	send_to_controller_fn,
		uint16_t	le_acl_credits_to_reserve,
		uint16_t	br_edr_acl_credits_to_reserve
	)

Creates an ProxyHost that will process HCI packets.

Parameters

[in]	send_to_host_fn	Callback that will be called when proxy wants to send HCI packet towards the host.
[in]	send_to_controller_fn	- Callback that will be called when proxy wants to send HCI packet towards the controller.
[in]	le_acl_credits_to_reserve	- How many buffers to reserve for the proxy out of any LE ACL buffers received from controller.
[in]	br_edr_acl_credits_to_reserve	- How many buffers to reserve for the proxy out of any BR/EDR ACL buffers received from controller.

◆ RegisterL2capStatusDelegate()

void pw::bluetooth::proxy::ProxyHost::RegisterL2capStatusDelegate ( L2capStatusDelegate & delegate )

Register for notifications of connection and disconnection for a particular L2cap service identified by its PSM.

Parameters

[in] delegate A delegate that will be notified when a successful L2cap connection is made on its PSM. Note: This must outlive the ProxyHost.

◆ Reset()

void pw::bluetooth::proxy::ProxyHost::Reset ( )

Called when an HCI_Reset Command packet is observed. Proxy resets its internal state. Deregisters all channels, and if any channels are not yet closed, closes them and sends L2capChannelEvent::kReset.

May also be called by container to notify proxy that the Bluetooth system is being otherwise reset.

Warning: Outstanding H4 packets are not invalidated upon reset. If they are destructed post-reset, packets generated post-reset are liable to be overwritten prematurely.

◆ SendAdditionalRxCredits()

pw::Status pw::bluetooth::proxy::ProxyHost::SendAdditionalRxCredits	(	uint16_t	connection_handle,
		uint16_t	local_cid,
		uint16_t	additional_rx_credits
	)

TODO: https://pwbug.dev/380076024 - Delete after downstream client uses this method on L2capCoc.

Deprecated:: Use L2capCoc::SendAdditionalRxCredits instead.

◆ SetH4Type() [1/3]

void pw::bluetooth::proxy::H4PacketWithHci::SetH4Type ( emboss::H4PacketType )

inlinefinalvirtual

Sets HCI packet type indicator.

Implements pw::bluetooth::proxy::H4PacketInterface.

◆ SetH4Type() [2/3]

void pw::bluetooth::proxy::H4PacketWithH4::SetH4Type ( emboss::H4PacketType )

inlinefinalvirtual

Sets HCI packet type indicator.

Implements pw::bluetooth::proxy::H4PacketInterface.

◆ SetH4Type() [3/3]

virtual void pw::bluetooth::proxy::H4PacketInterface::SetH4Type ( emboss::H4PacketType )

pure virtual

Sets HCI packet type indicator.

Implemented in pw::bluetooth::proxy::H4PacketWithHci, and pw::bluetooth::proxy::H4PacketWithH4.

◆ UnregisterL2capStatusDelegate()

void pw::bluetooth::proxy::ProxyHost::UnregisterL2capStatusDelegate ( L2capStatusDelegate & delegate )

Unregister a service delegate.

Parameters

[in] delegate The delegate to unregister. Must have been previously registered.

◆ ~ProxyHost()

pw::bluetooth::proxy::ProxyHost::~ProxyHost ( )

Deregisters all channels, and if any channels are not yet closed, closes them and sends L2capChannelEvent::kChannelClosedByOther.

Oveview

Classes

Functions

Variables

Function Documentation

◆ AcquireBasicL2capChannel()

◆ AcquireGattNotifyChannel()

◆ AcquireL2capCoc()

◆ AcquireRfcommChannel()

◆ GetH4Type() [1/3]

◆ GetH4Type() [2/3]

◆ GetH4Type() [3/3]

◆ GetHciSpan() [1/3]

◆ GetHciSpan() [2/3]

◆ GetHciSpan() [3/3]

◆ GetNumFreeBrEdrAclPackets()

◆ GetNumFreeLeAclPackets()

◆ GetNumSimultaneousAclSendsSupported()

◆ HandleH4HciFromController()

◆ HandleH4HciFromHost()

◆ HasSendBrEdrAclCapability()

◆ HasSendLeAclCapability()

◆ ProxyHost()

◆ RegisterL2capStatusDelegate()

◆ Reset()

◆ SendAdditionalRxCredits()

◆ SetH4Type() [1/3]

◆ SetH4Type() [2/3]

◆ SetH4Type() [3/3]

◆ UnregisterL2capStatusDelegate()

◆ ~ProxyHost()