L2CAP

L2CAP . More...

Data Structures
struct	bt_l2cap_chan
	L2CAP Channel structure. More...
struct	bt_l2cap_le_endpoint
	LE L2CAP Endpoint structure. More...
struct	bt_l2cap_le_chan
	LE L2CAP Channel structure. More...
struct	bt_l2cap_br_endpoint
	BREDR L2CAP Endpoint structure. More...
struct	bt_l2cap_br_chan
	BREDR L2CAP Channel structure. More...
struct	bt_l2cap_chan_ops
	L2CAP Channel operations structure. More...
struct	bt_l2cap_server
	L2CAP Server structure. More...

Macros
#define	BT_L2CAP_HDR_SIZE   4
	L2CAP PDU header size, used for buffer size calculations.
#define	BT_L2CAP_TX_MTU   (CONFIG_BT_L2CAP_TX_MTU)
	Maximum Transmission Unit (MTU) for an outgoing L2CAP PDU.
#define	BT_L2CAP_RX_MTU   (CONFIG_BT_BUF_ACL_RX_SIZE - BT_L2CAP_HDR_SIZE)
	Maximum Transmission Unit (MTU) for an incoming L2CAP PDU.
#define	BT_L2CAP_BUF_SIZE(mtu)
	Helper to calculate needed buffer size for L2CAP PDUs.
#define	BT_L2CAP_SDU_HDR_SIZE   2
	L2CAP SDU header size, used for buffer size calculations.
#define	BT_L2CAP_SDU_TX_MTU   (BT_L2CAP_TX_MTU - BT_L2CAP_SDU_HDR_SIZE)
	Maximum Transmission Unit for an unsegmented outgoing L2CAP SDU.
#define	BT_L2CAP_SDU_RX_MTU   (BT_L2CAP_RX_MTU - BT_L2CAP_SDU_HDR_SIZE)
	Maximum Transmission Unit for an unsegmented incoming L2CAP SDU.
#define	BT_L2CAP_SDU_BUF_SIZE(mtu)
	Helper to calculate needed buffer size for L2CAP SDUs.
#define	BT_L2CAP_ECRED_MIN_MTU   64
	L2CAP ECRED minimum MTU.
#define	BT_L2CAP_ECRED_MIN_MPS   64
	L2CAP ECRED minimum MPS.
#define	BT_L2CAP_ECRED_CHAN_MAX_PER_REQ   5
	The maximum number of channels in ECRED L2CAP signaling PDUs.
#define	BT_L2CAP_LE_CHAN(_ch)
	Helper macro getting container object of type bt_l2cap_le_chan address having the same container chan member address as object in question.
#define	BT_L2CAP_CHAN_SEND_RESERVE   (BT_L2CAP_BUF_SIZE(0))
	Headroom needed for outgoing L2CAP PDUs.
#define	BT_L2CAP_SDU_CHAN_SEND_RESERVE   (BT_L2CAP_SDU_BUF_SIZE(0))
	Headroom needed for outgoing L2CAP SDUs.

Typedefs
typedef void(*	bt_l2cap_chan_destroy_t) (struct bt_l2cap_chan *chan)
	Channel destroy callback.
typedef enum bt_l2cap_chan_state	bt_l2cap_chan_state_t
	Life-span states of L2CAP CoC channel.
typedef enum bt_l2cap_chan_status	bt_l2cap_chan_status_t
	Status of L2CAP channel.

Enumerations
enum	bt_l2cap_chan_state {   BT_L2CAP_DISCONNECTED , BT_L2CAP_CONNECTING , BT_L2CAP_CONFIG , BT_L2CAP_CONNECTED ,   BT_L2CAP_DISCONNECTING }
	Life-span states of L2CAP CoC channel. More...
enum	bt_l2cap_chan_status { BT_L2CAP_STATUS_OUT , BT_L2CAP_STATUS_SHUTDOWN , BT_L2CAP_STATUS_ENCRYPT_PENDING , BT_L2CAP_NUM_STATUS }
	Status of L2CAP channel. More...

Functions
int	bt_l2cap_server_register (struct bt_l2cap_server *server)
	Register L2CAP server.
int	bt_l2cap_br_server_register (struct bt_l2cap_server *server)
	Register L2CAP server on BR/EDR oriented connection.
int	bt_l2cap_ecred_chan_connect (struct bt_conn *conn, struct bt_l2cap_chan **chans, uint16_t psm)
	Connect Enhanced Credit Based L2CAP channels.
int	bt_l2cap_ecred_chan_reconfigure (struct bt_l2cap_chan **chans, uint16_t mtu)
	Reconfigure Enhanced Credit Based L2CAP channels.
int	bt_l2cap_ecred_chan_reconfigure_explicit (struct bt_l2cap_chan **chans, size_t chan_count, uint16_t mtu, uint16_t mps)
	Reconfigure Enhanced Credit Based L2CAP channels.
int	bt_l2cap_chan_connect (struct bt_conn *conn, struct bt_l2cap_chan *chan, uint16_t psm)
	Connect L2CAP channel.
int	bt_l2cap_chan_disconnect (struct bt_l2cap_chan *chan)
	Disconnect L2CAP channel.
int	bt_l2cap_chan_send (struct bt_l2cap_chan *chan, struct net_buf *buf)
	Send data to L2CAP channel.
int	bt_l2cap_chan_give_credits (struct bt_l2cap_chan *chan, uint16_t additional_credits)
	Give credits to the remote.
int	bt_l2cap_chan_recv_complete (struct bt_l2cap_chan *chan, struct net_buf *buf)
	Complete receiving L2CAP channel data.

Detailed Description

L2CAP .

Macro Definition Documentation

BT_L2CAP_BUF_SIZE

#define BT_L2CAP_BUF_SIZE

(

mtu

)

#include <zephyr/bluetooth/l2cap.h>

Value:

BT_BUF_ACL_SIZE(BT_L2CAP_HDR_SIZE + (mtu))

Helper to calculate needed buffer size for L2CAP PDUs.

Useful for creating buffer pools.

Parameters

mtu	Needed L2CAP PDU MTU.

Returns

Needed buffer size to match the requested L2CAP PDU MTU.

BT_L2CAP_CHAN_SEND_RESERVE

#define BT_L2CAP_CHAN_SEND_RESERVE   (BT_L2CAP_BUF_SIZE(0))

#include <zephyr/bluetooth/l2cap.h>

Headroom needed for outgoing L2CAP PDUs.

BT_L2CAP_ECRED_CHAN_MAX_PER_REQ

#define BT_L2CAP_ECRED_CHAN_MAX_PER_REQ   5

#include <zephyr/bluetooth/l2cap.h>

The maximum number of channels in ECRED L2CAP signaling PDUs.

Currently, this is the maximum number of channels referred to in the following PDUs:

• L2CAP_CREDIT_BASED_CONNECTION_REQ
• L2CAP_CREDIT_BASED_RECONFIGURE_REQ

Warning

The commonality is inferred between the PDUs. The Bluetooth specification treats these as separate numbers and does now guarantee the same limit for potential future ECRED L2CAP signaling PDUs.

BT_L2CAP_ECRED_MIN_MPS

#define BT_L2CAP_ECRED_MIN_MPS   64

#include <zephyr/bluetooth/l2cap.h>

L2CAP ECRED minimum MPS.

The minimum MPS for an L2CAP Enhanced Credit Based Connection.

This requirement is inferred from text in Core 3.A.4.25 v6.0:

L2CAP implementations shall support a minimum MPS of 64 and may
support an MPS up to 65533 octets for these channels.

BT_L2CAP_ECRED_MIN_MTU

#define BT_L2CAP_ECRED_MIN_MTU   64

#include <zephyr/bluetooth/l2cap.h>

L2CAP ECRED minimum MTU.

The minimum MTU for an L2CAP Enhanced Credit Based Connection.

This requirement is inferred from text in Core 3.A.4.25 v6.0:

L2CAP implementations shall support a minimum MTU size of 64
octets for these channels.

BT_L2CAP_HDR_SIZE

#define BT_L2CAP_HDR_SIZE   4

#include <zephyr/bluetooth/l2cap.h>

L2CAP PDU header size, used for buffer size calculations.

BT_L2CAP_LE_CHAN

#define BT_L2CAP_LE_CHAN

(

_ch

)

#include <zephyr/bluetooth/l2cap.h>

Value:

CONTAINER_OF(_ch, struct bt_l2cap_le_chan, chan)

Helper macro getting container object of type bt_l2cap_le_chan address having the same container chan member address as object in question.

Parameters

_ch	Address of object of bt_l2cap_chan type

Returns

Address of in memory bt_l2cap_le_chan object type containing the address of in question object.

BT_L2CAP_RX_MTU

#define BT_L2CAP_RX_MTU   (CONFIG_BT_BUF_ACL_RX_SIZE - BT_L2CAP_HDR_SIZE)

#include <zephyr/bluetooth/l2cap.h>

Maximum Transmission Unit (MTU) for an incoming L2CAP PDU.

BT_L2CAP_SDU_BUF_SIZE

#define BT_L2CAP_SDU_BUF_SIZE

(

mtu

)

#include <zephyr/bluetooth/l2cap.h>

Value:

BT_L2CAP_BUF_SIZE(BT_L2CAP_SDU_HDR_SIZE + (mtu))

Helper to calculate needed buffer size for L2CAP SDUs.

Useful for creating buffer pools.

Parameters

mtu	Required BT_L2CAP_*_SDU.

Returns

Needed buffer size to match the requested L2CAP SDU MTU.

BT_L2CAP_SDU_CHAN_SEND_RESERVE

#define BT_L2CAP_SDU_CHAN_SEND_RESERVE   (BT_L2CAP_SDU_BUF_SIZE(0))

#include <zephyr/bluetooth/l2cap.h>

Headroom needed for outgoing L2CAP SDUs.

BT_L2CAP_SDU_HDR_SIZE

#define BT_L2CAP_SDU_HDR_SIZE   2

#include <zephyr/bluetooth/l2cap.h>

L2CAP SDU header size, used for buffer size calculations.

BT_L2CAP_SDU_RX_MTU

#define BT_L2CAP_SDU_RX_MTU   (BT_L2CAP_RX_MTU - BT_L2CAP_SDU_HDR_SIZE)

#include <zephyr/bluetooth/l2cap.h>

Maximum Transmission Unit for an unsegmented incoming L2CAP SDU.

The Maximum Transmission Unit for an incoming L2CAP SDU when sent without segmentation, i.e. a single L2CAP SDU will fit inside a single L2CAP PDU.

The MTU for incoming L2CAP SDUs with segmentation is defined by the size of the application buffer pool. The application will have to define an alloc_buf callback for the channel in order to support receiving segmented L2CAP SDUs.

BT_L2CAP_SDU_TX_MTU

#define BT_L2CAP_SDU_TX_MTU   (BT_L2CAP_TX_MTU - BT_L2CAP_SDU_HDR_SIZE)

#include <zephyr/bluetooth/l2cap.h>

Maximum Transmission Unit for an unsegmented outgoing L2CAP SDU.

The Maximum Transmission Unit for an outgoing L2CAP SDU when sent without segmentation, i.e. a single L2CAP SDU will fit inside a single L2CAP PDU.

The MTU for outgoing L2CAP SDUs with segmentation is defined by the size of the application buffer pool.

BT_L2CAP_TX_MTU

#define BT_L2CAP_TX_MTU   (CONFIG_BT_L2CAP_TX_MTU)

#include <zephyr/bluetooth/l2cap.h>

Maximum Transmission Unit (MTU) for an outgoing L2CAP PDU.

Typedef Documentation

bt_l2cap_chan_destroy_t

typedef void(* bt_l2cap_chan_destroy_t) (struct bt_l2cap_chan *chan)

#include <zephyr/bluetooth/l2cap.h>

Channel destroy callback.

Parameters

chan	Channel object.

bt_l2cap_chan_state_t

typedef enum bt_l2cap_chan_state bt_l2cap_chan_state_t

#include <zephyr/bluetooth/l2cap.h>

Life-span states of L2CAP CoC channel.

Used only by internal APIs dealing with setting channel to proper state depending on operational context.

A channel enters the BT_L2CAP_CONNECTING state upon bt_l2cap_chan_connect, bt_l2cap_ecred_chan_connect or upon returning from bt_l2cap_server::accept.

When a channel leaves the BT_L2CAP_CONNECTING state, bt_l2cap_chan_ops::connected is called.

bt_l2cap_chan_status_t

typedef enum bt_l2cap_chan_status bt_l2cap_chan_status_t

#include <zephyr/bluetooth/l2cap.h>

Status of L2CAP channel.

Enumeration Type Documentation

bt_l2cap_chan_state

enum bt_l2cap_chan_state

#include <zephyr/bluetooth/l2cap.h>

Life-span states of L2CAP CoC channel.

Used only by internal APIs dealing with setting channel to proper state depending on operational context.

A channel enters the BT_L2CAP_CONNECTING state upon bt_l2cap_chan_connect, bt_l2cap_ecred_chan_connect or upon returning from bt_l2cap_server::accept.

When a channel leaves the BT_L2CAP_CONNECTING state, bt_l2cap_chan_ops::connected is called.

Enumerator
BT_L2CAP_DISCONNECTED	Channel disconnected.
BT_L2CAP_CONNECTING	Channel in connecting state.
BT_L2CAP_CONFIG	Channel in config state, BR/EDR specific.
BT_L2CAP_CONNECTED	Channel ready for upper layer traffic on it.
BT_L2CAP_DISCONNECTING	Channel in disconnecting state.

bt_l2cap_chan_status

enum bt_l2cap_chan_status

#include <zephyr/bluetooth/l2cap.h>

Status of L2CAP channel.

Enumerator
BT_L2CAP_STATUS_OUT	Channel can send at least one PDU.
BT_L2CAP_STATUS_SHUTDOWN	Channel shutdown status. Once this status is notified it means the channel will no longer be able to transmit or receive data.
BT_L2CAP_STATUS_ENCRYPT_PENDING	Channel encryption pending status.
BT_L2CAP_NUM_STATUS

Function Documentation

bt_l2cap_br_server_register()

int bt_l2cap_br_server_register

(

struct bt_l2cap_server *

server

)

#include <zephyr/bluetooth/l2cap.h>

Register L2CAP server on BR/EDR oriented connection.

Register L2CAP server for a PSM, each new connection is authorized using the accept() callback which in case of success shall allocate the channel structure to be used by the new connection.

Parameters

server

Server structure.

Returns

0 in case of success or negative value in case of error.

bt_l2cap_chan_connect()

int bt_l2cap_chan_connect	(	struct bt_conn *	conn,
		struct bt_l2cap_chan *	chan,
		uint16_t	psm )

#include <zephyr/bluetooth/l2cap.h>

Connect L2CAP channel.

Connect L2CAP channel by PSM, once the connection is completed channel connected() callback will be called. If the connection is rejected disconnected() callback is called instead. Channel object passed (over an address of it) as second parameter shouldn't be instantiated in application as standalone. Instead of, application should create transport dedicated L2CAP objects, i.e. type of bt_l2cap_le_chan for LE and/or type of bt_l2cap_br_chan for BR/EDR. Then pass to this API the location (address) of bt_l2cap_chan type object which is a member of both transport dedicated objects.

Warning

It is the responsibility of the caller to zero out the parent of the chan object.

Parameters

conn	Connection object.
chan	Channel object.
psm	Channel PSM to connect to.

Returns

0 in case of success or negative value in case of error.

bt_l2cap_chan_disconnect()

int bt_l2cap_chan_disconnect

(

struct bt_l2cap_chan *

chan

)

#include <zephyr/bluetooth/l2cap.h>

Disconnect L2CAP channel.

Disconnect L2CAP channel, if the connection is pending it will be canceled and as a result the channel disconnected() callback is called. Regarding to input parameter, to get details see reference description to bt_l2cap_chan_connect() API above.

Parameters

chan	Channel object.

Returns

0 in case of success or negative value in case of error.

bt_l2cap_chan_give_credits()

int bt_l2cap_chan_give_credits	(	struct bt_l2cap_chan *	chan,
		uint16_t	additional_credits )

#include <zephyr/bluetooth/l2cap.h>

Give credits to the remote.

Only available for channels using bt_l2cap_chan_ops::seg_recv. CONFIG_BT_L2CAP_SEG_RECV must be enabled to make this function available.

Each credit given allows the peer to send one segment.

This function depends on a valid chan object. Make sure to default-initialize or memset chan when allocating or reusing it for new connections.

Adding zero credits is not allowed.

Credits can be given before entering the BT_L2CAP_CONNECTING state. Doing so will adjust the 'initial credits' sent in the connection PDU.

Must not be called while the channel is in BT_L2CAP_CONNECTING state.

Returns

0 in case of success or negative value in case of error.

bt_l2cap_chan_recv_complete()

int bt_l2cap_chan_recv_complete	(	struct bt_l2cap_chan *	chan,
		struct net_buf *	buf )

#include <zephyr/bluetooth/l2cap.h>

Complete receiving L2CAP channel data.

Complete the reception of incoming data. This shall only be called if the channel recv callback has returned -EINPROGRESS to process some incoming data. The buffer shall contain the original user_data as that is used for storing the credits/segments used by the packet.

Parameters

chan	Channel object.
buf	Buffer containing the data.

Returns

0 in case of success or negative value in case of error.

bt_l2cap_chan_send()

int bt_l2cap_chan_send	(	struct bt_l2cap_chan *	chan,
		struct net_buf *	buf )

#include <zephyr/bluetooth/l2cap.h>

Send data to L2CAP channel.

Send data from buffer to the channel. If credits are not available, buf will be queued and sent as and when credits are received from peer. Regarding to first input parameter, to get details see reference description to bt_l2cap_chan_connect() API above.

Network buffer fragments (ie buf->frags) are not supported.

When sending L2CAP data over an BR/EDR connection the application is sending L2CAP PDUs. The application is required to have reserved BT_L2CAP_CHAN_SEND_RESERVE bytes in the buffer before sending. The application should use the BT_L2CAP_BUF_SIZE() helper to correctly size the buffers for the for the outgoing buffer pool.

When sending L2CAP data over an LE connection the application is sending L2CAP SDUs. The application shall reserve BT_L2CAP_SDU_CHAN_SEND_RESERVE bytes in the buffer before sending.

The application can use the BT_L2CAP_SDU_BUF_SIZE() helper to correctly size the buffer to account for the reserved headroom.

When segmenting an L2CAP SDU into L2CAP PDUs the stack will first attempt to allocate buffers from the channel's alloc_seg callback and will fallback on the stack's global buffer pool (sized CONFIG_BT_L2CAP_TX_BUF_COUNT).

Warning

The buffer's user_data will be overwritten by this function. Do not store anything in it. As soon as a call to this function has been made, consider ownership of user_data transferred into the stack.

Note

Buffer ownership is transferred to the stack in case of success, in case of an error the caller retains the ownership of the buffer.

Returns

0 in case of success or negative value in case of error.

-EINVAL if buf or chan is NULL.

-EINVAL if chan is not either BR/EDR or LE credit-based.

-EINVAL if buffer doesn't have enough bytes reserved to fit header.

-EINVAL if buffer's reference counter != 1

-EMSGSIZE if buf is larger than chan's MTU.

-ENOTCONN if underlying conn is disconnected.

-ESHUTDOWN if L2CAP channel is disconnected.

-other (from lower layers) if chan is BR/EDR.

bt_l2cap_ecred_chan_connect()

int bt_l2cap_ecred_chan_connect	(	struct bt_conn *	conn,
		struct bt_l2cap_chan **	chans,
		uint16_t	psm )

#include <zephyr/bluetooth/l2cap.h>

Connect Enhanced Credit Based L2CAP channels.

Connect up to 5 L2CAP channels by PSM, once the connection is completed each channel connected() callback will be called. If the connection is rejected disconnected() callback is called instead.

Warning

It is the responsibility of the caller to zero out the parents of the chan objects.

Parameters

conn	Connection object.
chans	Array of channel objects.
psm	Channel PSM to connect to.

Returns

0 in case of success or negative value in case of error.

bt_l2cap_ecred_chan_reconfigure()

int bt_l2cap_ecred_chan_reconfigure	(	struct bt_l2cap_chan **	chans,
		uint16_t	mtu )

#include <zephyr/bluetooth/l2cap.h>

Reconfigure Enhanced Credit Based L2CAP channels.

Reconfigure up to 5 L2CAP channels. Channels must be from the same bt_conn. Once reconfiguration is completed each channel reconfigured() callback will be called. MTU cannot be decreased on any of provided channels.

Parameters

chans	Array of channel objects. Null-terminated. Elements after the first 5 are silently ignored.
mtu	Channel MTU to reconfigure to.

Returns

0 in case of success or negative value in case of error.

bt_l2cap_ecred_chan_reconfigure_explicit()

int bt_l2cap_ecred_chan_reconfigure_explicit	(	struct bt_l2cap_chan **	chans,
		size_t	chan_count,
		uint16_t	mtu,
		uint16_t	mps )

#include <zephyr/bluetooth/l2cap.h>

Reconfigure Enhanced Credit Based L2CAP channels.

Experimental API to reconfigure L2CAP ECRED channels with explicit MPS and MTU values.

Pend a L2CAP ECRED reconfiguration for up to 5 channels. All provided channels must share the same Connection management.

This API cannot decrease the MTU of any channel, and it cannot decrease the MPS of any channel when more than one channel is provided.

There is no dedicated callback for this operation, but whenever a peer responds to a reconfiguration request, each affected channel's reconfigured() callback is invoked.

This function may block.

Warning

Known issue: The implementation returns -EBUSY if there already is an ongoing reconfigure operation on the same connection. The caller may try again later. There is no event signaling when the existing operation finishes.

Known issue: The implementation returns -ENOMEM when unable to allocate. The caller may try again later. There is no event signaling the availability of buffers.

Attention

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

Parameters

chans	Array of channels to reconfigure. Must be non-empty and contain at most 5 (BT_L2CAP_ECRED_CHAN_MAX_PER_REQ) elements.
chan_count	Number of channels in the array.
mtu	Desired MTU. Must be at least BT_L2CAP_ECRED_MIN_MTU.
mps	Desired MPS. Must be in range BT_L2CAP_ECRED_MIN_MPS to BT_L2CAP_RX_MTU.

Return values

0	Successfully pended operation.
-EINVAL	Bad arguments. See above requirements.
-ENOTCONN	Connection object is not in connected state.
-EBUSY	Another outgoing reconfiguration is pending on the same connection.
-ENOMEM	Host is out of buffers.

bt_l2cap_server_register()

int bt_l2cap_server_register

(

struct bt_l2cap_server *

server

)

#include <zephyr/bluetooth/l2cap.h>

Register L2CAP server.

Register L2CAP server for a PSM, each new connection is authorized using the accept() callback which in case of success shall allocate the channel structure to be used by the new connection.

For fixed, SIG-assigned PSMs (in the range 0x0001-0x007f) the PSM should be assigned to server->psm before calling this API. For dynamic PSMs (in the range 0x0080-0x00ff) server->psm may be pre-set to a given value (this is however not recommended) or be left as 0, in which case upon return a newly allocated value will have been assigned to it. For dynamically allocated values the expectation is that it's exposed through a GATT service, and that's how L2CAP clients discover how to connect to the server.

Parameters

server

Server structure.

Returns

0 in case of success or negative value in case of error.