Logical Link Control and Adaptation Protocol (L2CAP)¶
L2CAP layer enables connection-oriented channels which can be enable with the
configuration option: CONFIG_BT_L2CAP_DYNAMIC_CHANNEL
. This channels
support segmentation and reassembly transparently, they also support credit
based flow control making it suitable for data streams.
Channels instances are represented by the bt_l2cap_chan
struct which
contains the callbacks in the bt_l2cap_chan_ops
struct to inform
when the channel has been connected, disconnected or when the encryption has
changed.
In addition to that it also contains the recv
callback which is called
whenever an incoming data has been received. Data received this way can be
marked as processed by returning 0 or using
bt_l2cap_chan_recv_complete()
API if processing is asynchronous.
Note
The recv
callback is called directly from RX Thread thus it is not
recommended to block for long periods of time.
For sending data the bt_l2cap_chan_send()
API can be used noting that
it may block if no credits are available, and resuming as soon as more credits
are available.
Servers can be registered using bt_l2cap_server_register()
API passing
the bt_l2cap_server
struct which informs what psm
it should
listen to, the required security level sec_level
, and the callback
accept
which is called to authorize incoming connection requests and
allocate channel instances.
Client channels can be initiated with use of bt_l2cap_chan_connect()
API and can be disconnected with the bt_l2cap_chan_disconnect()
API.
Note that the later can also disconnect channel instances created by servers.
API Reference¶
-
group
bt_l2cap
L2CAP.
Defines
-
BT_L2CAP_HDR_SIZE
¶ L2CAP header size, used for buffer size calculations
-
BT_L2CAP_BUF_SIZE
(mtu)¶ Helper to calculate needed outgoing buffer size, useful e.g. for creating buffer pools.
- Return
Needed buffer size to match the requested L2CAP MTU.
- Parameters
mtu
: Needed L2CAP MTU.
-
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.
- Return
Address of in memory bt_l2cap_le_chan object type containing the address of in question object.
- Parameters
_ch
: Address of object of bt_l2cap_chan type
-
BT_L2CAP_CHAN_SEND_RESERVE
¶ Headroom needed for outgoing buffers.
Typedefs
-
typedef void (*
bt_l2cap_chan_destroy_t
)(struct bt_l2cap_chan *chan)¶ Channel destroy callback.
- Parameters
chan
: Channel object.
-
typedef enum bt_l2cap_chan_state
bt_l2cap_chan_state_t
¶ Life-span states of L2CAP CoC channel.
Used only by internal APIs dealing with setting channel to proper state depending on operational context.
-
typedef enum bt_l2cap_chan_status
bt_l2cap_chan_status_t
¶ Status of L2CAP channel.
Enums
-
enum
bt_l2cap_chan_state
¶ Life-span states of L2CAP CoC channel.
Used only by internal APIs dealing with setting channel to proper state depending on operational context.
Values:
-
enumerator
BT_L2CAP_DISCONNECTED
¶ Channel disconnected
-
enumerator
BT_L2CAP_CONNECT
¶ Channel in connecting state
-
enumerator
BT_L2CAP_CONFIG
¶ Channel in config state, BR/EDR specific
-
enumerator
BT_L2CAP_CONNECTED
¶ Channel ready for upper layer traffic on it
-
enumerator
BT_L2CAP_DISCONNECT
¶ Channel in disconnecting state
-
enumerator
-
enum
bt_l2cap_chan_status
¶ Status of L2CAP channel.
Values:
-
enumerator
BT_L2CAP_STATUS_OUT
¶ Channel output status
-
enumerator
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.
-
enumerator
BT_L2CAP_STATUS_ENCRYPT_PENDING
¶ Channel encryption pending status.
-
enumerator
BT_L2CAP_NUM_STATUS
¶
-
enumerator
Functions
-
int
bt_l2cap_server_register
(struct bt_l2cap_server *server)¶ 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.
- Return
0 in case of success or negative value in case of error.
- Parameters
server
: Server structure.
-
int
bt_l2cap_br_server_register
(struct bt_l2cap_server *server)¶ 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.
- Return
0 in case of success or negative value in case of error.
- Parameters
server
: Server structure.
-
int
bt_l2cap_ecred_chan_connect
(struct bt_conn *conn, struct bt_l2cap_chan **chans, uint16_t psm)¶ 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.
- Return
0 in case of success or negative value in case of error.
- Parameters
conn
: Connection object.chans
: Array of channel objects.psm
: Channel PSM to connect to.
-
int
bt_l2cap_chan_connect
(struct bt_conn *conn, struct bt_l2cap_chan *chan, uint16_t psm)¶ 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.
- Return
0 in case of success or negative value in case of error.
- Parameters
conn
: Connection object.chan
: Channel object.psm
: Channel PSM to connect to.
-
int
bt_l2cap_chan_disconnect
(struct bt_l2cap_chan *chan)¶ 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.
- Return
0 in case of success or negative value in case of error.
- Parameters
chan
: Channel object.
-
int
bt_l2cap_chan_send
(struct bt_l2cap_chan *chan, struct net_buf *buf)¶ 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.
- Return
Bytes sent in case of success or negative value in case of error.
-
int
bt_l2cap_chan_recv_complete
(struct bt_l2cap_chan *chan, struct net_buf *buf)¶ 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.
- Return
0 in case of success or negative value in case of error.
- Parameters
chan
: Channel object.buf
: Buffer containing the data.
-
struct
bt_l2cap_chan
¶ - #include <l2cap.h>
L2CAP Channel structure.
Public Members
-
struct bt_conn *
conn
¶ Channel connection reference
-
const struct bt_l2cap_chan_ops *
ops
¶ Channel operations reference
-
struct bt_conn *
-
struct
bt_l2cap_le_endpoint
¶ - #include <l2cap.h>
LE L2CAP Endpoint structure.
-
struct
bt_l2cap_le_chan
¶ - #include <l2cap.h>
LE L2CAP Channel structure.
Public Members
-
struct bt_l2cap_chan
chan
¶ Common L2CAP channel reference object
-
struct bt_l2cap_le_endpoint
rx
¶ Channel Receiving Endpoint
-
struct bt_l2cap_le_endpoint
tx
¶ Channel Transmission Endpoint
-
struct k_fifo
tx_queue
¶ Channel Transmission queue
-
struct k_work
tx_work
¶ Channel Transmission work
-
struct bt_l2cap_chan
-
struct
bt_l2cap_br_endpoint
¶ - #include <l2cap.h>
BREDR L2CAP Endpoint structure.
-
struct
bt_l2cap_br_chan
¶ - #include <l2cap.h>
BREDR L2CAP Channel structure.
Public Members
-
struct bt_l2cap_chan
chan
¶ Common L2CAP channel reference object
-
struct bt_l2cap_br_endpoint
rx
¶ Channel Receiving Endpoint
-
struct bt_l2cap_br_endpoint
tx
¶ Channel Transmission Endpoint
-
struct bt_l2cap_chan
-
struct
bt_l2cap_chan_ops
¶ - #include <l2cap.h>
L2CAP Channel operations structure.
Public Members
-
void (*
connected
)(struct bt_l2cap_chan *chan)¶ Channel connected callback.
If this callback is provided it will be called whenever the connection completes.
- Parameters
chan
: The channel that has been connected
-
void (*
disconnected
)(struct bt_l2cap_chan *chan)¶ Channel disconnected callback.
If this callback is provided it will be called whenever the channel is disconnected, including when a connection gets rejected.
- Parameters
chan
: The channel that has been Disconnected
-
void (*
encrypt_change
)(struct bt_l2cap_chan *chan, uint8_t hci_status)¶ Channel encrypt_change callback.
If this callback is provided it will be called whenever the security level changed (indirectly link encryption done) or authentication procedure fails. In both cases security initiator and responder got the final status (HCI status) passed by related to encryption and authentication events from local host’s controller.
- Parameters
chan
: The channel which has made encryption status changed.status
: HCI status of performed security procedure caused by channel security requirements. The value is populated by HCI layer and set to 0 when success and to non-zero (reference to HCI Error Codes) when security/authentication failed.
-
struct net_buf *(*
alloc_buf
)(struct bt_l2cap_chan *chan)¶ Channel alloc_buf callback.
If this callback is provided the channel will use it to allocate buffers to store incoming data. Channels that requires segmentation must set this callback.
- Return
Allocated buffer.
- Parameters
chan
: The channel requesting a buffer.
-
int (*
recv
)(struct bt_l2cap_chan *chan, struct net_buf *buf)¶ Channel recv callback.
- Return
0 in case of success or negative value in case of error.
- Return
-EINPROGRESS in case where user has to confirm once the data has been processed by calling bt_l2cap_chan_recv_complete passing back the buffer received with its original user_data which contains the number of segments/credits used by the packet.
- Parameters
chan
: The channel receiving data.buf
: Buffer containing incoming data.
-
void (*
sent
)(struct bt_l2cap_chan *chan)¶ Channel sent callback.
If this callback is provided it will be called whenever a SDU has been completely sent.
- Parameters
chan
: The channel which has sent data.
-
void (*
status
)(struct bt_l2cap_chan *chan, atomic_t *status)¶ Channel status callback.
If this callback is provided it will be called whenever the channel status changes.
- Parameters
chan
: The channel which status changedstatus
: The channel status
-
void (*
-
struct
bt_l2cap_server
¶ - #include <l2cap.h>
L2CAP Server structure.
Public Members
-
uint16_t
psm
¶ Server PSM.
Possible values: 0 A dynamic value will be auto-allocated when bt_l2cap_server_register() is called.
0x0001-0x007f Standard, Bluetooth SIG-assigned fixed values.
0x0080-0x00ff Dynamically allocated. May be pre-set by the application before server registration (not recommended however), or auto-allocated by the stack if the app gave 0 as the value.
-
bt_security_t
sec_level
¶ Required minimim security level
-
int (*
accept
)(struct bt_conn *conn, struct bt_l2cap_chan **chan)¶ Server accept callback.
This callback is called whenever a new incoming connection requires authorization.
- Return
0 in case of success or negative value in case of error.
- Return
-ENOMEM if no available space for new channel.
- Return
-EACCES if application did not authorize the connection.
- Return
-EPERM if encryption key size is too short.
- Parameters
conn
: The connection that is requesting authorizationchan
: Pointer to received the allocated channel
-
uint16_t
-