Line data Source code
1 1 : /** @file
2 : * @brief Bluetooth L2CAP handling
3 : */
4 :
5 : /*
6 : * Copyright (c) 2015-2016 Intel Corporation
7 : * Copyright (c) 2023 Nordic Semiconductor
8 : *
9 : * SPDX-License-Identifier: Apache-2.0
10 : */
11 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_L2CAP_H_
12 : #define ZEPHYR_INCLUDE_BLUETOOTH_L2CAP_H_
13 :
14 : /**
15 : * @brief L2CAP
16 : * @defgroup bt_l2cap L2CAP
17 : * @ingroup bluetooth
18 : * @{
19 : */
20 :
21 : #include <stddef.h>
22 : #include <stdint.h>
23 :
24 : #include <zephyr/bluetooth/buf.h>
25 : #include <zephyr/bluetooth/conn.h>
26 : #include <zephyr/bluetooth/hci.h>
27 : #include <zephyr/kernel.h>
28 : #include <zephyr/net_buf.h>
29 : #include <zephyr/sys/atomic.h>
30 : #include <zephyr/sys/slist.h>
31 : #include <zephyr/sys/util.h>
32 : #include <sys/types.h>
33 :
34 : #ifdef __cplusplus
35 : extern "C" {
36 : #endif
37 :
38 : /** L2CAP PDU header size, used for buffer size calculations */
39 1 : #define BT_L2CAP_HDR_SIZE 4
40 :
41 : /** Maximum Transmission Unit (MTU) for an outgoing L2CAP PDU. */
42 1 : #define BT_L2CAP_TX_MTU (CONFIG_BT_L2CAP_TX_MTU)
43 :
44 : /** Maximum Transmission Unit (MTU) for an incoming L2CAP PDU. */
45 1 : #define BT_L2CAP_RX_MTU (CONFIG_BT_BUF_ACL_RX_SIZE - BT_L2CAP_HDR_SIZE)
46 :
47 : /** @brief Helper to calculate needed buffer size for L2CAP PDUs.
48 : * Useful for creating buffer pools.
49 : *
50 : * @param mtu Needed L2CAP PDU MTU.
51 : *
52 : * @return Needed buffer size to match the requested L2CAP PDU MTU.
53 : */
54 1 : #define BT_L2CAP_BUF_SIZE(mtu) BT_BUF_ACL_SIZE(BT_L2CAP_HDR_SIZE + (mtu))
55 :
56 : /** L2CAP SDU header size, used for buffer size calculations */
57 1 : #define BT_L2CAP_SDU_HDR_SIZE 2
58 :
59 : /** @brief Maximum Transmission Unit for an unsegmented outgoing L2CAP SDU.
60 : *
61 : * The Maximum Transmission Unit for an outgoing L2CAP SDU when sent without
62 : * segmentation, i.e. a single L2CAP SDU will fit inside a single L2CAP PDU.
63 : *
64 : * The MTU for outgoing L2CAP SDUs with segmentation is defined by the
65 : * size of the application buffer pool.
66 : */
67 1 : #define BT_L2CAP_SDU_TX_MTU (BT_L2CAP_TX_MTU - BT_L2CAP_SDU_HDR_SIZE)
68 :
69 : /** @brief Maximum Transmission Unit for an unsegmented incoming L2CAP SDU.
70 : *
71 : * The Maximum Transmission Unit for an incoming L2CAP SDU when sent without
72 : * segmentation, i.e. a single L2CAP SDU will fit inside a single L2CAP PDU.
73 : *
74 : * The MTU for incoming L2CAP SDUs with segmentation is defined by the
75 : * size of the application buffer pool. The application will have to define
76 : * an alloc_buf callback for the channel in order to support receiving
77 : * segmented L2CAP SDUs.
78 : */
79 1 : #define BT_L2CAP_SDU_RX_MTU (BT_L2CAP_RX_MTU - BT_L2CAP_SDU_HDR_SIZE)
80 :
81 : /**
82 : *
83 : * @brief Helper to calculate needed buffer size for L2CAP SDUs.
84 : * Useful for creating buffer pools.
85 : *
86 : * @param mtu Required BT_L2CAP_*_SDU.
87 : *
88 : * @return Needed buffer size to match the requested L2CAP SDU MTU.
89 : */
90 1 : #define BT_L2CAP_SDU_BUF_SIZE(mtu) BT_L2CAP_BUF_SIZE(BT_L2CAP_SDU_HDR_SIZE + (mtu))
91 :
92 : /** @brief L2CAP ECRED minimum MTU
93 : *
94 : * The minimum MTU for an L2CAP Enhanced Credit Based Connection.
95 : *
96 : * This requirement is inferred from text in Core 3.A.4.25 v6.0:
97 : *
98 : * L2CAP implementations shall support a minimum MTU size of 64
99 : * octets for these channels.
100 : */
101 1 : #define BT_L2CAP_ECRED_MIN_MTU 64
102 :
103 : /** @brief L2CAP ECRED minimum MPS
104 : *
105 : * The minimum MPS for an L2CAP Enhanced Credit Based Connection.
106 : *
107 : * This requirement is inferred from text in Core 3.A.4.25 v6.0:
108 : *
109 : * L2CAP implementations shall support a minimum MPS of 64 and may
110 : * support an MPS up to 65533 octets for these channels.
111 : */
112 1 : #define BT_L2CAP_ECRED_MIN_MPS 64
113 :
114 : /** @brief L2CAP maximum MTU
115 : *
116 : * The maximum MTU for an L2CAP Based Connection. This is the same with or without ECRED. This
117 : * requirement is taken from text in Core 3.A.4.22 and 3.A.4.26 v6.0.
118 : */
119 1 : #define BT_L2CAP_MAX_MTU UINT16_MAX
120 :
121 : /** @brief L2CAP maximum MPS
122 : *
123 : * The maximum MPS for an L2CAP Based Connection. This is the same with or without ECRED. This
124 : * requirement is taken from text in Core 3.A.4.22 and 3.A.4.26 v6.0.
125 : */
126 1 : #define BT_L2CAP_MAX_MPS 65533
127 :
128 : /** @brief The maximum number of channels in ECRED L2CAP signaling PDUs
129 : *
130 : * Currently, this is the maximum number of channels referred to in the
131 : * following PDUs:
132 : * - L2CAP_CREDIT_BASED_CONNECTION_REQ
133 : * - L2CAP_CREDIT_BASED_RECONFIGURE_REQ
134 : *
135 : * @warning The commonality is inferred between the PDUs. The Bluetooth
136 : * specification treats these as separate numbers and does now
137 : * guarantee the same limit for potential future ECRED L2CAP signaling
138 : * PDUs.
139 : */
140 1 : #define BT_L2CAP_ECRED_CHAN_MAX_PER_REQ 5
141 :
142 : struct bt_l2cap_chan;
143 :
144 : /** @typedef bt_l2cap_chan_destroy_t
145 : * @brief Channel destroy callback
146 : *
147 : * @param chan Channel object.
148 : */
149 1 : typedef void (*bt_l2cap_chan_destroy_t)(struct bt_l2cap_chan *chan);
150 :
151 : /** @brief Life-span states of L2CAP CoC channel.
152 : *
153 : * Used only by internal APIs dealing with setting channel to proper state
154 : * depending on operational context.
155 : *
156 : * A channel enters the @ref BT_L2CAP_CONNECTING state upon @ref
157 : * bt_l2cap_chan_connect, @ref bt_l2cap_ecred_chan_connect or upon returning
158 : * from @ref bt_l2cap_server.accept.
159 : *
160 : * When a channel leaves the @ref BT_L2CAP_CONNECTING state, @ref
161 : * bt_l2cap_chan_ops.connected is called.
162 : */
163 1 : typedef enum bt_l2cap_chan_state {
164 : /** Channel disconnected */
165 : BT_L2CAP_DISCONNECTED,
166 : /** Channel in connecting state */
167 : BT_L2CAP_CONNECTING,
168 : /** Channel in config state, BR/EDR specific */
169 : BT_L2CAP_CONFIG,
170 : /** Channel ready for upper layer traffic on it */
171 : BT_L2CAP_CONNECTED,
172 : /** Channel in disconnecting state */
173 : BT_L2CAP_DISCONNECTING,
174 :
175 1 : } __packed bt_l2cap_chan_state_t;
176 :
177 : /** @brief Status of L2CAP channel. */
178 0 : typedef enum bt_l2cap_chan_status {
179 : /** Channel can send at least one PDU */
180 : BT_L2CAP_STATUS_OUT,
181 :
182 : /** @brief Channel shutdown status
183 : *
184 : * Once this status is notified it means the channel will no longer be
185 : * able to transmit or receive data.
186 : */
187 : BT_L2CAP_STATUS_SHUTDOWN,
188 :
189 : /** @brief Channel encryption pending status */
190 : BT_L2CAP_STATUS_ENCRYPT_PENDING,
191 :
192 : /* Total number of status - must be at the end of the enum */
193 : BT_L2CAP_NUM_STATUS,
194 1 : } __packed bt_l2cap_chan_status_t;
195 :
196 : /** @brief L2CAP Channel structure. */
197 1 : struct bt_l2cap_chan {
198 : /** Channel connection reference */
199 1 : struct bt_conn *conn;
200 : /** Channel operations reference */
201 1 : const struct bt_l2cap_chan_ops *ops;
202 0 : sys_snode_t node;
203 0 : bt_l2cap_chan_destroy_t destroy;
204 :
205 0 : ATOMIC_DEFINE(status, BT_L2CAP_NUM_STATUS);
206 : };
207 :
208 : /** @brief LE L2CAP Endpoint structure. */
209 1 : struct bt_l2cap_le_endpoint {
210 : /** Endpoint Channel Identifier (CID) */
211 1 : uint16_t cid;
212 : /** Endpoint Maximum Transmission Unit */
213 1 : uint16_t mtu;
214 : /** Endpoint Maximum PDU payload Size */
215 1 : uint16_t mps;
216 : /** Endpoint credits */
217 1 : atomic_t credits;
218 : };
219 :
220 : /** @brief LE L2CAP Channel structure. */
221 1 : struct bt_l2cap_le_chan {
222 : /** Common L2CAP channel reference object */
223 1 : struct bt_l2cap_chan chan;
224 : /** @brief Channel Receiving Endpoint.
225 : *
226 : * If the application has set an alloc_buf channel callback for the
227 : * channel to support receiving segmented L2CAP SDUs the application
228 : * should initialize the MTU of the Receiving Endpoint. Otherwise the
229 : * MTU of the receiving endpoint will be initialized to
230 : * @ref BT_L2CAP_SDU_RX_MTU by the stack.
231 : *
232 : * This is the source of the MTU, MPS and credit values when sending
233 : * L2CAP_LE_CREDIT_BASED_CONNECTION_REQ/RSP and
234 : * L2CAP_CONFIGURATION_REQ.
235 : */
236 1 : struct bt_l2cap_le_endpoint rx;
237 :
238 : /** Pending RX MTU on ECFC reconfigure, used internally by stack */
239 1 : uint16_t pending_rx_mtu;
240 :
241 : /** Channel Transmission Endpoint.
242 : *
243 : * This is an image of the remote's rx.
244 : *
245 : * The MTU and MPS is controlled by the remote by
246 : * L2CAP_LE_CREDIT_BASED_CONNECTION_REQ/RSP or L2CAP_CONFIGURATION_REQ.
247 : */
248 1 : struct bt_l2cap_le_endpoint tx;
249 : /** Channel Transmission queue (for SDUs) */
250 1 : struct k_fifo tx_queue;
251 : #if defined(CONFIG_BT_L2CAP_DYNAMIC_CHANNEL)
252 : /** Segment SDU packet from upper layer */
253 : struct net_buf *_sdu;
254 : uint16_t _sdu_len;
255 : #if defined(CONFIG_BT_L2CAP_SEG_RECV)
256 : uint16_t _sdu_len_done;
257 : #endif /* CONFIG_BT_L2CAP_SEG_RECV */
258 :
259 : struct k_work rx_work;
260 : struct k_fifo rx_queue;
261 :
262 : bt_l2cap_chan_state_t state;
263 : /** Remote PSM to be connected */
264 : uint16_t psm;
265 : /** Helps match request context during CoC */
266 : uint8_t ident;
267 : /** Opcode of the pending request. Used to match responses with requests. */
268 : uint8_t pending_req;
269 : bt_security_t required_sec_level;
270 :
271 : /* Response Timeout eXpired (RTX) timer */
272 : struct k_work_delayable rtx_work;
273 : struct k_work_sync rtx_sync;
274 : #endif
275 :
276 : /** @internal To be used with @ref bt_conn.upper_data_ready */
277 : sys_snode_t _pdu_ready;
278 : /** @internal Holds the length of the current PDU/segment */
279 : size_t _pdu_remaining;
280 : };
281 :
282 : /**
283 : * @brief Helper macro getting container object of type bt_l2cap_le_chan
284 : * address having the same container chan member address as object in question.
285 : *
286 : * @param _ch Address of object of bt_l2cap_chan type
287 : *
288 : * @return Address of in memory bt_l2cap_le_chan object type containing
289 : * the address of in question object.
290 : */
291 1 : #define BT_L2CAP_LE_CHAN(_ch) CONTAINER_OF(_ch, struct bt_l2cap_le_chan, chan)
292 :
293 : /** L2CAP Endpoint Link Mode. Basic mode. */
294 1 : #define BT_L2CAP_BR_LINK_MODE_BASIC 0x00
295 : /** L2CAP Endpoint Link Mode. Retransmission mode. */
296 1 : #define BT_L2CAP_BR_LINK_MODE_RET 0x01
297 : /** L2CAP Endpoint Link Mode. Flow control mode. */
298 1 : #define BT_L2CAP_BR_LINK_MODE_FC 0x02
299 : /** L2CAP Endpoint Link Mode. Enhance retransmission mode. */
300 1 : #define BT_L2CAP_BR_LINK_MODE_ERET 0x03
301 : /** L2CAP Endpoint Link Mode. Streaming mode. */
302 1 : #define BT_L2CAP_BR_LINK_MODE_STREAM 0x04
303 :
304 : /** Frame Check Sequence type. No FCS. */
305 1 : #define BT_L2CAP_BR_FCS_NO 0x00
306 : /** Frame Check Sequence type. 16-bit FCS. */
307 1 : #define BT_L2CAP_BR_FCS_16BIT 0x01
308 :
309 : /** @brief BREDR L2CAP Endpoint structure. */
310 1 : struct bt_l2cap_br_endpoint {
311 : /** Endpoint Channel Identifier (CID) */
312 1 : uint16_t cid;
313 : /** Endpoint Maximum Transmission Unit */
314 1 : uint16_t mtu;
315 : #if defined(CONFIG_BT_L2CAP_RET_FC) || defined(__DOXYGEN__)
316 : /** Endpoint Link Mode.
317 : * The value is defined as BT_L2CAP_BR_LINK_MODE_*
318 : */
319 1 : uint8_t mode;
320 : /** Whether Endpoint Link Mode is optional
321 : * If the `optional` is true, the `mode` could be
322 : * changed according to the extended feature and
323 : * peer configuration from L2CAP configuration
324 : * response and request.
325 : * Otherwise, if the channel configuration process
326 : * does not meet the set mode, the L2CAP channel
327 : * will be disconnected.
328 : */
329 1 : bool optional;
330 : /** Endpoint Maximum Transmit
331 : * The field is used to set the max retransmission
332 : * count.
333 : * For `RET`, `FC`, and `ERET`, it should be not
334 : * less 1.
335 : * For `STREAM`, it should be 0.
336 : */
337 1 : uint8_t max_transmit;
338 : /** Endpoint Retransmission Timeout
339 : * The field is configured by
340 : * `@kconfig{BT_L2CAP_BR_RET_TIMEOUT}`
341 : * The field should be no more than the field
342 : * `monitor_timeout`.
343 : */
344 1 : uint16_t ret_timeout;
345 : /** Endpoint Monitor Timeout
346 : * The field is configured by
347 : * `@kconfig{BT_L2CAP_BR_MONITOR_TIMEOUT}`
348 : */
349 1 : uint16_t monitor_timeout;
350 : /** Endpoint Maximum PDU payload Size */
351 1 : uint16_t mps;
352 : /** Endpoint Maximum Window Size
353 : * MAX supported window size is configured by
354 : * `@kconfig{BT_L2CAP_MAX_WINDOW_SIZE}`. The field
355 : * should be no more then `CONFIG_BT_L2CAP_MAX_WINDOW_SIZE`.
356 : */
357 1 : uint16_t max_window;
358 : /** Endpoint FCS Type
359 : * The value is defined as BT_L2CAP_BR_FCS_*
360 : * The default setting should be BT_L2CAP_BR_FCS_16BIT.
361 : * For FC and RET, the FCS type should be
362 : * BT_L2CAP_BR_FCS_16BIT.
363 : * For ERET and STREAM, the FCS type is optional. If
364 : * the field is not default value, the local will include
365 : * FCS option in configuration request packet if both side
366 : * support `FCS Option`.
367 : */
368 1 : uint8_t fcs;
369 : /** Endpoint Extended Control.
370 : * If this field is true, and both side support
371 : * `Extended Window size feature`, the local will
372 : * include `extended window size` option in configuration
373 : * request packet.
374 : */
375 1 : bool extended_control;
376 : #endif /* CONFIG_BT_L2CAP_RET_FC */
377 : };
378 :
379 : /** I-Frame transmission window for none `BASIC` mode L2cap connected channel. */
380 1 : struct bt_l2cap_br_window {
381 0 : sys_snode_t node;
382 :
383 : /** tx seq */
384 1 : uint16_t tx_seq;
385 : /** data len */
386 1 : uint16_t len;
387 : /** data address */
388 1 : uint8_t *data;
389 : /** Transmit Counter */
390 1 : uint8_t transmit_counter;
391 : /** SAR flag */
392 1 : uint8_t sar;
393 : /** srej flag */
394 1 : bool srej;
395 : /* Save PDU state */
396 0 : struct net_buf_simple_state sdu_state;
397 : /** @internal Holds the sending buffer. */
398 0 : struct net_buf *sdu;
399 : /** @internal Total length of TX SDU */
400 0 : uint16_t sdu_total_len;
401 : };
402 :
403 : /** @brief BREDR L2CAP Channel structure. */
404 1 : struct bt_l2cap_br_chan {
405 : /** Common L2CAP channel reference object */
406 1 : struct bt_l2cap_chan chan;
407 : /** Channel Receiving Endpoint */
408 1 : struct bt_l2cap_br_endpoint rx;
409 : /** Channel Transmission Endpoint */
410 1 : struct bt_l2cap_br_endpoint tx;
411 : /* For internal use only */
412 0 : atomic_t flags[1];
413 :
414 0 : bt_l2cap_chan_state_t state;
415 : /** Remote PSM to be connected */
416 1 : uint16_t psm;
417 : /** Helps match request context during CoC */
418 1 : uint8_t ident;
419 0 : bt_security_t required_sec_level;
420 :
421 : /* Response Timeout eXpired (RTX) timer */
422 0 : struct k_work_delayable rtx_work;
423 0 : struct k_work_sync rtx_sync;
424 :
425 : /** @internal To be used with @ref bt_conn.upper_data_ready */
426 : sys_snode_t _pdu_ready;
427 : /** @internal To be used with @ref bt_conn.upper_data_ready */
428 : atomic_t _pdu_ready_lock;
429 : /** @internal List of net bufs not yet sent to lower layer */
430 : sys_slist_t _pdu_tx_queue;
431 :
432 : #if defined(CONFIG_BT_L2CAP_RET_FC) || defined(__DOXYGEN__)
433 : /** @internal Total length of TX SDU */
434 : uint16_t _sdu_total_len;
435 :
436 : /** @internal Holds the remaining length of current sending buffer */
437 : size_t _pdu_remaining;
438 :
439 : /** @internal Holds the sending buffer. */
440 : struct net_buf *_pdu_buf;
441 :
442 : /** @internal TX windows for outstanding frame */
443 : sys_slist_t _pdu_outstanding;
444 :
445 : /** @internal PDU restore state */
446 : struct net_buf_simple_state _pdu_state;
447 :
448 : /** @internal Free TX windows */
449 : struct k_fifo _free_tx_win;
450 :
451 : /** @internal TX windows */
452 0 : struct bt_l2cap_br_window tx_win[CONFIG_BT_L2CAP_MAX_WINDOW_SIZE];
453 :
454 : /** Segment SDU packet from upper layer */
455 : struct net_buf *_sdu;
456 : /** @internal RX SDU */
457 : uint16_t _sdu_len;
458 : #if defined(CONFIG_BT_L2CAP_SEG_RECV) || defined(__DOXYGEN__)
459 : uint16_t _sdu_len_done;
460 : #endif /* CONFIG_BT_L2CAP_SEG_RECV */
461 : /** @internal variables and sequence numbers */
462 : /** @internal The sending peer uses the following variables and sequence
463 : * numbers.
464 : */
465 : /** @internal The send sequence number used to sequentially number each
466 : * new I-frame transmitted.
467 : */
468 0 : uint16_t tx_seq;
469 : /** @internal The sequence number to be used in the next new I-frame
470 : * transmitted.
471 : */
472 0 : uint16_t next_tx_seq;
473 : /** @internal The sequence number of the next I-frame expected to be
474 : * acknowledged by the receiving peer.
475 : */
476 0 : uint16_t expected_ack_seq;
477 : /** @internal The receiving peer uses the following variables and sequence
478 : * numbers.
479 : */
480 : /** @internal The sequence number sent in an acknowledgment frame to
481 : * request transmission of I-frame with TxSeq = ReqSeq and acknowledge
482 : * receipt of I-frames up to and including (ReqSeq-1).
483 : */
484 0 : uint16_t req_seq;
485 : /** @internal The value of TxSeq expected in the next I-frame.
486 : */
487 0 : uint16_t expected_tx_seq;
488 : /** @internal When segmented I-frames are buffered this is used to delay
489 : * acknowledgment of received I-frame so that new I-frame transmissions do
490 : * not cause buffer overflow.
491 : */
492 0 : uint16_t buffer_seq;
493 :
494 : /** @internal States of Enhanced Retransmission Mode */
495 : /** @internal Holds the number of times an S-frame operation is retried
496 : */
497 0 : uint16_t retry_count;
498 : /** @internal save the ReqSeq of a SREJ frame */
499 0 : uint16_t srej_save_req_seq;
500 :
501 : /** @internal Retransmission Timer */
502 0 : struct k_work_delayable ret_work;
503 : /** @internal Monitor Timer */
504 0 : struct k_work_delayable monitor_work;
505 : #endif /* CONFIG_BT_L2CAP_RET_FC */
506 : };
507 :
508 : /** @brief L2CAP Channel operations structure.
509 : *
510 : * The object has to stay valid and constant for the lifetime of the channel.
511 : */
512 1 : struct bt_l2cap_chan_ops {
513 : /** @brief Channel connected callback
514 : *
515 : * If this callback is provided it will be called whenever the
516 : * connection completes.
517 : *
518 : * @param chan The channel that has been connected
519 : */
520 1 : void (*connected)(struct bt_l2cap_chan *chan);
521 :
522 : /** @brief Channel disconnected callback
523 : *
524 : * If this callback is provided it will be called whenever the
525 : * channel is disconnected, including when a connection gets
526 : * rejected.
527 : *
528 : * @param chan The channel that has been Disconnected
529 : */
530 1 : void (*disconnected)(struct bt_l2cap_chan *chan);
531 :
532 : /** @brief Channel encrypt_change callback
533 : *
534 : * If this callback is provided it will be called whenever the
535 : * security level changed (indirectly link encryption done) or
536 : * authentication procedure fails. In both cases security initiator
537 : * and responder got the final status (HCI status) passed by
538 : * related to encryption and authentication events from local host's
539 : * controller.
540 : *
541 : * @param chan The channel which has made encryption status changed.
542 : * @param status HCI status of performed security procedure caused
543 : * by channel security requirements. The value is populated
544 : * by HCI layer and set to 0 when success and to non-zero (reference to
545 : * HCI Error Codes) when security/authentication failed.
546 : */
547 1 : void (*encrypt_change)(struct bt_l2cap_chan *chan, uint8_t hci_status);
548 :
549 : /** @brief Channel alloc_seg callback
550 : *
551 : * If this callback is provided the channel will use it to allocate
552 : * buffers to store segments. This avoids wasting big SDU buffers with
553 : * potentially much smaller PDUs. If this callback is supplied, it must
554 : * return a valid buffer.
555 : *
556 : * @param chan The channel requesting a buffer.
557 : *
558 : * @return Allocated buffer.
559 : */
560 : struct net_buf *(*alloc_seg)(struct bt_l2cap_chan *chan);
561 :
562 : /** @brief Channel alloc_buf callback
563 : *
564 : * If this callback is provided the channel will use it to allocate
565 : * buffers to store incoming data. Channels that requires segmentation
566 : * must set this callback.
567 : * If the application has not set a callback the L2CAP SDU MTU will be
568 : * truncated to @ref BT_L2CAP_SDU_RX_MTU.
569 : *
570 : * @param chan The channel requesting a buffer.
571 : *
572 : * @return Allocated buffer.
573 : */
574 : struct net_buf *(*alloc_buf)(struct bt_l2cap_chan *chan);
575 :
576 : /** @brief Channel recv callback
577 : *
578 : * @param chan The channel receiving data.
579 : * @param buf Buffer containing incoming data.
580 : *
581 : * @note This callback is mandatory, unless
582 : * @kconfig{CONFIG_BT_L2CAP_SEG_RECV} is enabled and seg_recv is
583 : * supplied.
584 : *
585 : * If the application returns @c -EINPROGRESS, the application takes
586 : * ownership of the reference in @p buf. (I.e. This pointer value can
587 : * simply be given to @ref bt_l2cap_chan_recv_complete without any
588 : * calls @ref net_buf_ref or @ref net_buf_unref.)
589 : *
590 : * @return 0 in case of success or negative value in case of error.
591 : * @return -EINPROGRESS in case where user has to confirm once the data
592 : * has been processed by calling
593 : * @ref bt_l2cap_chan_recv_complete passing back
594 : * the buffer received with its original user_data
595 : * which contains the number of segments/credits
596 : * used by the packet.
597 : */
598 1 : int (*recv)(struct bt_l2cap_chan *chan, struct net_buf *buf);
599 :
600 : /** @brief Channel sent callback
601 : *
602 : * This callback will be called once the controller marks the SDU
603 : * as completed. When the controller does so is implementation
604 : * dependent. It could be after the SDU is enqueued for transmission,
605 : * or after it is sent on air.
606 : *
607 : * @param chan The channel which has sent data.
608 : */
609 1 : void (*sent)(struct bt_l2cap_chan *chan);
610 :
611 : /** @brief Channel status callback
612 : *
613 : * If this callback is provided it will be called whenever the
614 : * channel status changes.
615 : *
616 : * @param chan The channel which status changed
617 : * @param status The channel status
618 : */
619 1 : void (*status)(struct bt_l2cap_chan *chan, atomic_t *status);
620 :
621 : /* @brief Channel released callback
622 : *
623 : * If this callback is set it is called when the stack has release all
624 : * references to the channel object.
625 : */
626 0 : void (*released)(struct bt_l2cap_chan *chan);
627 :
628 : /** @brief Channel reconfigured callback
629 : *
630 : * If this callback is provided it will be called whenever peer or
631 : * local device requested reconfiguration. Application may check
632 : * updated MTU and MPS values by inspecting chan->le endpoints.
633 : *
634 : * @param chan The channel which was reconfigured
635 : */
636 1 : void (*reconfigured)(struct bt_l2cap_chan *chan);
637 :
638 : #if defined(CONFIG_BT_L2CAP_SEG_RECV)
639 : /** @brief Handle L2CAP segments directly
640 : *
641 : * This is an alternative to @ref bt_l2cap_chan_ops.recv. They cannot
642 : * be used together.
643 : *
644 : * This is called immediately for each received segment.
645 : *
646 : * Unlike with @ref bt_l2cap_chan_ops.recv, flow control is explicit.
647 : * Each time this handler is invoked, the remote has permanently used
648 : * up one credit. Use @ref bt_l2cap_chan_give_credits to give credits.
649 : *
650 : * The start of an SDU is marked by `seg_offset == 0`. The end of an
651 : * SDU is marked by `seg_offset + seg->len == sdu_len`.
652 : *
653 : * The stack guarantees that:
654 : * - The sender had the credit.
655 : * - The SDU length does not exceed MTU.
656 : * - The segment length does not exceed MPS.
657 : *
658 : * Additionally, the L2CAP protocol is such that:
659 : * - Segments come in order.
660 : * - SDUs cannot be interleaved or aborted halfway.
661 : *
662 : * @note With this alternative API, the application is responsible for
663 : * setting the RX MTU and MPS. The MPS must not exceed @ref BT_L2CAP_RX_MTU.
664 : *
665 : * @param chan The receiving channel.
666 : * @param sdu_len Byte length of the SDU this segment is part of.
667 : * @param seg_offset The byte offset of this segment in the SDU.
668 : * @param seg The segment payload.
669 : */
670 1 : void (*seg_recv)(struct bt_l2cap_chan *chan, size_t sdu_len,
671 : off_t seg_offset, struct net_buf_simple *seg);
672 : #endif /* CONFIG_BT_L2CAP_SEG_RECV */
673 : };
674 :
675 : /**
676 : * @brief Headroom needed for outgoing L2CAP PDUs.
677 : */
678 1 : #define BT_L2CAP_CHAN_SEND_RESERVE (BT_L2CAP_BUF_SIZE(0))
679 :
680 : /**
681 : * @brief Headroom needed for outgoing L2CAP SDUs.
682 : */
683 1 : #define BT_L2CAP_SDU_CHAN_SEND_RESERVE (BT_L2CAP_SDU_BUF_SIZE(0))
684 :
685 : /** @brief L2CAP Server structure. */
686 1 : struct bt_l2cap_server {
687 : /** @brief Server PSM.
688 : *
689 : * For LE, possible values:
690 : * 0 A dynamic value will be auto-allocated when
691 : * bt_l2cap_server_register() is called.
692 : *
693 : * 0x0001-0x007f Standard, Bluetooth SIG-assigned fixed values.
694 : *
695 : * 0x0080-0x00ff Dynamically allocated. May be pre-set by the
696 : * application before server registration (not
697 : * recommended however), or auto-allocated by the
698 : * stack if the app gave 0 as the value.
699 : *
700 : * For BR, possible values:
701 : *
702 : * The PSM field is at least two octets in length. All PSM values shall have the least
703 : * significant bit of the most significant octet equal to 0 and the least significant bit
704 : * of all other octets equal to 1.
705 : *
706 : * 0 A dynamic value will be auto-allocated when
707 : * bt_l2cap_br_server_register() is called.
708 : *
709 : * 0x0001-0x0eff Standard, Bluetooth SIG-assigned fixed values.
710 : *
711 : * > 0x1000 Dynamically allocated. May be pre-set by the
712 : * application before server registration (not
713 : * recommended however), or auto-allocated by the
714 : * stack if the app gave 0 as the value.
715 : */
716 1 : uint16_t psm;
717 :
718 : /** Required minimum security level */
719 1 : bt_security_t sec_level;
720 :
721 : /** @brief Server accept callback
722 : *
723 : * This callback is called whenever a new incoming connection requires
724 : * authorization.
725 : *
726 : * @warning It is the responsibility of this callback to zero out the
727 : * parent of the chan object.
728 : *
729 : * @param conn The connection that is requesting authorization
730 : * @param server Pointer to the server structure this callback relates to
731 : * @param chan Pointer to received the allocated channel
732 : *
733 : * @return 0 in case of success or negative value in case of error.
734 : * @return -ENOMEM if no available space for new channel.
735 : * @return -EACCES if application did not authorize the connection.
736 : * @return -EPERM if encryption key size is too short.
737 : */
738 1 : int (*accept)(struct bt_conn *conn, struct bt_l2cap_server *server,
739 : struct bt_l2cap_chan **chan);
740 :
741 0 : sys_snode_t node;
742 : };
743 :
744 : /** @brief Register L2CAP server.
745 : *
746 : * Register L2CAP server for a PSM, each new connection is authorized using
747 : * the accept() callback which in case of success shall allocate the channel
748 : * structure to be used by the new connection.
749 : *
750 : * For fixed, SIG-assigned PSMs (in the range 0x0001-0x007f) the PSM should
751 : * be assigned to server->psm before calling this API. For dynamic PSMs
752 : * (in the range 0x0080-0x00ff) server->psm may be pre-set to a given value
753 : * (this is however not recommended) or be left as 0, in which case upon
754 : * return a newly allocated value will have been assigned to it. For
755 : * dynamically allocated values the expectation is that it's exposed through
756 : * a GATT service, and that's how L2CAP clients discover how to connect to
757 : * the server.
758 : *
759 : * @param server Server structure.
760 : *
761 : * @return 0 in case of success or negative value in case of error.
762 : */
763 1 : int bt_l2cap_server_register(struct bt_l2cap_server *server);
764 :
765 : /** @brief Register L2CAP server on BR/EDR oriented connection.
766 : *
767 : * Register L2CAP server for a PSM, each new connection is authorized using
768 : * the accept() callback which in case of success shall allocate the channel
769 : * structure to be used by the new connection.
770 : *
771 : * For fixed, SIG-assigned PSMs (in the range 0x0001-0x0eff) the PSM should
772 : * be assigned to server->psm before calling this API. For dynamic PSMs
773 : * (in the range 0x1000-0xffff) server->psm may be pre-set to a given value
774 : * (this is however not recommended) or be left as 0, in which case upon
775 : * return a newly allocated value will have been assigned to it. For
776 : * dynamically allocated values the expectation is that it's exposed through
777 : * a SDP record, and that's how L2CAP clients discover how to connect to
778 : * the server.
779 : *
780 : * @param server Server structure.
781 : *
782 : * @return 0 in case of success or negative value in case of error.
783 : */
784 1 : int bt_l2cap_br_server_register(struct bt_l2cap_server *server);
785 :
786 : /** @brief Unregister L2CAP server on BR/EDR oriented connection.
787 : *
788 : * Unregister L2CAP server for a PSM.
789 : *
790 : * @param server Server structure.
791 : *
792 : * @return 0 in case of success or negative value in case of error.
793 : */
794 1 : int bt_l2cap_br_server_unregister(struct bt_l2cap_server *server);
795 :
796 : /** @brief Connect Enhanced Credit Based L2CAP channels
797 : *
798 : * Connect up to 5 L2CAP channels by PSM, once the connection is completed
799 : * each channel connected() callback will be called. If the connection is
800 : * rejected disconnected() callback is called instead.
801 : *
802 : * @warning It is the responsibility of the caller to zero out the
803 : * parents of the chan objects.
804 : *
805 : * @param conn Connection object.
806 : * @param chans Array of channel objects.
807 : * @param psm Channel PSM to connect to.
808 : *
809 : * @return 0 in case of success or negative value in case of error.
810 : */
811 1 : int bt_l2cap_ecred_chan_connect(struct bt_conn *conn,
812 : struct bt_l2cap_chan **chans, uint16_t psm);
813 :
814 : /** @brief Reconfigure Enhanced Credit Based L2CAP channels
815 : *
816 : * Reconfigure up to 5 L2CAP channels. Channels must be from the same bt_conn.
817 : * Once reconfiguration is completed each channel reconfigured() callback will
818 : * be called. MTU cannot be decreased on any of provided channels.
819 : *
820 : * @param chans Array of channel objects. Null-terminated. Elements after the
821 : * first 5 are silently ignored.
822 : * @param mtu Channel MTU to reconfigure to.
823 : *
824 : * @return 0 in case of success or negative value in case of error.
825 : */
826 1 : int bt_l2cap_ecred_chan_reconfigure(struct bt_l2cap_chan **chans, uint16_t mtu);
827 :
828 : /** @brief Reconfigure Enhanced Credit Based L2CAP channels
829 : *
830 : * Experimental API to reconfigure L2CAP ECRED channels with explicit MPS and
831 : * MTU values.
832 : *
833 : * Pend a L2CAP ECRED reconfiguration for up to 5 channels. All provided
834 : * channels must share the same @ref bt_conn.
835 : *
836 : * This API cannot decrease the MTU of any channel, and it cannot decrease the
837 : * MPS of any channel when more than one channel is provided.
838 : *
839 : * There is no dedicated callback for this operation, but whenever a peer
840 : * responds to a reconfiguration request, each affected channel's
841 : * reconfigured() callback is invoked.
842 : *
843 : * This function may block.
844 : *
845 : * @warning Known issue: The implementation returns -EBUSY if there already is
846 : * an ongoing reconfigure operation on the same connection. The caller may try
847 : * again later. There is no event signaling when the existing operation
848 : * finishes.
849 : *
850 : * @warning Known issue: The implementation returns -ENOMEM when unable to
851 : * allocate. The caller may try again later. There is no event signaling the
852 : * availability of buffers.
853 : *
854 : * @kconfig_dep{CONFIG_BT_L2CAP_RECONFIGURE_EXPLICIT}
855 : *
856 : * @param chans Array of channels to reconfigure. Must be non-empty and
857 : * contain at most 5 (@ref BT_L2CAP_ECRED_CHAN_MAX_PER_REQ)
858 : * elements.
859 : * @param chan_count Number of channels in the array.
860 : * @param mtu Desired MTU. Must be at least @ref BT_L2CAP_ECRED_MIN_MTU.
861 : * @param mps Desired MPS. Must be in range @ref BT_L2CAP_ECRED_MIN_MPS
862 : * to @ref BT_L2CAP_RX_MTU.
863 : *
864 : * @retval 0 Successfully pended operation.
865 : * @retval -EINVAL Bad arguments. See above requirements.
866 : * @retval -ENOTCONN Connection object is not in connected state.
867 : * @retval -EBUSY Another outgoing reconfiguration is pending on the same
868 : * connection.
869 : * @retval -ENOMEM Host is out of buffers.
870 : */
871 1 : int bt_l2cap_ecred_chan_reconfigure_explicit(struct bt_l2cap_chan **chans, size_t chan_count,
872 : uint16_t mtu, uint16_t mps);
873 :
874 : /** @brief Connect L2CAP channel
875 : *
876 : * Connect L2CAP channel by PSM, once the connection is completed channel
877 : * connected() callback will be called. If the connection is rejected
878 : * disconnected() callback is called instead.
879 : * Channel object passed (over an address of it) as second parameter shouldn't
880 : * be instantiated in application as standalone. Instead of, application should
881 : * create transport dedicated L2CAP objects, i.e. type of bt_l2cap_le_chan for
882 : * LE and/or type of bt_l2cap_br_chan for BR/EDR. Then pass to this API
883 : * the location (address) of bt_l2cap_chan type object which is a member
884 : * of both transport dedicated objects.
885 : *
886 : * @warning It is the responsibility of the caller to zero out the
887 : * parent of the chan object.
888 : *
889 : * @param conn Connection object.
890 : * @param chan Channel object.
891 : * @param psm Channel PSM to connect to.
892 : *
893 : * @return 0 in case of success or negative value in case of error.
894 : */
895 1 : int bt_l2cap_chan_connect(struct bt_conn *conn, struct bt_l2cap_chan *chan,
896 : uint16_t psm);
897 :
898 : /** @brief Disconnect L2CAP channel
899 : *
900 : * Disconnect L2CAP channel, if the connection is pending it will be
901 : * canceled and as a result the channel disconnected() callback is called.
902 : * Regarding to input parameter, to get details see reference description
903 : * to bt_l2cap_chan_connect() API above.
904 : *
905 : * @param chan Channel object.
906 : *
907 : * @return 0 in case of success or negative value in case of error.
908 : */
909 1 : int bt_l2cap_chan_disconnect(struct bt_l2cap_chan *chan);
910 :
911 : /** @brief Send data to L2CAP channel
912 : *
913 : * Send data from buffer to the channel. If credits are not available, buf will
914 : * be queued and sent as and when credits are received from peer.
915 : * Regarding to first input parameter, to get details see reference description
916 : * to bt_l2cap_chan_connect() API above.
917 : *
918 : * Network buffer fragments (ie `buf->frags`) are not supported.
919 : *
920 : * When sending L2CAP data over an BR/EDR connection the application is sending
921 : * L2CAP PDUs. The application is required to have reserved
922 : * @ref BT_L2CAP_CHAN_SEND_RESERVE bytes in the buffer before sending.
923 : * The application should use the BT_L2CAP_BUF_SIZE() helper to correctly
924 : * size the buffers for the for the outgoing buffer pool.
925 : *
926 : * When sending L2CAP data over an LE connection the application is sending
927 : * L2CAP SDUs. The application shall reserve
928 : * @ref BT_L2CAP_SDU_CHAN_SEND_RESERVE bytes in the buffer before sending.
929 : *
930 : * The application can use the BT_L2CAP_SDU_BUF_SIZE() helper to correctly size
931 : * the buffer to account for the reserved headroom.
932 : *
933 : * When segmenting an L2CAP SDU into L2CAP PDUs the stack will first attempt to
934 : * allocate buffers from the channel's `alloc_seg` callback and will fallback
935 : * on the stack's global buffer pool (sized
936 : * @kconfig{CONFIG_BT_L2CAP_TX_BUF_COUNT}).
937 : *
938 : * @warning The buffer's user_data _will_ be overwritten by this function. Do
939 : * not store anything in it. As soon as a call to this function has been made,
940 : * consider ownership of user_data transferred into the stack.
941 : *
942 : * @note Buffer ownership is transferred to the stack in case of success, in
943 : * case of an error the caller retains the ownership of the buffer.
944 : *
945 : * @return 0 in case of success or negative value in case of error.
946 : * @return -EINVAL if `buf` or `chan` is NULL.
947 : * @return -EINVAL if `chan` is not either BR/EDR or LE credit-based.
948 : * @return -EINVAL if buffer doesn't have enough bytes reserved to fit header.
949 : * @return -EINVAL if buffer's reference counter != 1
950 : * @return -EMSGSIZE if `buf` is larger than `chan`'s MTU.
951 : * @return -ENOTCONN if underlying conn is disconnected.
952 : * @return -ESHUTDOWN if L2CAP channel is disconnected.
953 : * @return -other (from lower layers) if chan is BR/EDR.
954 : */
955 1 : int bt_l2cap_chan_send(struct bt_l2cap_chan *chan, struct net_buf *buf);
956 :
957 : /** @brief Give credits to the remote
958 : *
959 : * Only available for channels using @ref bt_l2cap_chan_ops.seg_recv.
960 : * @kconfig{CONFIG_BT_L2CAP_SEG_RECV} must be enabled to make this function
961 : * available.
962 : *
963 : * Each credit given allows the peer to send one segment.
964 : *
965 : * This function depends on a valid @p chan object. Make sure to
966 : * default-initialize or memset @p chan when allocating or reusing it for new
967 : * connections.
968 : *
969 : * Adding zero credits is not allowed.
970 : *
971 : * Credits can be given before entering the @ref BT_L2CAP_CONNECTING state.
972 : * Doing so will adjust the 'initial credits' sent in the connection PDU.
973 : *
974 : * Must not be called while the channel is in @ref BT_L2CAP_CONNECTING state.
975 : *
976 : * @return 0 in case of success or negative value in case of error.
977 : */
978 1 : int bt_l2cap_chan_give_credits(struct bt_l2cap_chan *chan, uint16_t additional_credits);
979 :
980 : /** @brief Complete receiving L2CAP channel data
981 : *
982 : * Complete the reception of incoming data. This shall only be called if the
983 : * channel recv callback has returned -EINPROGRESS to process some incoming
984 : * data. The buffer shall contain the original user_data as that is used for
985 : * storing the credits/segments used by the packet.
986 : *
987 : * @param chan Channel object.
988 : * @param buf Buffer containing the data.
989 : *
990 : * @return 0 in case of success or negative value in case of error.
991 : */
992 1 : int bt_l2cap_chan_recv_complete(struct bt_l2cap_chan *chan,
993 : struct net_buf *buf);
994 :
995 : #ifdef __cplusplus
996 : }
997 : #endif
998 :
999 : /**
1000 : * @}
1001 : */
1002 :
1003 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_L2CAP_H_ */
|
