Zephyr API Documentation  3.6.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches

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)   BT_BUF_ACL_SIZE(BT_L2CAP_HDR_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)   BT_L2CAP_BUF_SIZE(BT_L2CAP_SDU_HDR_SIZE + (mtu))
 Helper to calculate needed buffer size for L2CAP SDUs.
 
#define BT_L2CAP_LE_CHAN(_ch)   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.
 
#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_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)    BT_BUF_ACL_SIZE(BT_L2CAP_HDR_SIZE + (mtu))

#include <zephyr/bluetooth/l2cap.h>

Helper to calculate needed buffer size for L2CAP PDUs.

Useful for creating buffer pools.

Parameters
mtuNeeded 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_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)    CONTAINER_OF(_ch, struct bt_l2cap_le_chan, chan)

#include <zephyr/bluetooth/l2cap.h>

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

Parameters
_chAddress 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)    BT_L2CAP_BUF_SIZE(BT_L2CAP_SDU_HDR_SIZE + (mtu))

#include <zephyr/bluetooth/l2cap.h>

Helper to calculate needed buffer size for L2CAP SDUs.

Useful for creating buffer pools.

Parameters
mtuRequired 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

bt_l2cap_chan_destroy_t

#include <zephyr/bluetooth/l2cap.h>

Channel destroy callback.

Parameters
chanChannel object.

◆ 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

#include <zephyr/bluetooth/l2cap.h>

Status of L2CAP channel.

Enumeration Type Documentation

◆ 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

#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
serverServer 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.

Parameters
connConnection object.
chanChannel object.
psmChannel 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
chanChannel 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
chanChannel object.
bufBuffer 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 ).

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.

Parameters
connConnection object.
chansArray of channel objects.
psmChannel 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
chansArray of channel objects. Null-terminated. Elements after the first 5 are silently ignored.
mtuChannel MTU to reconfigure to.
Returns
0 in case of success or negative value in case of error.

◆ 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
serverServer structure.
Returns
0 in case of success or negative value in case of error.