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